Skip to content

Configuration Sync

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 12 configuration types from your Zendesk instance:

Business Rules

  1. Triggers — rules that execute when tickets are created or updated
  2. Automations — time-based rules that run on schedule

Agent Tools

  1. Macros — pre-built sets of actions for agents
  2. Views — filtered ticket lists for agents and admins

Custom Fields

  1. Ticket Fields — custom fields on tickets
  2. User Fields — custom fields on user profiles
  3. Organization Fields — custom fields on organisations

Service Management

  1. SLA Policies — service level agreement rules and targets

Infrastructure

  1. Groups — agent group definitions
  2. Brands — brand configurations (for multi-brand instances)
  3. Schedules — business hour schedules
  4. Ticket Forms — ticket submission form configurations

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).

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 eight
  • 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:

Sync Cadence Best For
After every change Tracking every configuration update, strict audit requirements
Daily Active development, frequent Zendesk changes
Weekly Stable production environments, periodic monitoring
Before/after deployments Controlled release processes, comparing specific changes

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

Error Cause Solution
Connection not found Invalid connection ID Check the connection exists and you have access
Authentication failed Expired or invalid credentials Re-authenticate the connection
API rate limit Too many requests to Zendesk Wait a few minutes and retry
Forbidden Insufficient permissions Ensure your Zendesk user has admin access
Network timeout Large instance or slow network Retry, or sync individual types

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