A practical HL7 v2 to FHIR migration roadmap: side-by-side running, segment-to-resource mapping, tooling, semantic testing and safe retirement of old feeds.
More than 80% of health information organizations routinely or sometimes sent, received, or made available HL7 v2 messages, while only about one-fifth routinely or sometimes exchanged data through FHIR APIs, according to ONC's data brief on standards adoption. For teams planning HL7 v2 to FHIR migration, the engineering problem is preserving operational workflows while introducing a different data model and exchange contract. A practical roadmap covers parallel operation, segment mapping, transformation tooling, semantic testing, and evidence-based retirement of legacy feeds.
Existing ADT, order, result, and scheduling interfaces have dependencies that extend beyond their message schemas. Local Z-segments, site-specific field usage, and workflow assumptions mean nominally compliant interfaces can behave differently. The official HL7 mapping guide treats implementation-specific refinement as necessary rather than exceptional.
Coexistence means keeping those operational contracts intact while exposing selected data through FHIR. Engineering must own the translation boundary; clinical domain owners must approve meaning; receiving-system owners must confirm that the new interface supports their workflow. Replacing the transport before resolving those responsibilities creates avoidable uncertainty.
FHIR makes sense when a consuming application needs resource-based access and the destination supports the required interactions. The FHIR R4 specification provides the target standard, but a project still needs an agreed resource scope and implementation contract. Start with a concrete consumer requirement, such as read access to converted results, rather than a general objective to modernize every interface.
Keep a functioning v2 connection when neither endpoint needs a new exchange model and the replacement would only add another transformation boundary. Delay write-back when ownership of updates, cancellations, or corrections remains unresolved. Most hospitals should plan for a hybrid period lasting years rather than assume an immediate replacement.
Keep a legacy feed until its consumers can demonstrate that the replacement supports their actual workflow.
Our approach to FHIR and HL7 integration services starts with dependency inventory and bounded delivery scope. The distinction between standards is also useful when agreeing that scope, particularly the exchange-model differences covered in FHIR versus HL7.
Agree on the FHIR interaction model before implementing the adapter. HL7's project supports messages, persistence models, and RESTful APIs; under FHIR R4 messaging requirements, a Bundle with type message must have a MessageHeader as its first resource. Persisting converted resources and emitting an event-bearing message are different delivery contracts.
For a persistence architecture, we recommend branching the existing feed into a controlled transformation pipeline without changing the operational consumer's path. Retain the source message, transformation version, and delivery outcome together. This provides evidence for reconciliation without treating successful FHIR delivery as proof that the legacy workflow completed.
Consider a hypothetical laboratory result feed that continues delivering ORU messages to an EHR while populating a read-only FHIR store.
The ingestion layer records the source message and routes the existing v2 delivery independently.
The transformer resolves patient and encounter identities using agreed identifier rules, then constructs the scoped resources.
A validation stage checks the generated output and sends ambiguous content to an exception queue.
The delivery stage records the destination outcome, allowing operators to distinguish transformation failures from receiving-system failures.
Engineering should define stable resource IDs and resolvable references before deployment. HL7's implementation considerations also warn about repeating-value loss and terminology translation, so the pipeline must retain enough source context to investigate either problem.
Assign a named owner to each exception queue. A queue without a response procedure moves unresolved clinical meaning out of the main processing path.
HL7 publishes HL7 Version 2 to FHIR, v1.0.0, STU 1, as a trial-use implementation guide. Its published mapping reference maps messages, segments, datatypes, and vocabulary to FHIR R4; work started from v2.9 while covering older elements still in use. Use the following mappings as entry points, not as independent conversion functions.
| HL7 V2 Segment | FHIR R4 Resource | Key Mapping Considerations |
|---|---|---|
| PID | Patient | Preserve identifier context and resolve identity before linking other resources. |
| PV1 | Encounter | Interpret visit information within the message event and receiving workflow. |
| OBX | Observation | Preserve value meaning, coding, repetitions, and relevant result context. |
| ORC/OBR | ServiceRequest | Interpret order control and request details together; context determines the complete output. |
| MSH | MessageHeader | Apply this mapping within a FHIR messaging contract rather than assuming every persistence conversion requires it. |
A segment can contribute to resources beyond its primary mapping. Message structure and neighboring segments determine relationships that a standalone field crosswalk can miss. The guide's mapping organization separates messages, segments, datatypes, and tables, and includes agreed extensions where FHIR has a gap.
Repeated v2 values need an explicit disposition when the destination's cardinality is narrower. Retaining only the first value and discarding the rest is not acceptable. Record whether the approved transformation uses an extension, produces additional resources, or requires review.
Vocabulary handling needs the same discipline. Preserve the original code, coding system, and text alongside normalized coding where appropriate, including use of the Alternate Codes extension described in the implementation considerations. An unresolved required binding should become a visible exception rather than an invented equivalent.
For local Z-segments, ask the clinical owner what each element means and which consumers use it. Prefer a suitable standard element when one exists; document the justification for an extension or local profile when it doesn't. Maintain a mapping register with source location, condition, destination, preservation decision, and approver.
That register should also distinguish intentional omissions from unsupported content. Both may produce valid output, but they require different acceptance decisions.
Evaluate interface engines, managed healthcare APIs, and custom transformation services against the same representative messages. An engine may fit an established operational environment; a managed service may fit the organization's deployment model. Neither category proves that local clinical semantics are preserved.
HL7 publishes computable CSV and ConceptMap artifacts, with traceable source material described in its v2-to-FHIR project documentation. Ask how a candidate tool imports, executes, versions, and exposes those mappings. A configuration screen is insufficient evidence unless reviewers can connect its behavior to approved transformation rules.
Use a short acceptance exercise before selecting infrastructure:
Mapping control should include conditional rules, local fields, and reviewable changes.
Failure visibility should distinguish parsing, terminology, validation, and delivery outcomes.
Replay support should allow operators to reproduce output using a known mapping version.
Operational ownership should identify who maintains dependencies, resolves incidents, and approves releases.
Avoid assuming that managed infrastructure removes customer responsibilities. Ask engineering and compliance owners to document access, retention, audit evidence, and deployment boundaries before using production data. This is a proposed review process, not a claim that a product automatically satisfies HIPAA requirements.
Staffing belongs in that assessment. Name an owner for interface engineering, terminology mapping, clinical validation and operations support before the first feed moves.
Require a candidate platform to reproduce an approved transformation and explain every exception before accepting its happy-path demonstration.
The HL7 mapping guide introduction states that current datatype mapping information is incomplete and doesn't cover all commonly used v2 elements. Build a golden-message corpus from representative local interfaces rather than expecting a generic test suite to establish readiness.
Include repeating fields, local codes, missing identifiers, multiple providers or organizations, and abnormal results. Each case needs expected output and a clinical rationale for the acceptance decision. Engineering owns executable assertions; clinical reviewers approve interpretation; receiving-system owners confirm workflow behavior.
Measure message-level conversion success, resource-level validation success, unresolved-code rate, and manual-review rate separately. Don't compress these into a single conversion percentage. A parsed message can still contain an unresolved code or an incorrect relationship.
Validation should test the target profiles, terminology preservation, referential integrity, and idempotent reprocessing. Then test actual destination interactions against its CapabilityStatement, which declares supported capabilities under the FHIR R4 overview. A locally valid resource doesn't establish that the receiver supports the intended operation or exchange mode.
Use dual-contract tests to compare both outputs against the same source event:
Legacy assertions verify that the existing consumer receives the expected operational content.
FHIR assertions verify that the converted representation retains the approved clinical meaning.
Cross-contract assertions reconcile identities, event context, and disposition across both paths.
The acceptance package should include reviewed fixtures, mapping versions, validation results, and exception decisions. Broader healthcare data interoperability depends on that shared understanding between producers and consumers, not merely successful serialization.
The 2025 State of FHIR survey found that 73% of experts reported FHIR as mandated or formally advised, while funding and deadlines remained uneven. That supports budgeting for incremental delivery, although the survey itself doesn't establish a legal obligation for a particular organization.
Start with high-volume interfaces in the inventory, but choose the first production scope by clinical risk and consumer readiness. Volume helps prioritize engineering effort; it shouldn't override unresolved workflow ownership.
Inventory and classify. Record ADT, ORU, ORM/OML, and SIU feeds, local profiles, downstream consumers, and accountable owners. Identify what each consumer would lose if its feed stopped.
Establish a bounded read-only scope. Approve mappings and expected clinical meaning before connecting a production consumer.
Run shadow processing and reconcile exceptions. Preserve the operational route while validating the new path against the agreed contract.
Enable selected consumers, with rollback procedures and support ownership documented. Expand scope only after the previous release's exception behavior is understood.
Retire by dependency evidence. Require consumer sign-off, accounted-for traffic, verified replacement behavior, and a tested recovery procedure.
A legacy feed with unexplained traffic is still an unresolved dependency. Conversely, leaving an unused feed running indefinitely adds another component that someone must maintain. Set retirement criteria when the interface enters the migration backlog, then evaluate them using observed behavior.
Document integration into existing healthcare systems as an operating responsibility, including change approval and post-release reconciliation.
Treat migration as a governed coexistence program with explicit source, transformation, and destination contracts. Retire interfaces only when owners can demonstrate semantic preservation and workflow replacement.
No universal replacement assumption is justified. Keep a feed when its consumers still depend on its operational behavior, and evaluate replacement against an agreed workflow contract.
No. The segment mapping identifies a target resource, but the implementation must still agree on identifier context, identity resolution, and references from related resources.
No. The target can use messaging, persistence, or RESTful access. Choose the interaction model with the receiver before implementing the adapter.
Preserve the source coding context and route ambiguous values for review. Don't manufacture a target equivalent merely to satisfy validation.
Require evidence that its consumers no longer depend on it and that the replacement passes operational acceptance. Unexplained traffic, unresolved exceptions, or an untested recovery procedure should block retirement.
Book a consultation with Ekipa's HealthTech engineers to review your interface inventory, mapping risks, and phased migration plan.
How to integrate with Epic EHR: FHIR vs HL7 v2, Epic developer programs, hospital approval, sandbox-to-production gates and the blockers that stall teams.
How to automate prior authorization under CMS-0057-F: the 2026 and 2027 deadlines, FHIR APIs and Da Vinci guides, ONC HTI-4, and where AI should stop.
How to build HIPAA-compliant AI: when LLM providers need a BAA, data minimization, de-identification, audit controls and a reference architecture.
Connect with our team to explore how AI expertise can transform your business.