HL7 v2 to FHIR
HL7 v2 to FHIR Pipeline
HL7 v2 is still the workhorse of hospital messaging. ADT for admissions, ORU for results, ORM for orders, SIU for scheduling. Converting these to FHIR resources lets the Fire Arrow-backed application benefit from the data without operating its own HL7 v2 listener and parser.
How it works
- 1 Receive HL7 v2
MLLP listener, queue subscriber, or HL7 v2 over HTTPS receives the inbound message.
- 2 Validate and parse
Message validated against the configured schema; segments extracted.
- 3 Map to FHIR
ADT to Patient/Encounter, ORU to Observation/DiagnosticReport, ORM to ServiceRequest, SIU to Appointment.
- 4 Write to Fire Arrow with idempotency
Resources written via PUT with conditional update or via business identifier match to keep retries idempotent.
Who this is for
Integration architects connecting hospital messaging networks to FHIR-backed applications, and product teams whose ingestion volume is dominated by HL7 v2 traffic.
Listener vs converter split
The listener accepts the inbound traffic, acknowledges the sender, and queues the message for processing. The converter takes the queued message, maps it to FHIR, and writes through the FHIR API. Splitting the two lets the listener handle retransmissions cleanly and the converter handle the mapping work.
Both components run under service identities. The listener identity needs no FHIR write access; the converter identity has scoped write access for the resource types it produces.
Idempotency
HL7 v2 senders retransmit on missing or delayed ACKs. The converter has to handle retransmissions without producing duplicate FHIR resources. The standard pattern is a business-identifier match: each FHIR resource carries an identifier derived from the source message (the placer order number, the filler order number, the message control id), and the converter writes through conditional update or upsert against that identifier.
Fire Arrow supports conditional update by identifier, so the converter can submit the same resource shape twice and end up with one resource on the server.
Selecting message types
Most ingestion pipelines select a subset of HL7 v2 message types relevant to the application. ADT and ORU are the most common; ORM and SIU appear in deployments where the application participates in scheduling or order entry.
Filtering at the listener level keeps the converter focused on the messages it knows how to map. Unrecognized messages can be logged and routed to a manual review queue rather than failing the pipeline.
Related docs
Related pages
FAQ
Do I need an HL7 v2 listener inside Fire Arrow?
No. The listener and converter run as separate services. Fire Arrow receives FHIR resources through its standard write API; the HL7 v2 plumbing stays outside.
What about HL7 v3 or v2.5.1?
v2.x messages all map similarly. HL7 v3 is rare in modern deployments; CDA is the more common v3-era format and has its own integration path.
How do I handle ACKs?
The listener sends ACKs on receipt. NACKs (negative acknowledgments) are returned for malformed messages; the listener typically logs and routes for manual review rather than dropping silently.
Can I keep the original HL7 v2 message?
Yes, as a Binary or DocumentReference attachment. Provenance can link the converted FHIR resources to the source message for audit.
