Interop Service — Sync Contract
Status: populated Owner: TBD Last updated: 2026-04-18 Companion: Service Template · 03 platform-services · 02 DDD
1. Per-Aggregate Conflict Policy
| Aggregate | Conflict policy | Rationale |
|---|---|---|
InteropConnector | server_authoritative | Admin-only mutations; no client-side conflict expected |
Hl7Message | append_only | Immutable message log; new processing attempts are appended |
FhirRoutingRule | server_authoritative | Platform admin only; authoritative routing table |
BulkExportJob | server_authoritative | Server drives job lifecycle; no client writes after initiation |
2. HL7 v2 Message Idempotency
The MLLP processor deduplicates messages on UNIQUE(connector_id, message_control_id, sending_app). A second message with the same control ID returns AA ACK and skips processing. This is the primary idempotency guarantee for HL7 v2 inbound.
3. FHIR Resource Idempotency
FHIR PUT /fhir/R4/{ResourceType}/{id} is idempotent per FHIR spec. Conditional creates using If-None-Exist header are supported.
4. Bulk Export Freshness
Bulk export snapshots have a configurable TTL (default 24 hours). Clients should poll the status endpoint and not assume output files are persistent beyond the TTL. New exports must be initiated for refreshed data.
5. Offline Behavior
The FHIR gateway must be online for all FHIR interactions (it proxies to owning services). In hub-outage scenarios:
- MLLP can accept messages (ACK sent) and queue them; processing deferred until hub connectivity restored.
- FHIR endpoint returns 503
OperationOutcometo clients.