Migrating from HL7 to FHIR

What does migrating from HL7 to FHIR involve?

Migrating from HL7 to FHIR means moving data exchange from HL7 v2 messages to FHIR resources and APIs, interface by interface. It involves inventorying current interfaces, choosing which to move and in what order, mapping v2 content to FHIR, running both formats side by side, and cutting over partners once the FHIR version is proven.

The work is as much about partners and operations as about mapping. Every interface has a system and a team on the other end, and each one needs to be ready, tested and supported before its v2 feed is switched off.

Should every HL7 v2 interface move to FHIR?

No. Many high-volume internal feeds, such as admissions to a lab system or results from an instrument middleware, work well in v2 and gain little from moving. Migrate where FHIR adds value: apps, partner access, patient access, analytics and new integrations.

• Strong candidates: Point-to-point feeds that serve apps or partners, custom extracts, and interfaces that need queries rather than pushes.
• Regulatory drivers: Patient access and payer exchange that rules expect to run on FHIR APIs.
• Weak candidates: Stable device and lab feeds where both ends only speak v2 and nothing new is planned.
• Defer: Interfaces whose partner systems are due for replacement; migrate with the replacement instead.

A realistic target is a hybrid estate in which FHIR becomes the default for new work and v2 remains where it is cheapest and safest, with both governed by the same integration team.

How do you inventory existing interfaces?

Inventory existing interfaces by exporting every channel from the interface engine and documenting each one's source, destination, message types, volume, owner and business purpose. Most organizations find interfaces nobody remembers and some that no longer carry traffic.

• Technical details: Message types and trigger events, such as ADT^A01 or ORU^R01, segments used, custom Z-segments and transport.
• Volume and timing: Messages per day, peak rates and how quickly the receiver needs them.
• Ownership: The business owner, the technical owner and the partner contact.
• Dependencies: Downstream systems and reports that rely on the feed.
• Customizations: Local code tables, field reuse and transformations in the engine.
• Status: Active, low-use or dead, based on recent traffic.

Retire dead interfaces before migrating anything. It shrinks the program and removes risk at no cost.

Keep the inventory as a living record, not a one-off spreadsheet. Each interface's migration status, mapping version and cutover date belongs there too, so the program can report progress and anyone can see which format a partner receives today.

How do you choose which interfaces to migrate first?

Choose first those interfaces where FHIR brings clear value, the partner is ready and the risk of failure is low. Score each interface on these three factors and start with a few that score well, to build skills and reusable mappings.

• 1. Value: New capability, lower maintenance or a regulatory need met by moving the interface.
• 2. Readiness: The partner system supports FHIR R4 and the partner has time to test.
• 3. Risk: Clinical impact if the interface fails, and how easily you can roll back.
• 4. Reuse: Whether the mapping work, such as patient and encounter resources, will be reused by later interfaces.

Patient demographics and encounters are usually the foundation. Almost every later interface depends on Patient, Encounter, Practitioner and Organization resources, so mapping those well first saves time on every interface that follows.

What does the V2-to-FHIR implementation guide provide?

HL7's V2-to-FHIR implementation guide provides published mappings from v2 messages, segments, data types and vocabulary to FHIR R4 resources. It is a trial-use guide, and its vocabulary mappings are published as FHIR ConceptMaps.

• Message mappings: How a v2 message structure, such as an ADT or ORU message, becomes a set of FHIR resources.
• Segment mappings: How each segment, such as PID or OBX, maps to resource elements.
• Data type mappings: How v2 data types such as XPN names or CWE coded values map to FHIR data types.
• Vocabulary mappings: ConceptMaps that translate v2 tables to FHIR code systems.

Use the guide as the starting point, not the finished answer. Local Z-segments, reused fields and site-specific code tables still need mapping decisions, and those should be documented and reviewed like any other clinical data decision.

How do HL7 v2 and FHIR run side by side?

HL7 v2 and FHIR run side by side through an interface engine or integration layer that converts between them, so each partner receives the format it supports while the source system keeps sending what it sends today.

• Conversion in the engine: v2 messages arrive as now, are converted to FHIR resources, and are posted to a FHIR server or partner API.
• FHIR facade: A FHIR API sits in front of a legacy system, answering queries from its data without changing it.
• Dual delivery: During testing, the same event goes to a partner as both v2 and FHIR, so results can be compared.
• Central FHIR store: Converted resources are stored in a FHIR server that apps and partners query directly.

Side-by-side operation can last years. Plan monitoring, alerting and support for both formats as permanent services, not temporary scaffolding.

Event feeds need particular care. Replace v2 event feeds with FHIR Subscriptions, which notify a partner when matching resources change, or with REST calls that the source sends when an event occurs. Polling a FHIR server for changes is a poor substitute for a real-time v2 feed.

ONC's API standards at 45 CFR 170.215 adopt FHIR R4.0.1 and reference the Subscriptions R5 Backport implementation guide, which brings topic-based subscriptions to FHIR R4 servers. Check that both the source and the receiving systems support the same subscription approach before committing to it.

Ordering is the other trap. A v2 feed delivers events in sequence over one connection, so an admission always arrives before its transfer. FHIR notifications and REST calls can arrive out of order or more than once, so receivers need to check resource versions and timestamps and handle repeats safely.

How do you test a migrated interface?

Test a migrated interface with a parallel run: send the same real events through both the v2 path and the FHIR path, compare what the receiver ends up with, and fix differences until they disappear.

• Sample library: Build a library of real, de-identified messages covering common and unusual cases.
• Field comparison: Compare every mapped field between the v2 result and the FHIR result automatically.
• Edge cases: Test merges, corrections, cancellations, out-of-order events and missing fields.
• Volume: Run peak-hour message rates to confirm the FHIR path keeps up.
• Clinical review: Have clinicians or analysts check a sample of results in the receiving system.

Automate the comparison and keep it. The same comparison tooling becomes the regression suite for every later change to the mapping, the FHIR server or the source system, which is where most of its long-term value lies.

Agree pass criteria before the run starts. For example, zero differences in identifiers, codes and values, and only documented, accepted differences in formatting. Without agreed criteria, parallel runs tend to drag on as each new difference is debated.

How do you plan the cutover?

Plan the cutover per interface, with a date agreed with the partner, a rollback plan, and a period of close monitoring after the switch. Keep the v2 path available, but idle, until the FHIR path has run cleanly for an agreed time.

• 1. Sign-off: Business owner and partner confirm parallel-run results.
• 2. Schedule: Pick a low-volume window and confirm support staff on both sides.
• 3. Switch: Route live traffic to the FHIR path and stop v2 delivery to that partner.
• 4. Monitor: Watch error rates, latency and reconciliation reports closely for the first weeks.
• 5. Retire: Decommission the v2 channel once the agreed clean period has passed.

What usually goes wrong in HL7 to FHIR migrations?

Migrations usually go wrong when hidden v2 customizations surface late, when identifiers do not line up across systems, or when partners are not ready on the agreed date.

• Hidden customizations: Fields reused for local purposes that nobody documented.
• Identifier mismatches: Patient, encounter and practitioner identifiers that differ between systems.
• Lost events: Corrections and cancellations that the FHIR path handles differently.
• Partner delays: Partner systems that support FHIR on paper but not the resources needed.
• Scope creep: Migration used as an opportunity to redesign every workflow at once.
• Unowned FHIR server: A new FHIR store goes live with no team responsible for its uptime, upgrades and security.

Most of these are visible early to anyone who looks. A thorough inventory exposes customizations, an identifier review before mapping exposes mismatches, and a short technical call with each partner exposes readiness gaps months before the cutover date.

How Agnotic can help

Agnotic Technologies plans and delivers HL7 v2 to FHIR migrations for clients: interface inventories, prioritization, mappings built from the V2-to-FHIR guide, FHIR facades and servers, subscription-based event delivery, and parallel-run testing.

Agnotic works within the client's interface engine and existing systems, so v2 and FHIR can run side by side for as long as partners need, with each cutover planned and reversible.

Sources

• HL7: V2-to-FHIR Implementation Guide
• 45 CFR 170.215: Application Programming Interface Standards