HL7v2 → FHIR Integration

An interface engine channel that turns legacy clinical messages into FHIR R4 Observations

Designed and built end to end by Margarita Montañez Davenport — channel design, transformation logic, test suite, and containerized deployment.

Demonstrated end to end: legacy HL7v2 messages converted by the interface engine are admitted or refused by the same participant-held consent gate that governs wearable data (synthetic messages, test network).

What an Interface Engine Does

Clinical systems exchange much of their data as HL7v2: pipe-delimited messages carrying lab results, admissions, and orders. Approximately 95% of US healthcare organizations use HL7v2 (HL7 International). Modern systems speak FHIR, a JSON-based API standard. An interface engine is the translation layer between the two. It listens on a network port, receives each HL7v2 message, converts it field by field into FHIR, delivers the result, and sends the sender a receipt confirming arrival. FHIR-native systems rely on that layer to receive HL7v2 traffic.

  • Receives HL7v2 ORU^R01 result messages over MLLP
  • Emits FHIR R4 Observation resources
  • Returns an HL7 acknowledgment for every message

Channel Architecture

One channel, three stages. An MLLP listener accepts HL7v2 ORU^R01 messages on port 6661. A JavaScript transformer maps each OBX segment to a FHIR R4 Observation: LOINC code, value and UCUM unit from the OBX, effective time from OBR-7, and a Patient reference from PID-3. A file writer delivers each Observation as JSON. The acknowledgment is generated once delivery completes, so an AA receipt means the Observation was written.

  • MLLP listener → JavaScript transformer → FHIR R4 Observation file writer
  • Heart rate — LOINC 8867-4 (/min)
  • Step count — LOINC 41950-7 ({steps})
  • Sleep duration — LOINC 93832-4 (min)
  • LOINC mappings shared with the wearable-to-FHIR module

Licensing Landscape

With version 4.6 (March 2025), Mirth Connect became closed-source under a commercial license. The community forked version 4.5.2, the last open-source release, into Open Integration Engine (OIE) and BridgeLink. This build targets OIE deliberately. It is the same decision pattern as catching the Fitbit API deprecation before building against it: read the platform’s trajectory first, then build on the line that stays open.

  • Mirth Connect closed-source from v4.6 (March 2025)
  • v4.5.2 forked into Open Integration Engine and BridgeLink
  • Built on Open Integration Engine 4.5.2

Pipeline

Channel pipeline: MLLP listener, JavaScript transformer, file writer MLLP listener HL7v2 ORU^R01 on port 6661 JavaScript transformer OBX → FHIR R4 Observation LOINC 8867-4 · 41950-7 · 93832-4 File writer Observation JSON per result

Input: HL7v2 ORU^R01 (synthetic)

MSH|^~\&|WEARABLE-SIM|SYNTHETIC-SITE|HL7-MIRTH-BRIDGE|SYNTHETIC-TEST|20260914071500-0400||ORU^R01^ORU_R01|SYNHR0001|P|2.5.1
PID|1||SYN-000001^^^SYNTHETIC^MR||TEST^PATIENT^ALPHA
OBR|1||SYNHR0001-OBR|8867-4^Heart rate^LN|||20260914071500-0400
OBX|1|NM|8867-4^Heart rate^LN||62|/min^/min^UCUM|||||F|||20260914071500-0400

Output: FHIR R4 Observation

{
  "resourceType": "Observation",
  "id": "oru-SYNHR0001-1",
  "status": "final",
  "category": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/observation-category",
          "code": "vital-signs",
          "display": "Vital Signs"
        }
      ]
    }
  ],
  "code": {
    "coding": [
      {
        "system": "http://loinc.org",
        "code": "8867-4",
        "display": "Heart rate"
      }
    ],
    "text": "Heart rate"
  },
  "subject": {
    "reference": "Patient/SYN-000001"
  },
  "effectiveDateTime": "2026-09-14T07:15:00-04:00",
  "valueQuantity": {
    "value": 62,
    "unit": "beats/minute",
    "system": "http://unitsofmeasure.org",
    "code": "/min"
  }
}

Test run — 2026-09-28: 6/6 passing

vitest v5.0.1

 Test Files  1 passed (1)
      Tests  6 passed (6)
   Start at  20:35:07
   Duration  2.21s (tests 77%, import 22%, transform 1%)
Download the exported channel (XML) →
6/6
Test Messages Passing (AA)
AE
Bad-Message Probe Rejected
3
LOINC Mappings
0
Real PHI — All Synthetic
4.5.2
Open Integration Engine

Test Results & Build

Six synthetic ORU^R01 messages, two per metric, are sent to the running engine over MLLP. All six pass: each returns an AA acknowledgment for its message control ID, and each written Observation validates against the official HL7 FHIR R4 JSON Schema with the expected LOINC code, value, and unit. A deliberately bad probe message with an unmapped code received AE, as expected, and produced no output.

  • 6 of 6 synthetic ORU^R01 messages passing with AA acknowledgment
  • Bad-message probe received AE, as expected
  • Zero real PHI — all synthetic (TEST^PATIENT^ALPHA/BRAVO, IDs SYN-000001/2)
  • Engine: Open Integration Engine 4.5.2 (OIE fork), running via Docker/Colima on an arm64 Mac under qemu emulation
  • Repository: mmdavenport/hl7-mirth-bridge (private)