Sync styles, changelog generation, and outgoing-sync filters

This document describes how Open-mSupply decides what records leave a site, what records arrive at a site, and over which transport. It is descriptive — read it to understand the rules, then go to the code if you need to see them in action.

Re-generating this document: see the bottom of the file.

1. Sync transports

A record that lands in the changelog can leave a site through one of three transports. They are not alternatives — a single record may travel on more than one of them depending on its sync style.

Coexistence:

• A v5 site keeps using the legacy transport, plus v6 selectively for the OMS-native tables.
• A v7 site uses only v7. v7 is a superset transport — it covers every table that has any sync style.

2. The classification matrix — two axes plus transport

A table's sync style is a point on a two-axis matrix, because two questions are genuinely independent:

• Authoring — who is allowed to create or edit this record and push it? This gates what a receiver accepts on an incoming push — checked both when central receives a push from a remote and when a remote receives one back.
• Distribution — which sites are eligible to receive this record on pull-down? This gates which sites central sends a row to.

A table has a set of authoring values and a set of distribution values, each OR'd: an incoming push is accepted if any one authoring clause accepts it, and a row reaches a site if any one distribution clause includes it. A third, separate tag records the transport (legacy v5 / OMS-native v6).

The axes are independent because some records need different answers on each: a clinician is authored on remotes (central must accept its push) yet must reach every site (so it broadcasts, rather than route to one owner). No single label can say "accept remote pushes and broadcast" — two axes can.

Authoring — what a receiver accepts on a push

Because authoring is a set, a push is accepted if any clause accepts it. A patient-typed name, for example, is tagged Central + Patient: central rejects it under the Central clause but accepts it under the Patient clause, so the only name-push central accepts is a patient one.

Distribution — who is an eligible recipient

The split between Remote and RemoteOwned is about write authority, not routing. Both styles use the same "owning site" predicate to pick a recipient. The difference shows up on the central → remote return path: for Remote tables central may legitimately have authored an edit on behalf of the site, so those rows are forwarded every cycle; for RemoteOwned tables central can't author edits, so the return path is suppressed except during initialisation (when the site needs a full snapshot to start from).

Central broadcasts a row when it carries no routing scope; a scoped row of a mixed table (for example a patient-typed name) is claimed by its own clause instead.

Transport-flag per table

Filters that ask for "v6 only" pull just the OMS-native tables. Filters that ask for "v5 only" pull just the legacy-only tables. Filters that pass no transport flag (used by v7) pull every table that has any sync style.

3. The matrix — every table by axis

One row per table, grouped by matrix cell (distribution-set and transport, with authoring alongside) so tables that route and validate identically sit together. Both authoring and distribution are sets — a push is accepted if any one authoring clause accepts it, and a row reaches a site if any one distribution clause includes it. The lists mirror the code exactly. Per-cell notes follow the table.

Per-cell notes

• RemoteOwned · Remote · v5 (ActivityLog, Sensor, TemperatureBreach, TemperatureLog) — site-owned cold-chain and activity data on the legacy transport. Authored on the owning site, and distributed back to that site on every cycle (the Remote clause) rather than only at initialisation.
• RemoteOwned · RemoteOwned · v5 (IndicatorValue, Location, LocationMovement, …) — site-owned data on the legacy transport. A remote pushes these up to legacy 4D central, which fans them back out via its own routing. From the OMS central perspective there is nothing to send back, so the OMS-side return path is suppressed except at initialisation.
• RemoteOwned + Transfer · RemoteOwned + Transfer · v5 (Requisition, RequisitionLine) — site-owned plus a transfer counterpart store. The changelog records the row's own store and a transfer store, so the row routes to the owning site (RemoteOwned) and to the counterpart site (Transfer); a push is accepted from whichever site owns either store.
• RemoteOwned + Transfer + Patient · RemoteOwned + Transfer + Patient · v5 (Invoice, InvoiceLine) — adds patient routing on top of RemoteOwned+Transfer; an invoice also follows its patient (prescriptions only) through name-store-join.
• RemoteOwned · RemoteOwned · v6 (RnrForm, RnrFormLine) — site-owned data on the OMS-native transport. Central does not author edits; the return path is suppressed except at initialisation.
• Remote + Patient · Remote + Patient · v6 (Encounter, Vaccination, ContactTrace) — store-scoped clinical records that should also follow the patient. Each row carries the authoring store and the patient. The Remote clause delivers it to the owning site; the Patient clause delivers it to every other site that knows the patient. Authoring is Remote (not RemoteOwned): the owning site keeps accepting updates even after it has initialised.
• Remote · Remote · v5 (UserPermission, UserStoreJoin) — store-scoped user-access data on the legacy transport. The owning remote site may author and push changes — central accepts a push when the row's store is active on the source site — and central may also edit them. Each row routes only to the site that owns the referenced store, and on every cycle (the Remote distribution clause, not RemoteOwned) precisely because central legitimately authors edits to push back. In practice UserStoreJoin is authored on central (it originates from legacy 4D's user_store table); the Remote authoring clause simply means central would also accept a push from the owning site rather than rejecting it.
• Central · Central · v5 (Abbreviation, Barcode, …) — central data still served from legacy 4D. This bucket also acts as a catch-all for tables that exist in the changelog but haven't been classified into a more specific cell yet.
• Central · Central · v6 (AncillaryItem, AssetCatalogueItem, …) — authored on OMS central, fans out to every v6 site. A few of these (notably NameOmsFields) also allow remote → central writebacks. Some (notably the vaccine-course family) are re-published to legacy 4D so v5-only stores still receive them (see §7).
• Central + Remote · Central + Remote · v6 (PluginData, Preference) — store-or-global data on the OMS-native transport. If the record carries a store it routes to the owning site (the Remote clause); if it doesn't it broadcasts to every site (the Central clause). Authoring is Central + Remote, so both central and the owning site may edit.
• Central + Patient · Central + Patient · v5 + v6 (Name) — names are central data — every site needs the full directory — but a patient-typed name additionally carries its own id as the patient on the changelog. Non-patient names route via the broadcast (Central) clause; patient names route via the Patient clause to every site that knows the patient. On central the Central authoring clause rejects and only the Patient clause accepts, so the only name-push central accepts is a patient name. Name is the only table tagged for both transports.
• Patient · Patient · v5 (Document, NameInsuranceJoin, ProgramEnrolment, ProgramEvent) — pure patient-scoped data on the legacy transport. The changelog row carries only the patient, no store, so routing is purely by Patient and the record follows the patient across stores.
• Anyone · Remote · v5 (NameStoreJoin, ItemStoreJoin, ClinicianStoreJoin) — store-scoped join tables that central accepts from any pusher (no authoring checks) and routes to the owning site on every cycle. NameStoreJoin in particular is rewritten on central whenever a name's patient visibility changes, or whenever the customer/supplier flag on a name flips (which cascades across every site's join row for that name); because central authors those edits, the return path is on every cycle.
• Anyone · Remote · v6 (Asset, AssetInternalLocation, AssetLog) — asset data on the OMS-native transport, accepted from any pusher and routed to the owning site on every cycle. AssetLog and AssetInternalLocation don't carry a store directly, so the changelog generator looks one up from a related row (see §5).
• Anyone · Central · v5 (Clinician) — remote-authored data that broadcasts to every site. The changelog row is keyless — no store, no patient — so it matches the broadcast predicate; the clinician's own store travels in the record data, where store-join and invoice foreign keys still resolve it.
• Anyone · Central · v6 (SyncFileReference) — every site receives every reference row. The file blobs themselves are negotiated separately by the file-sync pipeline.
• Anyone · Central + Remote · v5 (SyncMessage) — accepted from any pusher, with a broadcast clause plus a Remote clause. The changelog store_id is populated from the message's destination store, so the routing matches PluginData / Preference: with a destination store only the owning site receives the message; without one it fans out to every site. Used to ship cross-site instructions like name/item/clinician merges from OMS central down to v7 remotes (see §7).
• Anyone · NotDistributed · v6 (ContactForm, SystemLog) — pushed up to OMS central; not sent back to remotes. On re-initialisation a site does not get its old contact-forms / system-logs back.
• LegacyOnly · NotDistributed · v5 (Site) — pushed to legacy 4D central; never re-sent down to remotes, and never a valid v7 record.

Special — MasterList

MasterList is in the Central/Central/v5 bucket, but its translator does not declare a changelog mapping for push, so nothing actually ships on the wire. The changelog entry exists purely so in-process processors can react to changes; legacy mSupply remains the source of truth and pushes master lists down via its own sync.

4. Changelog row metadata

Each changelog row carries a small set of metadata fields. Each filter joins through one of these fields to decide "is this row for me?".

The source-site field is always populated. When a record is authored locally, it's the current site. When a record is integrated from another site, the original source is preserved. This is what powers every echo guard.

5. How records become changelog rows

When a record is mutated, a changelog row is generated. The patterns differ by what fields the changelog needs.

For deletes, the same generator is used; only the row_action field changes.

6. Outgoing-sync filters

Five filters compose the metadata above into "this site, this transport" predicates. The distribution-keyed filters read the distribution axis; the legacy-push filter reads the transport flag; the v7 push filter reads only the source-site field.

Per-distribution behaviour inside all-data-for-site

The filter joins changelog → store, changelog → transfer-store, changelog → name-store-join → patient-store. A row matches if any one of its applicable distribution clauses holds.

7. Translation

For v5 and v6, a per-table translator decides which transport actually carries a row, and reshapes it for the wire. Three directions exist:

Notable special cases:

For v7 there is no per-table translation step — the database row is serialised directly and deserialised on the other side. As a consequence, v7 push for a given table works whether or not its translator has a v6 opt-in.

8. The single useful invariant

A row reaches a site only if both of the following agree:

1. The matrix (authoring + distribution + transport flag) says the site is an eligible recipient on this transport.
2. The transport-specific machinery actually carries the row — for v5/v6 that's a translator opt-in; for v7 it's blanket (any table with a sync style).

The matrix answers who is eligible and in which direction. The transport answers which wire format. A row only moves when both agree.

How to regenerate this document

Run the slash command:

/sync-styles-doc

(skill defined at .claude/skills/sync-styles-doc/SKILL.md). It reads the current code and rewrites this file from scratch — useful after sync-style changes, new tables, or new translators.