Configure how a Business Entity exchanges records or documents with its Connected System — on a schedule or on demand — so data normalizes into Enterprise Knowledge.
Prerequisites
- Connected System authentication configured and upload-ready
- Configure metadata and identity on the entity
- Configure business vocabulary for field projections
- Configure data flow so list/get (and write ops, if needed) bind correctly
Where it lives
| Layer | Location |
|---|---|
| Sync band | <datasourceKey>.json → sync |
| Document ingestion | documentStorage + sync together for entityType: documentStorage |
| UI | Business Entity Sync tab (?tab=sync) — enablement, mode, schedule, batch size |
Manifest key: sync.
Builder MCP
| Manifest key | sync |
| UI tab | Sync (?tab=sync) |
| Help topics | section, dependencyGraph, repairRules |
| Repair hooks | sync |
After sync edits, run aifabrix repair <systemKey> --sync when the dependency graph lists downstream sections. Validate before upload.
Sync mode (what direction to sync)
sync.mode sets direction — which way data moves when sync runs. It is not the same as enterprise sync bridge participation (syncBridge on the datasource root).
| Mode | Direction | Use when |
|---|---|---|
| pull (default) | Connected System → Enterprise Knowledge | You want scheduled or manual ingest: list/get from the vendor and upsert into local storage. Typical for CRM, tickets, and document libraries. |
| push | Enterprise Knowledge → Connected System | Local or enterprise changes should write out to the vendor (create/update through CIP write capabilities). |
| bidirectional | Both | The entity must both ingest from the vendor and write changes back. Requires write-capable CIP operations and writable field mappings. |
Most record entities start as pull. Switch to push or bidirectional only when the Business Entity is meant to update the Connected System, not only mirror it.
How to set
- Set sync enablement, direction, and schedule on the datasource:
{
"sync": {
"enabled": true,
"mode": "pull",
"schedule": "0 */6 * * *",
"batchSize": 500
}
}
Allowed mode values: pull, push, bidirectional. Optional schedule uses 5-field cron or @hourly / @daily / @weekly / @monthly. Optional batchSize is 1–10000 (default 500). Set enabled: false when operators must stop all synchronization while retaining the configured cadence and incremental settings.
- Or edit the same fields on the Business Entity Sync tab (Mode, schedule, batch size) and save when the UI allows editing.
- Document storage — use document-specific pull/download operations; see Build a document storage entity.
- Record storage — align pull (and write, for push/bidirectional) operations with OpenAPI bindings under Configure data flow.
- Repair and validate:
aifabrix repair <systemKey> --sync
aifabrix validate <systemKey>
Incremental sync (optional)
schedule above always drives the full-set job (sync all). Optional sync.incrementalKey and sync.incrementalSchedule add a separate incremental job on top of it — they do not replace schedule and are unrelated to sync.mode direction.
| Field | Required | Notes |
|---|---|---|
incrementalKey |
No | Name of the query filter already authored on the list CIP operation's fetch.query (see Configure data flow). Must map to a metadataSchema field of type date, date-time, or integer (unix time). Never inferred from field names — you name the filter. |
incrementalSchedule |
No — allowed only when incrementalKey is set |
Cron for the incremental job. schedule remains the full-set cron; the two run independently. |
{
"sync": {
"mode": "pull",
"schedule": "@daily",
"batchSize": 500,
"incrementalKey": "updatedAfter",
"incrementalSchedule": "*/15 * * * *"
}
}
Incremental jobs bind the entity's last-synced timestamp into the named incrementalKey filter on every run. Keep the full-set schedule as a periodic reconciliation pass — incremental sync narrows volume, it does not replace the full-set job.
Defaults and examples
| Field | Default | Notes |
|---|---|---|
enabled |
true |
New sync configurations emit this explicitly. A legacy sync block without it remains enabled. |
mode |
pull |
Direction only — see table above |
schedule |
@monthly for a new configuration |
Calendar-month cadence in UTC. A legacy configuration with no schedule stays manual-only until an operator chooses a schedule. |
batchSize |
500 |
Page/chunk size for sync processing |
Pull example (ingest only):
{
"sync": {
"enabled": true,
"mode": "pull",
"schedule": "@hourly",
"batchSize": 500
}
}
Bidirectional example (ingest and write back — only when CIP update/create exist):
{
"sync": {
"enabled": true,
"mode": "bidirectional",
"schedule": "0 */6 * * *",
"batchSize": 200
}
}
Stop all synchronization
Use total disable when no scheduled, manual, webhook, or sync-bridge synchronization may start:
{
"sync": {
"enabled": false,
"mode": "pull",
"schedule": "@monthly",
"batchSize": 500
}
}
Disabling preserves schedule, incrementalKey, and incrementalSchedule so re-enabling restores the intended cadence. It does not deactivate the Business Entity, block reads and search, or disable governed non-sync capabilities.
A queued job or sync intent rechecks enablement before its first side effect and stops with recorded datasourceSyncDisabled evidence. Work already performing an external or storage side effect finishes its current operation; disabling prevents later work rather than pretending that the in-flight effect was cancelled.
Validate
Integration proof: CLI workflow — test-integration exercises sync against live credentials.
Confirm these states in the Sync tab before upload:
- Enabled, monthly: the next automatic run uses the monthly UTC cadence.
- Enabled, manual-only: no schedule is present; an operator can run sync on demand.
- Disabled: manual and automatic sync actions are unavailable, while saved schedule fields remain visible for re-enable.
Enterprise sync bridge
Inbound sync (above) loads records into Enterprise Knowledge for one datasource. Sync bridge propagates normalized changes across datasources that share a resourceType — without point-to-point target lists.
| Concern | Where to read |
|---|---|
| Track B How to set | Configure sync bridge |
| Optional change signals | Configure webhook change signals |
| Business model | Enterprise Synchronization Fabrix |
| Manifest depth / CIP prerequisites | Enterprise sync bridge — technical guide |
Do not confuse sync.mode (pull / push / bidirectional) with syncBridge (disabled / master / bidirectional). Mode is per-entity direction with the Connected System; sync bridge is cross-datasource enterprise propagation.
Common mistakes
| Mistake | Fix |
|---|---|
Treating mode as incremental vs full job type |
Use pull / push / bidirectional for direction only |
| Removing the schedule to stop sync | Use enabled: false; an omitted schedule means manual-only, not total disable |
| Expecting disable to undo running work | It prevents the next side effect; inspect the recorded outcome of work already running |
| Push or bidirectional without write CIP ops | Add update/create under data flow |
| Sync without CIP/list operation | Configure data flow bindings first |
| Record sync pattern on document entity | Use document ingestion band |
| Skipping repair after sync edits | repair --sync |
| Confusing Sync Mode with syncBridge | Mode = vendor direction; syncBridge = enterprise cross-entity |
Setting incrementalSchedule without incrementalKey |
Not allowed — set incrementalKey first |
Inferring incrementalKey from a field name |
Name the filter already authored on the list operation's fetch.query; never inferred |
Limits
This page documents the external datasource schema 2.9.12 sync contract. Dataplane support is complete. Builder authoring support must pass its companion release validation before teams rely on every generator and repair path to emit the new defaults; validate the installed CLI schema version and preserve legacy schedule-less configurations as manual-only.
Job-level run options (for example how aggressively missing vendor rows are reconciled on a given run) are platform sync-engine behavior and are not fields on sync.mode.
For document storage, root documentStorage.ingestAfterSync is an ingestion-timing control after extraction, not a trust or approval bypass; see Build a document storage entity. For static or file loads, a partial/direct batch preserves keys absent from that batch. A job-bound full-source reconciliation may tombstone missing keys only with positive complete-source evidence; missing evidence is not “complete by default.”