Chartferry

Mapping HL7 v2 to FHIR in Mirth Connect

FHIR obligations keep arriving. CMS-0057-F requires regulated payers to stand up FHIR APIs, with operational provisions from 2026 and most API requirements from January 2027, and providers face their own API requirements. Yet in most organisations the data those APIs need still arrives as HL7 v2, through the integration engine.

That makes Mirth Connect a natural place to produce FHIR resources from existing feeds. This post covers the mapping decisions that make such a channel trustworthy. The HL7 v2-to-FHIR Implementation Guide published by HL7 is the reference to read alongside it.

Shape of the channel

A typical v2-to-FHIR channel:

  1. receives the existing v2 feed, often from a Channel Writer on the channel that already handles it, so the original interface is untouched;
  2. builds FHIR resources in a JavaScript transformer, as JSON;
  3. sends them to a FHIR server or API layer with an HTTP Sender, often as a transaction Bundle so related resources succeed or fail together;
  4. inspects the server's response and treats an OperationOutcome error as a failure, not a success.

Keeping the FHIR channel separate from the clinical feed means a FHIR server outage queues FHIR work without delaying the results feed.

Patient from PID

  • Identifiers (PID-3). PID-3 repeats, and each repetition carries an assigning authority and identifier type. Map each to a Patient.identifier with a stable system URI per assigning authority. Agree those URIs once, document them, and never change them, because every downstream match depends on them.
  • Name (PID-5). Map family and given names, and carry the name type code where present.
  • Birth date (PID-7). v2 timestamps may include time and precision. FHIR birthDate is a date; truncate deliberately.
  • Administrative sex (PID-8). Map local codes to FHIR's male, female, other and unknown. Write the mapping table down; many sources use local codes beyond M and F.
  • Address and telecom (PID-11, PID-13, PID-14). Repeating fields with use codes; map the use codes rather than dropping them.

Decide how you will find an existing Patient before creating one. Conditional create or update on a business identifier avoids duplicates; creating a new Patient per message does not.

Encounter from PV1

  • Class (PV1-2). Map patient class to the FHIR encounter class codes, for example inpatient, ambulatory and emergency. Local values are common; document each.
  • Visit number (PV1-19). Use it as the Encounter identifier, again with a stable system.
  • Status. Derive from the trigger event: an admit, a discharge and a cancel mean different statuses. ADT event semantics matter more than any single field.
  • Locations and practitioners (PV1-3, PV1-7 and others) become references, which means deciding whether you create Location and Practitioner resources or reference ones that already exist.

Observation from OBR and OBX

  • Code (OBX-3). Carry the code and coding system. If the source uses local codes, include them and add a LOINC coding where you have a reliable map; never invent one.
  • Value (OBX-5 with OBX-2). The value type in OBX-2 decides the FHIR value: numeric to a Quantity with units from OBX-6, coded to a CodeableConcept, text to a string. Do not flatten everything to strings.
  • Status (OBX-11). Map result status codes, for example final, preliminary and corrected, to Observation.status. Corrected results should update the existing Observation, not create a second one, which again depends on stable identifiers.
  • Reference ranges and abnormal flags (OBX-7, OBX-8) map to referenceRange and interpretation.
  • Grouping. OBR becomes a DiagnosticReport that references its Observations, keeping the order and result structure intact.

Coverage from IN1

For payer-facing work, IN1 segments map to Coverage: the plan, member identifiers, subscriber relationship and period. Payer and plan identifiers need the same stable-system discipline as patient identifiers.

Decisions to write down

  • the system URI for every identifier source;
  • every local code table and its FHIR mapping;
  • how updates, corrections and cancellations are handled;
  • what the channel does when the FHIR server rejects a resource;
  • what is deliberately not mapped, and why.

That document is what lets someone else maintain the channel, and it is the first thing an auditor or API consumer will ask for.

Testing

Test with real message variety, not a single sample: every trigger event, repeating fields, empty fields and corrected results. Validate the resources you produce against the profiles your API must meet before they reach production.

We build these channels as part of our interface build and FHIR enablement work, on the engine you already run.

Chartferry is independent and is not affiliated with, endorsed by, or a reseller of NextGen Healthcare. Mirth Connect is a trademark of NextGen Healthcare, Inc.