Interoperability (FHIR & HL7v2)
medOS speaks the two standards healthcare systems actually use to exchange data. FHIR R4 is the front door for modern external exchange — SMART-on-FHIR apps, regional health information exchanges, and patient handoff bundles. HL7v2 is the back door for legacy integration — lab instruments, ADT feeds, and pharmacy systems that still emit pipe-delimited messages. A connector catalog sits above both, cataloguing the adapters a deployment can activate and giving operators one place to monitor live data flow.
This page is a map. Each standard has a dedicated detail page; the goal here is to show how the pieces fit together and where the boundaries are.
Two doors, one domain model
Both standards translate into the same medOS domain model held in MongoDB. The mappers and transformers are the only place a standard-specific shape exists; everything downstream — clinical records, orders, results, billing — works in medOS terms regardless of how the data arrived.
FHIR R4
Read, write, and subscription-based delivery through the public-api service. The standard for external exchange.
HL7v2
ADT / ORM / ORU parsing over MLLP or REST, handled by the interoperability service.
Connector catalog
A registry of available adapters across interop, EHR/HIS, claims, lab, imaging, pharmacy, devices and more — each with an honest live / available / planned status.
Integration center
One operator surface to activate connectors and monitor liveness, run history, and a tamper-evident per-run audit trail.
When to use which
| Scenario | Standard | Direction |
|---|---|---|
| SMART-on-FHIR app reads patient data | FHIR R4 | medOS → app |
| External system writes back an observation | FHIR R4 | app → medOS |
| Notify a subscriber when an event matches criteria | FHIR R4 | medOS → subscriber |
| Patient handoff / portable record (QR, download) | FHIR R4 Bundle | medOS → patient |
| Lab analyzer posts results | HL7v2 ORU | instrument → medOS |
| Order placed into an external LIS | HL7v2 ORM | medOS ↔ LIS |
| Admit / discharge / transfer feed | HL7v2 ADT | feed → medOS |
FHIR R4 — modern exchange
FHIR read, write, and subscription operations are served by the public-api service. Writes pass through reverse mappers into the medOS domain model; subscriptions match domain events against stored criteria and dispatch HMAC-signed FHIR Bundles to registered endpoints. A CapabilityStatement endpoint advertises which resources are supported.
SMART / external app
│ FHIR (read / write)
▼
FHIR API (public-api service)
│ reverse mappers
▼
medOS domain model ──▶ MongoDB
│
│ domain events
▼
subscription matcher ──▶ HMAC-signed FHIR Bundle ──▶ subscriber endpoint
Key capabilities:
| Capability | What it does |
|---|---|
| Read API | GET / search for Patient, Encounter, Observation, Condition and related resources |
| Write API | POST / PUT / PATCH mapped back into medOS records |
| Subscriptions | Stored criteria + a delivery log; matches are dispatched outward |
| Signed dispatch | Outbound Bundles are HMAC-signed so subscribers can verify authenticity |
| Rate limiting | A per-subscription dispatch ceiling protects subscribers |
| Bundle export | IPS-compliant FHIR R4 Bundle for patient handoff workflows |
FHIR write-back is governed by a per-tenant kill switch and is off by default, so a deployment opts in deliberately. See the full reference on the FHIR R4 page.
HL7v2 — legacy instruments and feeds
HL7v2 is handled by the interoperability service. Inbound messages arrive either over a TCP MLLP listener (with standard start/end framing) or via REST endpoints, are parsed into structured segments, mapped into medOS operations, and acknowledged with an ACK or NAK. Mapped results then flow into the domain model and emit events like any other write.
Lab / ADT feed
│ MLLP (framed) or REST
▼
Interoperability service
│ parse segments → map → persist
▼
medOS domain model ──▶ MongoDB ──▶ domain events
│
▼
ACK / NAK ──▶ back to the sending system
| Message | Maps to |
|---|---|
| ADT (A01–A08) | Patient and encounter operations (admit, discharge, transfer, update) |
| ORM (O01) | Diagnostic order create / update |
| ORU (R01) | Lab result creation |
The MLLP listener is disabled by default and enabled per deployment via configuration. See the full reference on the HL7v2 page.
Connector catalog & integration center
Above the two protocol layers, the connector catalog describes the adapters a deployment can turn on — across interoperability, EHR/HIS migration, claims, lab, imaging, pharmacy, terminology, messaging, identity, and device feeds. Each connector carries an honest status so operators can tell what is live versus what is planned.
The integration center is the single operator surface for this layer:
Connector runs are recorded with a per-run hash chain, so the activity history is tamper-evident and a stalled feed is visible at a glance rather than failing silently.
Design principles
- One domain model. FHIR transformers and HL7v2 mappers are the only standard-specific code; everything downstream is medOS-native.
- FHIR for external, HL7v2 for legacy. Modern partners use FHIR; only instruments and ADT feeds that require it use HL7v2.
- Opt-in by default. FHIR write-back and the HL7v2 MLLP listener both ship off and are enabled deliberately per deployment.
- Signed and audited. Outbound FHIR dispatch is HMAC-signed; connector runs are recorded in a tamper-evident log.
- Acknowledge everything. Every inbound HL7v2 message produces an ACK or NAK back to the sender.