Normal Sync (source → clone tables)

Normal Sync is the third agent, and it runs first in the chain: an on-premises change-tracking sync agent for Microsoft SQL Server (2008 R2 and later) that extracts changed data from the customer’s source database into the clone tables of their gateway database. Sources that are not SQL Server use the ODBC sync agent instead, which lands the data in an intermediary database that Normal Sync then moves into the clone tables. From there CRMPro consumes the clone tables (through views) and pushes to the CRM — so the three products chain: Normal Sync → clone tables → CRMPro → CRM, with TxDownloaderPro closing the loop back toward the source.

The SQL login the agent uses for the source database needs db_owner on it. Normal Sync does more than read: it creates and alters the clone tables, table types and stored procedures in that database and enables change tracking there. A read-only login is enough for the connection test to pass and not enough to sync, so this is worth confirming before a first run rather than after one that moves nothing.

The normalsync_* admin tools manage which source tables the agent syncs: normalsync_available_tables (the ERP’s table catalogue), normalsync_list_selected_tables, normalsync_readiness (are the prerequisites in place?), normalsync_select_table (add an already-catalogued table to this customer’s sync), normalsync_set_sync_enabled (per-table activate/deactivate), normalsync_set_row_filter (the per-table row filter and index hint), and — for tables never synced anywhere before — normalsync_catalog_table / the composed normalsync_add_table. Four more cover RESYNC, for tables that already clone: normalsync_resync_status (what is pending, plus clone coverage), normalsync_resync_all, normalsync_resync_table and normalsync_clear_table_resync.

From the CLI, the same operations are a shorthand group — everything runs against a named tenant profile:

dlake normalsync tables --profile <tenant>            # what could be added
dlake normalsync selected --profile <tenant>          # what IS selected, syncing, filtered
dlake normalsync readiness --profile <tenant>         # all four phases, with reasons
dlake normalsync select AR_CUSTOMER 41 --profile <tenant>
dlake normalsync enable AR_CUSTOMER 41 --profile <tenant>
dlake normalsync filter 41 --where "CustomerNo > '1000'" --confirm --profile <tenant>
dlake normalsync add SO_HEADER --confirm --profile <tenant>
dlake normalsync resync --confirm --profile <tenant>              # re-pull every table
dlake normalsync resync --table ArCustomer --confirm --profile <tenant>
dlake normalsync resync-status --profile <tenant>                 # pending + clone coverage

dlake normalsync --help lists the shorthand group; the full tool set is always reachable as dlake admin normalsync_<tool>, with --help generated from each tool’s schema. --confirm is required by catalog, add, filter and every resync form, and the CLI refuses without it before any call is made.

Resync is a REQUEST QUEUE, not a setting: it writes flags into the customer gateway database — no delete, no truncate, no clone table touched — and the agent picks them up on its next run, clearing RE_SYNC_FLAG when it starts. So a zero in normalsync_resync_status means nothing is PENDING (never requested, or already picked up), never that a request was lost, and no write on that surface verifies itself by reading the flag back. The status read also reports clone coverage — rows actually in each clone table against the count recorded at last sync — because a sync run reporting SUCCESS is not evidence that rows moved. Both numbers are soft in opposite directions (approximate count, ageing snapshot), which is why no percentage is computed and nothing is clamped. That next run need not be the scheduled one: the customer’s server also runs the Commercient Receiver, a WebSocket client that stays connected to the Commercient service and starts a product’s sync when a run command arrives from it, so a queued resync can be picked up on demand — provided the Receiver task exists on that server (the Sync Agent CLI’s status reports Created / Not Created; Not Created means only the product’s own scheduled task will run it).

Two things deserve care:

• The table catalogue is shared per ERP. Cataloguing a new table writes a row that every customer on that ERP sees in their available-tables list. That is deliberate — it is how a never-before-synced table becomes syncable without waiting on Commercient — but there is no API that removes a catalogue row, so a mistake is a manual database cleanup. Both cataloguing tools require confirm: true for exactly this reason.
• Row filters are executed against the customer’s source database by the on-premises agent. normalsync_set_row_filter is read-merge-write (an omitted field is preserved; clearing is explicit) and confirm-gated.

The deeper guide — prerequisites, the two-call add sequence, and how the ODBC agent stacks — is the dlake-normalsync skill.