HL7 v2.x Transformation

Overview

InteropSuite transforms HL7 v2.x messages into validated FHIR R4 bundles. The transformation engine supports 30 message types across ADT, ORU, ORM, SIU, MDM, VXU, RDS, RDE, and DFT families.

Supported Message Types

InteropSuite supports 30 HL7 v2.x message types:

ADT - Admission/Discharge/Transfer (12 types)

ORU - Observation Results (3 types)

ORM/OML - Orders (2 types)

SIU - Scheduling (5 types)

MDM - Medical Documents (3 types)

Other Message Types (5 types)

Usage

Basic Transformation

// Activate license (once at startup)
Interop.ActivateLicense(licenseKey);

// Transform HL7 message
var result = await Interop.HL7ToFhirAsync(hl7Message);

if (result.Success)
{
    // Access the FHIR bundle (JSON)
    string fhirJson = result.FhirBundle;

    // Check detected message type
    string messageType = result.DetectedFormat; // e.g., "ADT^A01"
}
else
{
    // Handle errors
    foreach (var error in result.Errors)
        Console.WriteLine(error);
}

Batch Processing

Process multiple HL7 files at once. For mixed workloads, use unified batch processing (recommended).

Unified Processing Recommended

using InteropSuite.Fhir.Engine.Batch;

// Process all formats with RoundRobin interleaving
var options = new BatchOptions
{
    Sources = new[]
    {
        new BatchSource("./input/hl7", "HL7", OutputFormat.UsCore),
        new BatchSource("./input/x12", "X12", OutputFormat.UsCore),
        new BatchSource("./input/cda", "CDA", OutputFormat.UsCore),
        new BatchSource("./input/cms", "CMS-0057-F", OutputFormat.Cms0057F),
    }
};

var result = await Interop.ProcessBatchAsync(options);

Sequential Processing

// Process HL7 files only
var options = new BatchOptions
{
    Domain = "HL7",
    OutputFormat = OutputFormat.UsCore
};

var result = await Interop.ProcessBatchAsync("./input/hl7", options);

Console.WriteLine($"Processed: {result.TotalFiles} files");
Console.WriteLine($"Succeeded: {result.Succeeded}");

See User Guide: Batch Processing for complete documentation.

FHIR Mapping

HL7 segments map to FHIR resources with US Core profiles:

Data Requirements

Required Segments

• MSH - Message header (always required)
• PID - Patient identification (required for most messages)

Recommended for Complete Output

• PV1 - Patient visit information for Encounter
• DG1 - Diagnosis codes for Conditions
• OBX - Observations with LOINC codes
• OBR - Order information for DiagnosticReport

Code Systems

For optimal FHIR output, use standard code systems:

• LOINC - Lab tests, vital signs (OBX-3)
• SNOMED CT - Clinical findings, procedures
• ICD-10-CM - Diagnoses (DG1-3)
• CPT/HCPCS - Procedures (PR1-3)
• CVX - Vaccines (RXA-5)
• NDC - Medications (RXE-2)

Examples

ADT A01 - Patient Admission

MSH|^~\&|SENDING|FACILITY|RECEIVING|DEST|20240115120000||ADT^A01|MSG001|P|2.5.1
EVN|A01|20240115120000
PID|1||MRN12345^^^HOSP^MR||Smith^John^Q||19800515|M|||123 Main St^^Boston^MA^02101
PV1|1|I|ICU^101^A|E|||12345^Jones^Sarah|||MED||||7|||12345^Jones^Sarah|I|||||||||||||||||||HOSP|||||20240115100000
DG1|1||I10^Essential Hypertension^ICD10|||A
AL1|1|DA|00000741^Penicillin^RXNORM|SV|Rash

ORU R01 - Lab Results

MSH|^~\&|LAB|FACILITY|EHR|DEST|20240115140000||ORU^R01|MSG002|P|2.5.1
PID|1||MRN12345^^^HOSP^MR||Smith^John^Q||19800515|M
OBR|1|ORD001|LAB001|24323-8^CBC^LN|||20240115130000|||||||20240115133000||12345^Jones^Sarah
OBX|1|NM|6690-2^WBC^LN||7.5|10*3/uL|4.5-11.0|N|||F
OBX|2|NM|789-8^RBC^LN||4.8|10*6/uL|4.2-5.9|N|||F
OBX|3|NM|718-7^Hemoglobin^LN||14.2|g/dL|12.0-17.5|N|||F

VXU V04 - Immunization

MSH|^~\&|EHR|CLINIC|IIS|STATE|20240115150000||VXU^V04|MSG003|P|2.5.1
PID|1||MRN12345^^^CLINIC^MR||Smith^John^Q||19800515|M
RXA|0|1|20240115||141^Influenza^CVX|0.5|mL|IM|LA^Left Arm|||||||||||CP|A