The short answer
An HL7 v2 to FHIR pipeline receives v2 messages (ADT, ORU, ORM and others), parses them into segments and fields, maps each to FHIR R4 resources, validates the result, and writes it to a FHIR server, ideally as a transaction, then reads it back. HL7 publishes official mappings for this: the HL7 Version 2 to FHIR guide maps v2 message segments, datatypes and vocabulary to FHIR R4 as concept maps.2 AI agents are useful for drafting mappings for local fields and triaging failed messages. They shouldn’t be the path every message takes into the record.
Deedglass
The server said “saved”. Deedglass looked.
Deedglass reads it back
Why v2 still matters
FHIR gets the attention, but v2 carries most of the traffic. In a 2023 national survey, 96% of US health information exchanges reported receiving HL7 v2 ADT messages, while adoption of FHIR APIs was slower.1 Inside hospitals the pattern is similar: admissions, lab results and orders move as v2 between systems that were never rebuilt for FHIR. Any FHIR-based app, analytics store or AI tool that needs live data usually depends on a conversion pipeline somewhere.
The five stages
Code What the screen or file shows, copied as is.
v2 message ─▶ 1 receive ─▶ 2 parse ─▶ 3 map ─▶ 4 validate ─▶ 5 write + read back
(MLLP) ack/nack segments concept profiles transaction,
fields maps and rules compare stored
| Stage | Job | Typical failure |
|---|---|---|
| 1. Receive | Accept over MLLP or files; acknowledge | Ack sent before the message is safely stored |
| 2. Parse | Split segments, fields, components; handle escapes | Wrong encoding characters; truncated repeats |
| 3. Map | Segments and fields to FHIR resources and elements | Local Z-segments dropped; codes mis-mapped |
| 4. Validate | Check against FHIR and your profiles | Validation off, so bad data is accepted |
| 5. Write | Send to the FHIR server, read back | Partial writes; duplicates; silent trimming |
Stages 4 and 5 are where most teams cut corners, and where our measurements say the losses hide.
What the HL7 mapping guide gives you
The HL7 Version 2 to FHIR guide (1.0.0, STU 1, trial use) maps v2 message segments, datatypes and vocabulary to FHIR R4. It isn’t tied to one v2 version, covers deprecated components still in use, and is a cumulative mapping of the standard rather than of any particular v2-based implementation guide. It ships the mappings as Concept Maps, with references to the spreadsheets used to generate them.2
Two consequences. First, start from these maps rather than writing your own; they encode years of committee work on questions like which PID fields become which Patient elements. Second, your interfaces aren’t the standard. Local Z-segments, site-specific code tables and fields used in non-standard ways won’t be in the guide, because it maps the standard, not your implementation.2 That gap is where most mapping work, and most mistakes, live.
Where data gets lost
Three losses are common, and none produce an error by default.
Unmapped fields. A field with no mapping is often skipped, not refused. The message converts “successfully” without it.
Lenient servers. If the converted resource is malformed, many FHIR servers accept it anyway. In our October 2026 study across four server setups, 29 of 72 invalid writes got a success reply, and 8 of those were stored with part of what was sent removed.4 A status sent as an array was answered 201 by HAPI’s defaults and stored with no status at all; with request validation on, HAPI refused it.4 Validation strictness is a server setting, not a defect, but it means stage 4 has to happen somewhere you control.
Duplicates on replay. v2 interfaces resend messages after timeouts. If stage 5 creates resources without checking, a resent ADT creates a second Patient. Use conditional create on a stable identifier, and know that when one match exists, R4 answers 200 and creates nothing.3 Our conditional create post shows the edge cases.
For multi-resource messages, a transaction makes the entries succeed or fail together, and its response has one entry per request to check.3
The four setups we tested are named in the study: HAPI FHIR JPA Server 8.12.0 twice, the HAPI public server and the Firely Server 6.11.0 sandbox.4
Where AI agents help, and where they don’t
| Task | Agent role | Safe? |
|---|---|---|
| Drafting mappings for local Z-segments | Proposes a mapping; an analyst reviews | Yes, with review |
| Explaining a failed message | Reads the error and the message, suggests a fix | Yes |
| Triage of the exception queue | Sorts failures by cause | Yes |
| Writing test messages | Generates synthetic v2 messages for each mapping | Yes, synthetic only |
| Converting every live message | Model in the hot path | No: non-deterministic and slow |
| Fixing and resubmitting failed messages alone | Edits clinical data and writes | Only with a person approving each |
The line is determinism. A pipeline should convert the same message the same way every time, so a mapping bug can be found, fixed and replayed. A model in the hot path makes each conversion a fresh judgement. Use the agent to write and review the deterministic mapping, not to be it.
If an agent does resubmit corrected messages, treat its write like any other: rules before, a person for anything clinical, a read-back after, and a record of what it changed.
A checklist
- Start from the HL7 v2-to-FHIR concept maps; document every local deviation.2
- Store the original v2 message before acknowledging it.
- List every field you deliberately drop, and alert on fields you didn’t expect.
- Validate against your profiles before writing; don’t rely on the server’s defaults.4
- Use conditional create on stable identifiers; treat 200 and 201 differently.3
- Write multi-resource messages as transactions and check each entry.3
- Read back a sample, or all, of writes and compare with the source message.
- Keep agents out of the hot path; let them draft mappings and triage exceptions.
Questions people ask
Is there an official HL7 v2 to FHIR mapping?
Yes: the HL7 Version 2 to FHIR implementation guide, 1.0.0 STU 1, with concept maps for segments, datatypes and vocabulary.2
Can an LLM convert HL7 v2 to FHIR?
It can produce plausible output, but not reliably the same output every time. Use it to draft and test mappings that a deterministic engine runs.
How do I know nothing was lost?
Compare what you sent with what the server stored, and keep a list of fields you drop on purpose. The FHIR write integrity study shows how often servers store something different from what they accept.
Hospitals planning this can start from our healthcare overview; the provenance spec shows how to record an agent’s corrections. To try approvals and read-backs on a real database in your browser, open the playground; to grade what an agent can reach on your own machine, run npx deedglass scan (the grade, explained).
Written with AI assistance and checked against our claims register.