How Syncs Work

A sync is the process of transferring data between connected systems based on your mapping configuration. This guide explains the sync lifecycle, what happens during a sync, and how to monitor sync health.

The Sync Lifecycle

Every sync follows these stages:

1. PENDING    → Sync is queued and waiting to start
2. RUNNING    → Sync is actively processing records
3. COMPLETED  → Sync finished successfully
   PARTIAL    → Sync finished but some records failed
   FAILED     → Sync could not complete

What Happens During a Sync

Stage 1: Initialization

FluxCascade prepares for the sync:

1. Load the mapping configuration
2. Verify connections to both systems are active
3. Retrieve access tokens (refreshing if needed)
4. Determine which records need syncing

Stage 2: Data Fetch

Records are retrieved from the source system:

• Full Sync: All records matching the mapping criteria
• Incremental Sync: Only records modified since last sync
• Webhook-Triggered: The specific record(s) that changed

Stage 3: Transformation

For each record, FluxCascade:

1. Maps source fields to target fields
2. Applies configured transformations
3. Validates required fields are present
4. Checks for conflicts (bidirectional syncs)

Stage 4: Upsert

Records are written to the target system:

• Create: New records not found in target
• Update: Existing records with changes

FluxCascade uses "upsert" logic to handle both cases automatically.

Stage 5: Completion

After processing all records:

1. Success/failure counts are tallied
2. Sync status is updated
3. Audit log is written
4. Notifications are sent (if configured)

Sync Types

Manual Sync

Triggered on-demand by clicking Sync Now:

• Useful for testing new mappings
• Good for one-time data migrations
• Full control over when syncs occur

Scheduled Sync

Runs automatically on a schedule:

See Scheduling for configuration details.

Webhook-Triggered Sync

Runs immediately when data changes:

• Near real-time synchronization
• Only processes changed records
• Most efficient for active data

See Webhooks for setup instructions.

Sync Statistics

Each completed sync reports:

Viewing Sync History

Syncs Page

Navigate to Syncs in the sidebar to see:

• All recent sync jobs across mappings
• Filter by status, mapping, or date range
• Quick stats and status indicators

Mapping Detail View

Click on a mapping to see:

• Sync history for that specific mapping
• Success rate over time
• Last sync details

Individual Sync Details

Click on any sync job to view:

• Full statistics breakdown
• Record-by-record results
• Error details for failed records
• Timestamps and duration

Sync Logs

Each sync generates detailed logs:

Event Log

Chronological events during the sync:

14:30:00 - Sync started
14:30:01 - Connected to HubSpot
14:30:01 - Connected to Jobber
14:30:02 - Fetched 150 contacts from HubSpot
14:30:05 - Processed 150 records
14:30:05 - Created 12, Updated 45, Skipped 93
14:30:05 - Sync completed successfully

Error Log

Details on failed records:

Record: john@example.com
Error: Invalid phone format - could not parse "(555) ABC-1234"
Field: phone
Action: Skipped field, synced other fields

Running a Manual Sync

From the Syncs Page

1. Click + New Sync
2. Select the mapping to sync
3. Choose sync options:
   • Full sync or incremental
   • Test mode (preview only)
4. Click Start Sync

From a Mapping

1. Open the mapping
2. Click the Sync Now button (⚡)
3. Confirm to start

From the Dashboard

Use the quick sync buttons on your dashboard to trigger syncs for active mappings.

Sync Performance

Factors Affecting Speed

• Record count: More records = longer sync
• Field count: More fields per record = more processing
• API rate limits: External systems may throttle requests
• Transformations: Complex transforms add processing time

Optimization Tips

1. Use incremental syncs – Only sync changed records
2. Enable webhooks – Process records as they change
3. Limit fields – Only map fields you need
4. Schedule wisely – Balance frequency with performance

Next Steps

• Scheduling – Configure automatic syncs
• Webhooks – Enable real-time sync
• Error Handling – Handle sync failures