How configuration sync works

Configuration sync is how Configly pulls your Zendesk configuration and saves it as a snapshot. This creates a historical record you can compare, search, and analyse.

What Gets Synced

Configly syncs up to 41 configuration types from your Zendesk instance, organised into 7 groups matching Zendesk Admin Centre:

Objects & Rules (18 types)

Triggers, Automations, Macros, Views, SLA Policies, Trigger Categories, Ticket Fields, Ticket Forms, Custom Statuses, Tags, Ticket Settings, Routing Attributes, Routing Attribute Values, Queues, Custom Objects, Custom Object Fields, Support Addresses, Dynamic Content

People (4 types)

Groups, User Fields, Organisation Fields, Custom Roles

Channels (3 types)

Webhooks, Targets, Sharing Agreements

Account (6 types)

Brands, Schedules, Locales, Account Settings, OAuth Clients, Workspaces

Apps & Integrations (4 types)

App Installations, Apps Owned, OAuth Global Clients, Resource Collections

Guide (6 types)

Articles, Sections, Categories, Themes, User Segments, Permission Groups

How Syncing Works

Full Sync

A full sync downloads all configuration types and saves them with a shared version timestamp.

When to use full sync:

• Setting up a new connection for the first time
• After making multiple changes across different configuration types
• Before comparing historical configuration to see all changes
• Regular maintenance syncs (daily/weekly)

What happens:

1. Configly connects to Zendesk using your saved credentials
2. Makes API calls to fetch each configuration type
3. Handles pagination automatically (for large result sets)
4. Saves all data as snapshots with the same version timestamp
5. Extracts dependencies (which objects reference which fields/groups/tags)
6. Updates your dashboard with the new data

How long it takes:

• Small instance (< 100 objects/type): 5–30 seconds
• Medium instance (100–500 objects/type): 30–90 seconds
• Large instance (500+ objects/type): 2–5 minutes

Selective Sync

A selective sync downloads just one configuration type (e.g., only Triggers). You can trigger a selective sync directly from the dashboard by clicking the sync button on any type row.

When to use selective sync:

• You only changed one type of object in Zendesk
• You want to quickly check if a trigger or macro was updated
• You're troubleshooting a specific configuration type

What happens:

1. Configly syncs only the selected configuration type
2. Creates a snapshot for just that type
3. Uses a new version timestamp (not shared with other types)

Trade-offs:

• Faster - Only downloads one type instead of all forty-one
• Narrower comparison - Can only diff that specific type against historical snapshots of the same type
• Good for focused updates - Ideal when you know exactly what changed

Pagination Handling

Zendesk's API returns results in pages (typically 100 objects per page). Configly automatically:

• Requests the first page
• Checks if there are more pages
• Fetches all remaining pages until complete
• Combines all pages into one snapshot

You don't need to do anything special - pagination is handled transparently. Whether you have 10 triggers or 1,000 triggers, Configly gets them all.

Sync Frequency

How often should you sync?

It depends on your workflow:

Recommendations:

• During development: Sync before and after making changes
• In production: Set up a regular cadence (daily or weekly) for historical tracking
• Before major changes: Always sync to capture the "before" state

Versioning and Snapshots

Each sync creates a snapshot with a version timestamp:

Version: 2026-02-02T14:30:00.000Z

This version groups related snapshots together:

• Full sync → All config types get the same version
• Selective sync → Only that type gets a new version

Why versions matter:

• You can compare any two versions to see what changed
• Each version is a complete historical record
• You can view your configuration as it existed at any point in time

What Happens After Sync

Once a sync completes:

1. Snapshots saved — all configuration data is stored in Configly's database
2. Dependencies extracted — Configly analyses the configuration to find which triggers reference which fields, which macros use which groups, which views display which custom fields, and what tags are referenced in conditions
3. Dashboard updated — counts, active/inactive breakdowns, and "last synced" times refresh
4. Ready for comparison — you can now diff this version against previous versions

Authentication and Credentials

Configly uses the authentication method you configured when setting up the connection:

API Token Method

• Uses your email + Zendesk API token
• Tokens are encrypted at rest
• Never expire (unless revoked in Zendesk)

OAuth Method

• Uses OAuth 2.0 access tokens
• Tokens expire after a period (typically 1-24 hours)
• Configly automatically refreshes expired tokens using the refresh token
• If refresh fails, you'll need to re-authenticate

Best practice: If you see authentication errors, check your connection settings and re-authenticate if needed.

Sync Errors and Troubleshooting

Common Error Messages

Partial Failures

If one configuration type fails during a full sync, the others continue:

• You'll see which types succeeded and which failed
• Failed types can be retried individually
• Successful types are still saved as snapshots

Performance Tips

For Large Zendesk Instances

If you have many objects (500+ per type):

1. Use selective sync when possible - Sync only what changed
2. Schedule syncs during off-hours - Avoid peak API usage times
3. Don't sync too frequently - Once per day is usually sufficient

For Slow Connections

If syncing is taking a long time:

1. Check your internet connection - Sync requires downloading data from Zendesk
2. Sync individual types - Instead of full sync, sync types one at a time
3. Be patient - Large configuration sets take time to download and process

Next Steps

• Compare snapshots — see what changed between sync versions
• View dependencies — understand how objects are connected
• Dashboard overview — monitor sync history and status
• Global search — find objects across all types