Synchronize records safely
A reliable synchronization is a small state machine, not a loop that retries every HTTP call. Decide which system owns each value, map stable identities, use the API's replacement semantics intentionally, and combine signed webhooks with periodic reconciliation.
Choose ownership firstβ
Write down one direction for every synchronized concern:
| Concern | Possible owner | Why it matters |
|---|---|---|
| Object and attribute definitions | Tourfold administrator or provisioning service | Two schema writers can delete each other's declarative fields |
| Scalar attribute | Source system, Tourfold, or explicitly merged | Prevents update loops and last-writer surprises |
| Relationship edge | The object containing the declaring relationship attribute | Managed reverse fields cannot accept writes |
| Choice catalog | Schema owner | Record writers must not invent options |
| Deletion | One authoritative system plus reconciliation policy | A missed delete cannot be recovered from current records alone |
Do not make both systems authoritative for the same field unless you also define conflict resolution, clock assumptions, and loop suppression.
Build an identity mapβ
For each workspace, persist:
- workspace identity;
- object UUID and current slug;
- attribute UUIDs and current slugs;
- option/state UUIDs and current values; and
- Tourfold record UUID plus the source-system ID.
When possible, model the source-system ID as a unique text attribute. That gives you a readable point lookup:
GET /api/v2/objects/equipment/records/by/source_id?attribute_value=erp-4711
The record UUID is still the primary Tourfold identity. A business key can be renamed or reassigned by the source's own rules; preserve both in your mapping store.
Bootstrap the schemaβ
- Read the complete object catalog and locate objects by persisted ID first, slug second.
- Create missing objects and capture every server-assigned child ID.
- For declarative
PUT, send all attributes owned by that object and their existing IDs. - Omit managed reverse attributes from the target object's replacement document.
- Send
lock_version; on conflict, fetch and reconcile rather than replaying stale state.
If administrators are allowed to extend the same object, a provisioning service must preserve those fields or own a clearly separated object. Declarative replacement is intentionally not a patch.
Import new records atomicallyβ
For independent records, create one at a time and persist the returned UUID immediately. For connected
new records, use POST /api/v2/records/batch: it accepts 1β100 records across objects in one transaction.
{
"items": [
{
"object": "equipment",
"key": "equipment:erp-4711",
"data": {
"source_id": "erp-4711",
"name": "Rooftop HVAC Unit RTU-17",
"asset_tag": "AFS-RTU-17"
}
},
{
"object": "maintenance_request",
"key": "request:erp-9902",
"data": {
"source_id": "erp-9902",
"title": "Temperature too high on third floor",
"equipment": [{"ref": "equipment:erp-4711"}]
}
}
]
}
Request-local key values exist only inside the batch. A ref links to a sibling item. If any item,
constraint, or relationship is invalid, the entire batch rolls back and no returned item should be
recorded as created.
Batch create is atomic, but it is not an upsert and does not turn a repeated POST into an idempotent
operation. After a lost response, reconcile by your unique source key before deciding whether to create
again.
Apply updates with merge semanticsβ
Record PATCH follows JSON Merge Patch:
| Payload state | Meaning |
|---|---|
Attribute omitted from data | Leave unchanged |
| Attribute contains a value | Replace current value |
Optional attribute is null | Clear it |
Writable array is [] | Replace with an empty set |
Send only fields owned by this synchronization. This avoids overwriting Tourfold-managed values and fields owned by another system.
{
"lock_version": 12,
"data": {
"name": "Rooftop HVAC Unit RTU-17A",
"certifications": ["tuv", "iso_9001"]
}
}
An array is always the complete desired value, never an append. Read/merge/write if ownership is shared,
and protect that sequence with lock_version. A stale version returns 409; fetch current state,
reapply your ownership rules, and retry the newly constructed patch.
Relationship arrays follow the same replacement rule only on the declaring owner attribute. A managed reverse is a read-only projection. If a target-side workflow wants to add or remove an edge, it must patch the corresponding owner record.
Reconcile existing recordsβ
Use POST /objects/{object_ref}/records/query for a flat paged scan. Page size is at most 100. Apply an
explicit stable sort and keep the source key and Tourfold ID in the result you process.
{
"filter": {
"updated_at": {"gte": "2026-08-27T00:00:00Z"}
},
"sort": ["updated_at:asc", "id:asc"],
"page": 0,
"size": 100
}
This is a query over current state, not a snapshot-isolated change feed. Records can move between pages
while the scan is running, and deleted records are absent. Use overlapping time windows and deduplicate
by record ID if you use updated_at as a high-water hint. Periodically run a complete inventory
reconciliation so missed deletes and long-lived drift are detectable.
GraphQL is useful when reconciliation needs connected context, but its depth and row-cost limits make it the wrong default for bulk export. Prefer REST paging for bulk movement and GraphQL for targeted graph reads.
Use webhooks as the fast pathβ
Subscribe to the concrete record events you need or an object pattern such as
object.equipment.*. A webhook tells you to process a change quickly; REST tells you the current truth.
Your receiver should:
- Verify the signature over the exact request bytes.
- Enforce a timestamp tolerance.
- Insert
webhook-idinto a table with a unique constraint. - Durably enqueue the event in the same local transaction.
- Return
2xxwithin five seconds. - Process asynchronously and tolerate unknown payload fields.
Delivery is at-least-once and ordering is not guaranteed. The same webhook-id is stable across retries;
deduplicate on it. When ordering matters, compare the event timestamp and finally read current REST
state rather than trusting arrival order.
Delivery failures are not a complete delivery ledger: they record messages that failed at least once, not every successful attempt. Monitor exhausted failures, but keep your own processing journal and reconciliation job.
Retry by operation typeβ
| Operation | Safe retry strategy |
|---|---|
GET / query | Retry transient transport/server failures with bounded exponential backoff |
PATCH with lock_version | On lost response, read current state; on 409, merge and send a newly constructed patch |
Declarative schema PUT | Read current definition/version and regenerate the complete desired document |
Record or batch POST | Do not blind-retry after an ambiguous response; look up unique source keys first |
| Webhook processing | Deduplicate by webhook-id; acknowledge duplicates without applying twice |
Validation, authentication, authorization, and schema errors are not transient. Branch on the RFC 9457
problem type and status. Refresh and replay once only for an expired-token 401; changing credentials or
grants is required for other authorization failures.
Prevent synchronization loopsβ
If Tourfold and the source both emit changes:
- store the last applied source version or content hash;
- compare owned fields before writing and skip no-op patches;
- retain correlation information in your processing journal;
- never route solely on a mutable slug; and
- make webhook handling idempotent independently of API request idempotency.
A webhook caused by your own write is normal. The receiver should recognize that the desired state is already present and finish without another write.
Production checklistβ
- Each synchronized field and relationship has one documented owner.
- Mapping keys include workspace, object, and record identity.
- Source IDs are unique where point lookup is required.
- POST ambiguity is reconciled before retry.
- Arrays and owner-side relationships are treated as replacement sets.
- Concurrent updates use
lock_versionand a merge policy. - Webhooks are signature-verified, durably queued, deduplicated, and processed out of order.
- Full reconciliation covers missed events and deletions.
- Logs retain request/correlation IDs but never bearer tokens or webhook secrets.
For schema changes that affect the mapping, see Evolve a live object schema.