Sync Engine
Real-time bidirectional sync between Salesforce orgs. Vendor and client orgs stay in sync automatically — work items, time logs, comments, and files flow between orgs without manual data entry. Built on a push/pull architecture with echo suppression, multi-tenant isolation, and a GlobalSourceId kill-switch to prevent infinite loops.
Core Architecture
Push Flow
When a record changes in the source org, a Sync_Item__c record is enqueued with the payload, target entity, and object type. The SyncItemProcessor queueable picks up queued items and delivers them to the target org via REST callout. On successful delivery, a DeliverySync__e platform event is published so dashboards and external subscribers can react in real time. Processing is asynchronous and non-blocking — users never wait for sync to complete.
Pull Flow
The DeliveryHubPoller scheduled job runs on a configurable interval and calls the @HttpGet /changes endpoint on connected orgs. This catches anything the push flow missed — network blips, governor limit hits, or items queued while the processor was already running. Pull is the safety net that guarantees eventual consistency.
Echo Suppression
When Org A sends a record to Org B, Org B’s trigger fires and would normally try to sync that same record back to Org A — creating an infinite loop. The engine prevents this with a blockedOrigins set and the ignoreOrigin() method in SyncEngine static memory. Inbound records are tagged so the outbound trigger knows to skip them.
Two-Step Dedup
The SyncItemIngestor resolves duplicates in two passes. First, it checks the Request bridge — the in-flight batch of items being processed — for a matching record. If no match, it falls back to the Ledger — the full history of previously synced items. This two-step approach handles both rapid-fire updates and historical re-syncs without creating duplicates.
Multi-Tenant Isolation
Every sync route is scoped to a NetworkEntity. The EntityTypePk__c field on each routing rule enforces directionality: Vendor-type entities only send to Client-type entities, and vice versa. Data never leaks between unrelated orgs. Each tenant’s sync traffic is completely isolated at the query level.
GlobalSourceId Kill-Switch
Every synced record is stamped with a GlobalSourceIdTxt__c on creation — a unique identifier that tracks where the record originated. When the sync engine evaluates a routing target, it checks whether the target matches the GlobalSourceId. If it does, routing is aborted. This is the final safeguard against infinite sync loops, even across complex multi-hop chains.
Sync Reconciler
A scheduled reconciliation process that automatically detects drift between connected orgs. The Reconciler compares record states (field values, timestamps, sync status) across org pairs, identifies mismatches caused by missed pushes, failed retries, or edge-case race conditions, and queues self-healing corrections. Each reconciliation run produces a full audit log showing what was checked, what drifted, and what was corrected — ensuring eventual consistency without manual intervention.
Self-Healing Receiver (v0.161+)
Sync updates from a sender whose bridge stored a stale (deleted) local-record Id used to silently no-op on the receiver — Database.update against a deleted Id returns success without an exception, so the sender marked the item Synced and the bridge stayed broken indefinitely. Receivers now validate the target record exists before processing and fall back to the WorkItem ledger if the local Id is missing. Production drift between connected orgs is now self-correcting at the receiver, not just the reconciler. (PR #611)
Per-Event Echo Suppression (v0.162+)
The X-Global-Source-Id echo check used to query for ANY outbound SyncItem with that source id — but GlobalSourceId is a per-record identifier, not a per-event one. Once any work item was synced bidirectionally even once, every subsequent legitimate inbound from the partner org was permanently classified as an echo and dropped. The check now uses a time-window scope so legitimate later updates pass through while the loop-prevention guarantee holds. (PR #612)
Failed-Sync Dismissal + Auto-Aging
Sync Health panel now lets admins explicitly dismiss known-bad failed syncs (e.g. historical drift from decommissioned scratch URLs) so they don't clutter the dashboard. A schedulable job auto-ages dismissed failures off the panel after a configurable retention window. Surfaces real signal in the dashboard while keeping the audit trail intact. (PR #616)
How a Sync Happens
From a user edit in the source org to a synced record in the target org — four steps, fully automatic.
Record Changes
A user edits a WorkItem, logs time, or posts a comment in the source org. The platform trigger fires and hands the change to SyncEngine.
Enqueue
SyncEngine evaluates routing rules, checks echo suppression and the GlobalSourceId kill-switch, then creates a Sync_Item__c record with status Queued for each valid target.
Process
SyncItemProcessor (a queueable) picks up queued items, serializes the payload, injects the X-Global-Source-Id HTTP header, and makes the REST callout to the target org.
Ingest
The target org’s SyncItemIngestor receives the payload, runs two-step dedup, maps fields (stripping remote IDs), and upserts the record. Echo suppression blocks the outbound trigger from re-syncing.
Data Flow
The sync engine supports complex multi-org topologies. Here is the typical vendor-client chain.
Retry & Error Handling
The sync engine is designed for resilience. Failed items are retried automatically, and admins have full visibility into sync health.
Automatic Retry
Failed sync items are retried up to 3 times with increasing backoff. Each attempt is logged with a timestamp and error message on the Sync_Item__c record. Items that exhaust all retries are marked as Failed.
Sync Health Dashboard
The Sync Retry Panel LWC surfaces all failed and queued items grouped by object type. Admins see the error message, target entity, timestamp, and retry count — with a one-click retry button to reprocess any item.
Scheduler Safety Net
The DeliveryHubScheduler runs on a 5-minute interval and picks up any items stuck in Queued status. This covers edge cases where the queueable chain breaks due to governor limits, org downtime, or deployment locks.
Connection Handshake
Setting up a sync connection between two orgs takes four steps. The Getting Started wizard handles most of it automatically.
Initiate Connection
In the Getting Started wizard, enter the target org’s Site URL. Delivery Hub generates a shared API key and sends a handshake request to the remote org.
NetworkEntity Created
The remote org receives the handshake and auto-creates a NetworkEntity__c record with the source org’s details — name, endpoint, API key, and entity type. The connection starts in Pending status.
Admin Approval
An admin on the remote org reviews and approves the connection request. Once approved, the NetworkEntity status moves to Active and sync traffic begins flowing.
Sync Begins
With both sides Active, the push flow starts delivering changes in real time and the pull flow runs on schedule. The Sync Health dashboard confirms data is flowing.
Technical Details
The Sync Engine is built entirely on native Salesforce — Apex classes, platform events, queueable jobs, scheduled jobs, and custom objects. No external middleware.
| Component | Details |
|---|---|
| SyncEngine.cls | Core routing logic, echo suppression, GlobalSourceId kill-switch, blockedOrigins management |
| SyncItemProcessor.cls | Queueable that processes Sync_Item__c queue, REST callouts, X-Global-Source-Id header injection |
| SyncItemIngestor.cls | Inbound handler: two-step dedup, field mapping, cross-org ID resolution, upsert logic |
| DeliveryHubPoller.cls | Scheduled pull flow — calls @HttpGet /changes on connected orgs to catch missed pushes |
| DeliveryHubScheduler.cls | Global schedulable — 5-minute interval, picks up stuck Queued items, chains queueable processing |
| Sync_Item__c | Queue ledger object — stores payload, target entity, status, retry count, error message, timestamps |
| NetworkEntity__c | Tenant routing object — EntityTypePk__c (Vendor/Client/Both), API key, endpoint URL, active status |
| SyncReconciler.cls | Scheduled reconciliation — compares record states across orgs, detects drift, queues self-healing corrections with full audit trail |
What Gets Synced
The engine syncs the following object types between connected orgs. Each type has its own ingestor logic for field mapping and relationship resolution.
Work Items
Title, description, stage, priority, assignee, dates, and all custom fields
Work Logs
Hours, date, description, approval status — with cross-org WorkItem resolution
Comments
Body text, author, timestamp — threaded to the parent WorkItem
Files
ContentVersion attachments linked to WorkItems via ContentDocumentLink
Work Requests
Scope, rates, status, linked entity — the billing backbone
Network Entities
Connection metadata, entity type, and status for the sync graph
Platform Events
The sync engine publishes platform events at key points in the sync lifecycle. External systems, LWC components, and Apex triggers can subscribe for real-time updates.
DeliverySync__e
Published on sync completions and failures. Contains the sync item ID, target entity, object type, and status. The Sync Retry Panel LWC subscribes to this event to auto-refresh when items complete or fail, providing real-time visibility into sync health.
DeliveryWorkItemChange__e
Published when work items change stage, priority, or assignee — whether from direct user action or inbound sync. The Kanban board subscribes to auto-refresh when another user (or a sync from a remote org) moves a card.
DeliveryEscalation__e
Published when an escalation rule fires — SLA breaches, stuck items, or missing assignees. Drives bell notifications and email alerts through the DeliveryEscalationService.
DeliveryDocEvent__e
Published on document status transitions (Draft, Sent, Approved, Disputed, Paid). Enables the portal to show real-time invoice status updates and powers audit logging for the document lifecycle.
Ready to connect your orgs?
The Sync Engine is included in every Delivery Hub installation. Run the Getting Started wizard to establish your first connection in under 5 minutes.