Workflow data synchronisation

Workflow data synchronisation keeps selected records aligned across applications as they change. Define which records qualify, how they are paired, who owns each shared value, and what create, update, delete and restore should do. Then decide how missed changes will be found and how the resulting records will be checked. A setting labelled “two-way sync” does not make those decisions for you.

Define what must agree

Consider a customer record shared by a sales system and a service system. Sales might own the account owner, while service owns support status; both may display a contact name. Record the authority for each shared field before configuring movement between the systems.

For a two-way sync, HubSpot Data Sync stores record IDs and matching identifiers in its index and keeps it up to date during syncing. Its matching options vary by connected app and object.

Check matching criteria against the data

HubSpot’s default matching identifiers vary by object: contacts and leads use email address, companies use company name or domain, and products use SKU or name. These defaults are not available for every connected app or object; check the options for the specific sync.

Matching is separate from field mappings and filters. In supported apps, HubSpot normalises non-unique name fields by ignoring capitalisation, special characters and punctuation. If you choose a custom identifier, only text fields can be selected, and the selected property alone determines the match; an unsuitable choice can leave records unmatched or create duplicates.

Choose direction and field authority

One-way sync fits when one system supplies a value and the other receives it. Two-way sync fits when edits on both sides are legitimate and there is a rule for competing changes. A record may move both ways while a particular field moves only one way.

Check the selected connector’s actual mappings and write permissions. HubSpot documents one-way field mappings where connected-app API limits or read-only fields prevent a write; creating and customising mappings requires an eligible Data Hub subscription.

An update written by the sync can also appear in a later change feed. Identify it where the source contract permits so it does not circulate as a fresh business edit. If both sides changed a value since the last confirmed common state, apply the field’s authority rule or hold it for review. Event arrival order alone does not establish which decision should prevail.

Treat deletion as a separate decision

Absence from a list is not proof of deletion: a filter, permission change or incomplete scan may hide a record. Use the source’s documented change signal when available.

Google Calendar incremental sync includes deleted entries for its client store. Microsoft Graph delta query can help applications discover deleted entities. Use each source’s change signal as input to your own deletion handling.

Choose whether an authorised deletion removes, archives or leaves the paired record, and whether a restore reconnects or recreates it. Retain enough deletion history to prevent a later refresh from recreating a record deliberately removed.

Make recovery observable

Read changes from a saved checkpoint, resolve each record’s identity, apply permitted changes and account for every required page before advancing the checkpoint. Google Calendar supplies the next sync token on the final page. Microsoft Graph returns @odata.nextLink while pages remain and @odata.deltaLink when a round is complete.

A checkpoint can become invalid. Google Calendar documents that an invalidated sync token can require a full sync of the client’s calendar state. Those instructions do not authorise overwriting another application’s independently edited records. Preserve pairings and unresolved decisions, compare both sides under the agreed rules, and confirm the destination state before normal writes resume.

A useful acceptance check compares paired IDs and values after a create, an authorised edit on each side, competing edits, deletion, restore and a missed-change interval. Record expected states before exercising those cases. A completed sync run alone does not establish that the records agree.

Separate initial indexing from change checks

HubSpot Data Sync first indexes existing records in both apps, then moves to incremental checks for new or changed records. Its internal index compares records against stored copies, and the sync engine examines the full record when an update occurs. Indexing can take time at startup, but the index can also help recover dropped or errored API calls.

Microsoft Graph delta query uses a pull model to retrieve changes without rereading the full resource on every request; change notifications use a push model. An initial delta query returns the current collection state, not a complete history: updates made before that first request appear as their latest state, and resources deleted before it are not returned.

A source can also invalidate a saved cursor for reasons unrelated to a business-record edit. Google Calendar identifies token expiry and changes to related access-control lists as possible reasons for invalidation. Treat the source’s reset instruction as a request to re-establish its view of the collection, not as evidence that another application’s records should be replaced.

Key Sync Tools and Their Capabilities