Every healthcare organization with an HL7v2 integration layer is having the same conversation: "We need to move to FHIR." The reasons are clear — regulatory mandates from CMS and ONC, payer requirements for Patient Access APIs, the mobile app ecosystem that speaks only REST and JSON, and the growing API economy that makes HL7v2's pipe-delimited messages feel like fax machines in a Slack world. But the conversation stalls when someone asks the obvious question: "How?"
The average HL7v2 to FHIR migration takes 18 to 36 months for a mid-size organization (HealthIT.gov, 2024). Failed migration projects waste an average of $200,000 to $500,000 before organizations restart with a different approach. The failures almost never come from technical inability to map HL7v2 segments to FHIR resources. They come from trying to do everything at once, ignoring the reality that HL7v2 is not going away, and underestimating the complexity of maintaining two standards simultaneously.
This guide is the practical roadmap that conference presentations skip. We will cover the four-phase migration strategy that works for organizations ranging from 10-interface clinics to 200-interface health systems. It is based on real migrations, real timelines, and real costs — not vendor marketing slides that promise seamless conversion in six weeks.
Why Migrate Now
The pressure to migrate from HL7v2 to FHIR is coming from multiple directions simultaneously. Understanding these drivers helps you prioritize which interfaces to migrate first and justify the investment to executive leadership.
Regulatory Mandates
The ONC Cures Act requires healthcare organizations to provide access to electronic health information without information blocking. CMS mandates FHIR-based Patient Access APIs, Provider Directory APIs, and Payer-to-Payer exchange. TEFCA (Trusted Exchange Framework and Common Agreement) is building the nationwide data exchange infrastructure on FHIR. These are not suggestions. They are requirements with financial penalties for non-compliance — up to $1 million per violation for information blocking.
Payer Requirements
Health plans are increasingly requiring FHIR-based data exchange as a condition of network participation. Prior authorization is moving to electronic FHIR-based workflows under CMS-0057-F. Payer-to-payer data exchange (effective January 2026) requires FHIR APIs. Organizations that cannot speak FHIR to their payers will face administrative burden, delayed reimbursement, and potential exclusion from preferred networks.
The Mobile App and API Economy
Patient-facing applications, clinical decision support tools, population health platforms, and AI/ML systems all expect RESTful APIs that return JSON. HL7v2 over MLLP cannot serve these use cases. Every new capability that depends on modern APIs requires either a FHIR endpoint or a custom translation layer. Building custom translation layers for each new use case is more expensive than migrating to FHIR once.
Talent and Ecosystem
New developers entering healthcare IT understand REST, JSON, and OAuth. They do not understand MLLP, pipe-delimited segments, and Z-segments. The HL7v2 talent pool is shrinking as experienced engineers retire. The FHIR ecosystem — libraries, tools, testing frameworks, community support — is growing rapidly. Building on FHIR means building on a platform with an expanding, not contracting, ecosystem.
The Reality: HL7v2 Is Not Going Away
60-80% of US hospitals still run HL7v2 interfaces for core clinical workflows: ADT (admit/discharge/transfer), lab orders and results, radiology, pharmacy, and billing. These interfaces connect to devices, systems, and partners that will not switch to FHIR on your timeline. The infusion pump that sends HL7v2 results. The reference lab that processes millions of HL7v2 messages daily. The legacy billing system from a vendor that went out of business in 2018.
This is the most important strategic insight for your migration: coexistence is the norm for 5-10 years. You will run HL7v2 and FHIR simultaneously for the foreseeable future. Any migration plan that assumes you can turn off HL7v2 within 2-3 years is unrealistic for most organizations. Plan for coexistence. Design for coexistence. Budget for coexistence.
This is not a failure. It is pragmatism. The organizations that acknowledge coexistence as a feature, not a bug, build better architectures than those that pretend they can eliminate HL7v2 on a short timeline. For a deeper look at when you need both standards, see our analysis of HL7 vs FHIR: when organizations need both.
Phase 1: Inventory and Assessment (Months 1-3)
Before you migrate anything, you need to know exactly what you have. This phase produces the foundation that every subsequent decision rests on.
Catalog All HL7v2 Interfaces
Create a complete inventory of every HL7v2 interface in your organization. For each interface, document:
- Source and destination systems: What sends the message? What receives it?
- Message types: ADT^A01, ORM^O01, ORU^R01, etc.
- Daily message volume: How many messages per day? Peak volume?
- Criticality classification: Patient safety (critical), clinical workflow (important), or administrative (low).
- Customization level: Standard HL7v2, or heavily customized with Z-segments and site-specific logic?
- Partner dependency: Is the sending/receiving system under your control, or does it belong to an external partner?
- Contract/regulatory requirement: Is this interface mandated by a contract, regulation, or accreditation requirement?
Classify by FHIR Readiness
For each interface, assess how ready it is for FHIR migration:
- Green (ready): Both source and destination systems support FHIR R4. Migration is a configuration change, not a development project.
- Yellow (bridgeable): One side supports FHIR, the other does not. A translation layer (Mirth Connect) can bridge the gap.
- Red (not ready): Neither side supports FHIR. Both would need upgrades or replacement before FHIR is possible. These stay on HL7v2.
Identify FHIR Candidates
Prioritize interfaces for FHIR migration based on a weighted scoring model:
Priority Score = (Regulatory Urgency x 3) + (Business Value x 2) + (Technical Readiness x 1)
Regulatory Urgency (1-5):
5 = Required by active CMS/ONC mandate
4 = Required by upcoming mandate (within 12 months)
3 = Needed for TEFCA participation
2 = Helpful for compliance posture
1 = No regulatory driver
Business Value (1-5):
5 = Enables new revenue or prevents revenue loss
4 = Eliminates significant manual work or clinical risk
3 = Improves operational efficiency
2 = Nice to have
1 = Minimal business impact
Technical Readiness (1-5):
5 = Both sides FHIR-ready, standard mapping
4 = One side ready, bridge needed but straightforward
3 = Moderate mapping complexity
2 = Significant customization needed
1 = Major system upgrade required firstPhase 2: Bridge Strategy (Months 4-9)
The bridge strategy is the core of a practical migration: HL7v2 in, FHIR out. Your integration engine (Mirth Connect) sits at the boundary between the HL7v2 world and the FHIR world, translating messages in real time.
How the Bridge Works
The bridge pattern is straightforward:
- Legacy systems continue to send HL7v2 messages exactly as they do today. No changes required on the source side.
- Mirth Connect receives the HL7v2 message on its existing MLLP listener.
- A transformer maps HL7v2 segments to FHIR resources (PID to Patient, OBX to Observation, PV1 to Encounter, etc.).
- The FHIR resource is either stored in a FHIR server or forwarded to the destination via FHIR RESTful API.
- An ACK is returned to the source system, maintaining backward compatibility.
This approach has a critical advantage: the source systems do not need to change. The hundreds of HL7v2 interfaces that feed your integration engine continue to work exactly as they do today. The FHIR translation happens at the integration layer, invisible to the upstream systems. For a technical walkthrough of building this bridge, see our guide on turning HL7v2 streams into FHIR APIs using Mirth Connect.
Resource Mapping Challenges
Mapping HL7v2 segments to FHIR resources is the most labor-intensive part of the migration. It is not a one-to-one translation. HL7v2 is message-centric (events trigger messages), while FHIR is resource-centric (state is represented as resources). This fundamental difference creates mapping complexity.
Key Mapping Pairs
- PID → Patient: Relatively straightforward. Name, DOB, gender, identifiers, address, phone. Complications: HL7v2 allows multiple names without clear type indicators; FHIR requires name use types (official, nickname, maiden). HL7v2 race and ethnicity codes may not map cleanly to FHIR value sets.
- PV1 → Encounter: Moderate complexity. Patient class, admit/discharge dates, location, attending physician. Complications: HL7v2 PV1 combines visit information with provider assignments; FHIR separates these into Encounter and Practitioner resources with references.
- OBR → ServiceRequest / DiagnosticReport: High complexity. An HL7v2 OBR can map to a ServiceRequest (the order), a DiagnosticReport (the result), or both. The mapping depends on the message context (ORM vs ORU).
- OBX → Observation: Moderate to high complexity. HL7v2 OBX segments can carry numeric results, coded results, text results, dates, and even structured data. FHIR Observation has specific value types. The OBX-2 field (value type) determines the mapping, but site-specific usage often deviates from the standard.
- IN1 → Coverage: High complexity. Insurance information in HL7v2 is deeply nested with subscriber information, group details, and plan identifiers that map to multiple FHIR resources (Coverage, Organization, RelatedPerson).
- DG1 → Condition: Moderate complexity. Diagnosis codes map reasonably well, but HL7v2 DG1 carries diagnosis type (admitting, working, final) that FHIR represents differently through Condition.verificationStatus and Condition.category.
- AL1 → AllergyIntolerance: Moderate complexity. Allergy type and severity mappings are generally clean, but free-text allergy descriptions in HL7v2 do not map well to FHIR's structured coding requirements.
Building the Translation Layer
For each HL7v2 message type you need to bridge, create a dedicated Mirth Connect channel:
Channel Architecture:
ADT_TO_FHIR_PATIENT - ADT messages → Patient + Encounter resources
ORM_TO_FHIR_ORDER - ORM messages → ServiceRequest resources
ORU_TO_FHIR_RESULTS - ORU messages → DiagnosticReport + Observation resources
SIU_TO_FHIR_SCHEDULE - SIU messages → Appointment + Schedule resources
RDE_TO_FHIR_MEDICATION - RDE messages → MedicationRequest resources
MDM_TO_FHIR_DOCUMENT - MDM messages → DocumentReference resourcesEach channel follows the same pattern: receive HL7v2, transform to FHIR JSON, validate against FHIR profiles, and send to the FHIR server or destination. Following channel design patterns ensures these translation channels are maintainable and testable.
Phase 3: New Interfaces FHIR-First (Months 10-18)
Once the bridge is operational, establish a policy: all new integrations are built natively in FHIR. No new HL7v2 interfaces. Period.
What FHIR-First Means in Practice
- New partner integrations: When a new referral partner, lab, or payer needs data exchange, the integration is built on FHIR R4 from day one. If the partner cannot speak FHIR, they use the bridge.
- New application integrations: Patient portals, mobile apps, clinical decision support, population health tools — all connect via FHIR APIs using SMART on FHIR authorization.
- New regulatory requirements: CMS API mandates, TEFCA exchange patterns, and USCDI data sharing are all built on FHIR natively.
- Internal system modernization: When legacy systems are replaced or upgraded, new interfaces are built in FHIR, and the old HL7v2 interface is decommissioned.
Building Your FHIR Infrastructure
FHIR-first requires infrastructure that most organizations need to build:
- FHIR server: A repository that stores and serves FHIR resources. Options range from open-source (HAPI FHIR) to commercial (Smile CDR, Firely, cloud offerings from AWS/Azure/GCP).
- SMART on FHIR authorization: OAuth 2.0-based authorization for patient and provider access to FHIR APIs.
- FHIR validation: Automated validation of FHIR resources against US Core profiles and organization-specific profiles.
- Developer portal: Documentation, sandbox environment, and API keys for internal and external developers consuming your FHIR APIs.
- Subscription/notification: FHIR Subscriptions (R4) or FHIR Topic-Based Subscriptions (R5) for event-driven data exchange, replacing the HL7v2 trigger event model.
Phase 4: Gradual Conversion (Months 19-36)
With the bridge operational and new interfaces FHIR-first, begin converting existing HL7v2 interfaces to native FHIR. Prioritize by the scoring model from Phase 1: regulatory urgency first, then business value, then technical readiness.
Conversion Process per Interface
- Identify the target state: Define which FHIR resources, profiles, and exchange patterns will replace the HL7v2 interface.
- Build and test the FHIR interface: Create the new FHIR-based integration and validate it in a test environment with real message patterns.
- Run in parallel: Operate both the HL7v2 and FHIR interfaces simultaneously for 2-4 weeks. Compare outputs to verify consistency.
- Cut over: Switch the consuming system from the HL7v2 feed to the FHIR API. Keep the HL7v2 interface in standby mode.
- Monitor and stabilize: Monitor the FHIR interface for 2-4 weeks. Address any issues.
- Decommission: Disable and archive the HL7v2 interface. Document the decommission for audit purposes.
What to Convert Last (or Never)
Some HL7v2 interfaces will be the last to convert and some may never convert:
- Medical device interfaces: Devices with embedded firmware that sends HL7v2 messages. These will not change until the device is replaced (often a 10-15 year capital cycle).
- Reference lab interfaces: Large national labs (Quest, LabCorp) process billions of HL7v2 messages. They will support FHIR eventually, but HL7v2 will remain their primary interface for years.
- Legacy vendor interfaces: Systems from vendors that are no longer in business or no longer investing in the product. If the system cannot be upgraded, the interface stays on HL7v2 until the system is replaced.
- High-volume, low-complexity interfaces: A simple ADT feed to a downstream system that processes 50,000 messages per day with no transformation. The HL7v2 interface works, the migration adds no value, and the risk of disrupting a high-volume feed is not justified.
Common Pitfalls
These are the mistakes that turn an 18-month migration into a 36-month project or cause the project to fail entirely.
Boiling the Ocean
Trying to migrate all interfaces simultaneously. This fails because resources are spread too thin, testing becomes overwhelming, and the organization cannot absorb that much change at once. Migrate in waves: 5-10 interfaces per wave, with stabilization periods between waves.
Ignoring HL7v2 Maintenance
During the migration, HL7v2 interfaces still need maintenance. New partners still need HL7v2 interfaces (if they do not support FHIR). Existing interfaces need bug fixes and updates. If all engineering resources are allocated to the FHIR migration, HL7v2 maintenance suffers, and production issues pile up. Allocate at least 30% of integration team capacity to HL7v2 operations during the migration.
Underestimating Mapping Complexity
HL7v2 to FHIR mapping is harder than it looks. The standards are well-documented, but site-specific customizations — Z-segments, local code translations, non-standard field usage — make every organization's mapping unique. Budget 2-3x your initial time estimate for mapping and validation. For guidance on tackling the most common integration challenges, review the top 10 Mirth Connect integration failures.
Skipping the Parallel Run
Cutting over from HL7v2 to FHIR without running both in parallel is like deploying to production without testing. The parallel run catches data discrepancies, missing mappings, and edge cases that testing alone will not find. It adds 2-4 weeks per interface but prevents data loss and clinical workflow disruptions.
No Rollback Plan
Every conversion must have a rollback plan. If the FHIR interface fails in production, you need to revert to HL7v2 within minutes, not hours. Keep the HL7v2 interface in standby mode for at least 30 days after cutover. This is non-negotiable for patient safety interfaces.
Timeline and Cost by Organization Size
These estimates are based on actual migration projects and assume a dedicated integration team with HL7v2 and FHIR expertise.
Small Organization (10-50 HL7v2 Interfaces)
- Timeline: 12-18 months for Phase 1-3, ongoing Phase 4
- Team: 2-3 integration engineers + project manager
- Cost: $150,000-$300,000 (engineering + infrastructure)
- Key risk: Single point of failure if only 2 engineers on team
Mid-Size Organization (50-200 HL7v2 Interfaces)
- Timeline: 18-30 months for Phase 1-3, 12-18 months for Phase 4
- Team: 4-6 integration engineers + architect + project manager
- Cost: $400,000-$800,000 (engineering + infrastructure + FHIR server licensing)
- Key risk: Scope creep as stakeholders add requirements mid-migration
Large Organization (200+ HL7v2 Interfaces)
- Timeline: 24-36 months for Phase 1-3, 18-36 months for Phase 4
- Team: 8-12 integration engineers + 2 architects + program manager + QA
- Cost: $1,000,000-$3,000,000 (engineering + infrastructure + licensing + consulting)
- Key risk: Organizational change fatigue and competing priorities with EHR upgrades
These costs assume the organization already has Mirth Connect or an equivalent integration engine. If the integration engine itself needs to be replaced or upgraded, add 20-30% to the budget and 3-6 months to the timeline. For organizations still on the open-source version, review our guide on Mirth Connect migration strategies before starting the FHIR migration.
The Role of Mirth Connect in Migration
Mirth Connect serves as the bidirectional translation engine at the center of your migration strategy. It plays different roles in each phase:
- Phase 1 (Assessment): Mirth's channel statistics and message logs provide the data you need to inventory interfaces, measure volumes, and classify criticality.
- Phase 2 (Bridge): Mirth's transformation engine converts HL7v2 messages to FHIR resources in real time. The FHIR Connector sends and receives FHIR resources via RESTful APIs.
- Phase 3 (FHIR-First): Mirth serves as the FHIR API gateway for new integrations, routing FHIR requests to the appropriate backend systems.
- Phase 4 (Conversion): Mirth supports parallel running of HL7v2 and FHIR interfaces, comparing outputs for validation before cutover.
The key architectural decision is whether Mirth Connect remains the long-term FHIR API layer or is supplemented by a dedicated FHIR server. For most organizations, Mirth handles the translation and routing while a FHIR server (HAPI FHIR, Smile CDR) serves as the persistence and API layer. This separation of concerns keeps the architecture clean and allows each component to be optimized for its role. For performance considerations, see our guide on Mirth Connect performance tuning.
Measuring Migration Progress
Track these metrics to demonstrate progress and identify bottlenecks:
Metric Target Frequency
Interfaces inventoried 100% Phase 1
FHIR readiness assessed 100% Phase 1
Bridge channels operational Top 10 by Q2 Quarterly
New interfaces built in FHIR 100% Monthly
HL7v2 interfaces converted to FHIR 20% per year Quarterly
FHIR resource validation pass rate >95% Weekly
Parallel run discrepancy rate <1% Per conversion
Mean time to convert one interface <4 weeks Per conversion
HL7v2 interfaces decommissioned Tracked Quarterly
Patient Access API availability 99.9% WeeklyBuilding interoperable healthcare systems is complex. Our Healthcare Interoperability Solutions team has deep experience shipping production integrations. We also offer specialized Healthcare Software Product Development services. Talk to our team to get started.
Frequently Asked QuestionsCan we skip HL7v2 and go straight to FHIR for new systems?
Yes, and you should. If a new system supports FHIR R4, build the integration in FHIR from the start. There is no reason to build a new HL7v2 interface and then migrate it later. The FHIR-first policy (Phase 3) should apply to all new integrations regardless of where you are in the overall migration timeline. This is the single highest-impact decision you can make.
What about FHIR R5? Should we wait?
No. FHIR R4 is the current regulatory standard and will remain so for the foreseeable future. CMS mandates reference R4 specifically. FHIR R5 was published in 2023 but is not yet required by any US regulation. Build on R4 now. When R5 adoption grows, the migration from R4 to R5 is significantly easier than from HL7v2 to FHIR — it is an upgrade within the same paradigm, not a paradigm shift.
How do we handle Z-segments that have no FHIR equivalent?
Z-segments carry site-specific data that may or may not have a FHIR equivalent. Options: (1) Map to FHIR extensions if the data fits an existing resource. (2) Create custom FHIR profiles with extensions for data that does not map to standard resources. (3) Carry the data as a contained resource or use a Basic resource for truly unique data elements. (4) Evaluate whether the data is still needed — many Z-segments carry legacy data that is no longer used.
What if our EHR vendor says they will handle the FHIR migration?
EHR vendors provide FHIR APIs for data that lives in the EHR. This covers some of your integration needs but not all. You still need to handle: data from non-EHR systems (lab instruments, medical devices, specialty systems), data transformation between different FHIR profiles, routing and orchestration across multiple FHIR endpoints, and integration with external partners who may use different FHIR implementation guides. Your integration engine complements the EHR's FHIR capabilities; it does not replace them.
How do we maintain data consistency during the parallel run phase?
During parallel run, both the HL7v2 and FHIR interfaces are active, but only one is authoritative. Typically the HL7v2 interface remains authoritative during the parallel period. The FHIR output is compared against the HL7v2 output for consistency. Discrepancies are logged and investigated. The FHIR interface becomes authoritative only after the parallel run demonstrates acceptable consistency (less than 1% discrepancy rate) for at least two weeks. For understanding how to build reliable integration architectures that support this kind of dual-running, review our article on how EHR integration unlocks seamless interoperability.
The Bottom Line
Migrating from HL7v2 to FHIR is not a project with a finish line. It is a transition that will take most organizations 3-5 years of active migration and another 5 years of coexistence before HL7v2 is truly retired (if it ever is). The organizations that succeed treat it as a phased program with clear priorities, realistic timelines, and continuous progress — not a big bang conversion.
Start with the inventory. Know what you have. Build the bridge. Keep HL7v2 flowing while you stand up FHIR capabilities. Go FHIR-first for everything new. Convert existing interfaces gradually, prioritized by regulatory urgency and business value. And accept that some HL7v2 interfaces will outlast your career at the organization.
The practical path is not the exciting path. It does not make for a compelling conference keynote. But it is the path that actually works for organizations with real patients, real budgets, and real legacy systems that cannot be turned off for a migration weekend. And in healthcare, the approach that works is always preferable to the approach that sounds impressive but fails when it meets reality.
