HL7 v2 to FHIR Mapping Guide: What Actually Breaks in Practice

HL7 v2 to FHIR mapping sits at the center of most real-world healthcare integration work today, since the vast majority of clinical data still originates as HL7 v2 messages from source systems, even as downstream applications and analytics platforms increasingly expect standardized FHIR resources instead. The mapping itself sounds conceptually simple, an ADT message becomes a Patient and Encounter, an ORU becomes Observations, but the actual implementation involves genuine complexity around terminology translation, message segment grouping, and handling the inconsistent ways different source systems implement the same nominal HL7 v2 standard.

Below is how the core message-to-resource mapping works, where terminology and field-level translation gets genuinely difficult, and how Mirth Connect fits into building this pipeline reliably. If you're planning an HL7 v2 to FHIR mapping project, our free Mirth Health Check can scope the specific mapping complexity in your environment directly — part of the Mirth Connect support work we do for US healthcare teams.

Each major HL7 v2 message type has a general, well-understood mapping to one or more FHIR resources, though the specific implementation details still require careful, deliberate handling.

ADT Messages Map to Patient and Encounter

Admission, discharge, and transfer messages typically map to updates on the Patient resource for demographic data and the Encounter resource for the actual visit details, with the specific ADT trigger event determining exactly which fields change.

ORU Messages Map to Observation and DiagnosticReport

Observation result messages map to individual Observation resources for each result, often grouped under a parent DiagnosticReport resource representing the overall report, particularly for panel-based lab results with multiple components. See our FHIR Observation resource guide for the resource-side details.

ORM Messages Map to ServiceRequest

Order messages generally map to the ServiceRequest resource, representing the request for a service like a lab test or imaging study, which then connects to the eventual Observation or DiagnosticReport once results are available.

SIU Messages Map to Appointment

Scheduling information unsolicited messages typically map to the Appointment resource, capturing the scheduling details that HL7 v2's SIU message type was specifically designed to communicate between systems. See our FHIR Encounter and Appointment resources guide for how that resource behaves.

Beyond the general message-to-resource pattern, the actual field-level and terminology translation is where most real mapping projects encounter genuine, time-consuming complexity.

Local and Proprietary Codes Need Terminology Mapping

Source systems frequently use local or proprietary codes rather than standard terminologies like LOINC or SNOMED CT, requiring a dedicated terminology mapping layer to translate those codes into FHIR-appropriate standard coding systems.

Segment Grouping Doesn't Always Map One-to-One

A single HL7 v2 message can contain multiple segments that need careful grouping logic to correctly become either separate FHIR resources or components within one resource, rather than a naive one-segment-to-one-resource assumption.

Every Source System Implements HL7 v2 Slightly Differently

Despite HL7 v2 being a defined standard, different vendors and even different sites running the same vendor's system tend to populate fields inconsistently, requiring source-specific mapping logic rather than one universal transformation.

Handling Missing or Non-Standard Field Values Gracefully

Real HL7 v2 messages frequently have missing, malformed, or non-standard field values that a naive mapping implementation will fail on, so robust error handling and fallback logic matter as much as the core mapping logic itself.

Mirth Connect is a practical, purpose-built tool for exactly this kind of transformation work, and understanding how to structure the mapping logic within it matters for building a maintainable, reliable pipeline.

Transformer Steps for Structured Mapping Logic

Mirth's transformer steps let you build structured, testable mapping logic converting HL7 v2 segments into FHIR resource JSON, keeping each specific mapping concern isolated rather than one large, tangled transformation script.

Code Templates for Reusable Terminology Lookups

Terminology mapping logic used across multiple channels, translating local codes to LOINC or SNOMED, belongs in a shared code template, so a terminology update applies consistently everywhere that mapping logic is actually used. See our code templates and reuse guide for how to build these.

Testing Against Real, Messy Source Data

Test your HL7 v2 to FHIR mapping against genuinely messy, real source data rather than idealized test messages, since production data's inconsistencies are exactly what a clean test message won't reveal before go-live.

Building Incrementally by Message Type

Rather than attempting to build a complete mapping pipeline for every message type at once, build and validate incrementally by message type, starting with your highest-priority data before expanding to less critical message flows.

If terminology translation is turning out to be the long pole in your mapping project, that's the norm, not a sign something's wrong with your approach. Our free Mirth Connect health check assesses your specific mapping complexity as part of the standard diagnostic.

Book a Free Health Check →

Troubleshooting something specific? Send us the log, or check pricing for our support plans.