HL7 Tools
NEW!

HL7 v2 to FHIR Mapper

Convert HL7 v2.x ADT, ORU, and ORM messages to FHIR R4 Bundle JSON with a detailed field-mapping table. Free, browser-only, HIPAA-compatible.

HIPAA-Compliant by Design

Your medical data never leaves your device. No PHI is transmitted to any server.

HIPAA-Friendly No PHI Transmission Local Processing

Drop .hl7 or .txt file here, or paste below

Examples:

All conversion happens locally in your browser. Your HL7 messages and PHI never leave your device. HIPAA-compatible.

Keywords

hl7 v2 to fhir converterhl7 to fhir r4 mapperhl7 adt to fhirhl7 oru to fhir observationhl7 orm to fhir servicerequesthl7 fhir migration toolhl7 v2 fhir bundle generatorhl7 v2 message to fhir onlinehl7 to fhir r4 free

Need something else?

📨
Try HL7 Message Viewer

Parse and analyze HL7 v2.x messages with field-level detail. Free online viewer for healthcare integration testing.

 📨
Try HL7 Segment Browser

Browse all common HL7 v2.x segments with field definitions and message type schemas. Free reference for healthcare integration analysts.

How to use

1

Paste your HL7 v2 message into the text area or drag and drop a .hl7 file. The tool supports ADT^A01/A03/A04/A08, ORU^R01, and ORM^O01 message types.

2

Select the FHIR Bundle type — Collection (default) or Transaction — and the FHIR version (R4 or R5). Click Convert to FHIR.

3

Review the FHIR Bundle JSON rendered in the output panel. The bundle contains all generated resources (Patient, Encounter, Observation, DiagnosticReport, ServiceRequest) as entries.

4

Inspect the Mapping Table to see every HL7 field that was mapped, which FHIR resource and path it maps to, the original HL7 value, and the resulting FHIR value.

5

Click Copy JSON to copy the bundle to your clipboard, or Download .json to save the file. Use the Warnings panel to identify unmapped or missing fields.

Features

Multi-Message-Type Support

Converts ADT^A01/A03/A04/A06/A08 admit/discharge/update events to Patient + Encounter; ORU^R01 lab results to DiagnosticReport + Observation resources; and ORM^O01 orders to ServiceRequest + Patient — all from the same interface.

FHIR Field-Provenance Mapping Table

Every converted HL7 field is displayed in a provenance table showing the source segment (PID-3), field name (Patient ID List), target FHIR resource (Patient), target path (Patient.identifier[0].value), the original HL7 value, and the mapped FHIR value. Ideal for integration documentation.

Transaction and Collection Bundles

Choose Collection to produce a simple read-only bundle, or Transaction to add RESTful PUT request entries (method + url) to each resource — ready for POST to a FHIR server endpoint.

Warnings for Unmapped Segments

The tool emits warnings for common data quality issues — missing PID-3 identifiers, empty patient names, Z-segments, NK1, IN1, DG1 — that cannot be automatically mapped to R4 resources, helping you identify gaps in your HL7 messages before migration.

Curated Example Messages

Five realistic sample messages covering patient admission, discharge, lab results, lab order, and patient update are available via the Examples bar. Each loads into the tool and converts immediately so you can explore the output without needing real HL7 data.

Why Choose This Tool?

Private by Default — PHI Never Leaves Your Browser

HL7 v2 messages routinely contain patient names, MRNs, diagnoses, and lab results — all Protected Health Information. This tool converts entirely in your browser using JavaScript. No message content is sent to any server, stored in any database, or logged. Healthcare organizations can use it safely on production data from hospital workstations under BYOD policies.

Full Field-Level Traceability

Unlike simple format-converters that produce anonymous FHIR JSON, this tool generates a comprehensive field-mapping table for every conversion. You can see exactly which HL7 segment and field number produced each FHIR value, with the raw HL7 value and the resulting FHIR representation side-by-side. This level of traceability is essential during migration projects and HL7 interface audits.

Standards-Compliant FHIR R4 Output

The generated bundles follow FHIR R4 resource specifications. Patient identifiers use the HL7 v2 type-code system (MR, AN), gender is mapped using the FHIR administrative-gender code set, encounter class codes use the HL7 v3 ActCode vocabulary, and observation values distinguish quantity (NM), text (ST/TX/FT), and coded (CWE/CE) types.

Supports the Full HL7 v2.x ADT, ORU, and ORM Spectrum

ADT events A01 (admit), A03 (discharge), A04 (register outpatient), A06 (transfer to inpatient), A08 (update demographics), and A02/A11/A13 are all handled. ORU^R01 supports multi-OBX result sets. ORM^O01 reads both ORC and OBR segments to populate the ServiceRequest resource. All standard HL7 delimiter variants are supported.

HL7 v2 to FHIR Migration: A Practical Guide to Mapping Messages and Resources

Why HL7 v2 to FHIR Migration Matters

HL7 v2.x has been the backbone of healthcare interoperability since the late 1980s. Hundreds of thousands of hospital interfaces worldwide still exchange ADT, ORU, ORM, and MDM messages over MLLP connections. Yet the industry is steadily shifting to FHIR R4 — driven by US federal regulations (CMS and ONC interoperability rules), SMART on FHIR app ecosystems, and cloud EHR platforms that natively speak REST + JSON. Migration projects must bridge these two worlds: preserving the clinical semantics of existing v2 messages while expressing them in FHIR resource graphs.

The Core Mapping Challenge

HL7 v2 and FHIR represent clinical information very differently. A v2 ADT^A01 message encodes a patient admission in a flat, pipe-delimited structure with segment-level relationships (PID → patient data, PV1 → visit data, EVN → event metadata). FHIR R4 represents the same event as a graph of linked resources: a Patient resource referenced by an Encounter resource, with contained or standalone Location and Practitioner resources. The mapping is conceptually straightforward but operationally complex — every component field in a v2 XPN, XCN, CX, or PL data type must be decomposed and reassembled into the right FHIR datatype.

ADT to Patient and Encounter

The most common migration task is converting ADT^A01 (admit) and ADT^A03 (discharge) messages. The PID segment maps to a FHIR Patient: PID-3 (CX list) becomes Patient.identifier, PID-5 (XPN) becomes Patient.name with family and given components, PID-8 becomes Patient.gender using the administrative-gender vocabulary, and PID-11 (XAD) becomes Patient.address. The PV1 segment maps to a FHIR Encounter: PV1-2 (Patient Class) maps to Encounter.class using the v3 ActCode system, PV1-7 (XCN) maps to Encounter.participant (attender), PV1-19 becomes Encounter.identifier, and PV1-44/PV1-45 become Encounter.period.start and .end.

ORU to DiagnosticReport and Observations

ORU^R01 messages carry laboratory, radiology, and clinical observation results. The OBR segment maps to a FHIR DiagnosticReport: OBR-4 (Universal Service ID, CWE) becomes DiagnosticReport.code, OBR-7 becomes effectiveDateTime, and OBR-14 becomes issued. Each OBX segment maps to a separate FHIR Observation resource, with the result set grouped under DiagnosticReport.result references. The OBX value type field (OBX-2) determines the FHIR observation value type: NM (Numeric) maps to valueQuantity with OBX-6 as the unit, CE/CWE maps to valueCodeableConcept, and ST/TX/FT map to valueString.

ORM to ServiceRequest

ORM^O01 messages represent orders. The ORC segment provides order control (ORC-1), placer order number (ORC-2 → ServiceRequest.identifier), filler order number (ORC-3), order status (ORC-5 → ServiceRequest.status), and ordering provider (ORC-12 → ServiceRequest.requester). The OBR segment contributes the procedure code (OBR-4 → ServiceRequest.code), requested date/time (OBR-6 → ServiceRequest.occurrenceDateTime), and priority (OBR-5 → ServiceRequest.priority).

Key Migration Considerations

  • Identifier systems: HL7 v2 CX identifiers (PID-3, PV1-19) carry an assigning authority. In FHIR, these should become Identifier.system URIs — ideally OIDs (urn:oid:...) or NamingSystem canonical URLs registered in your FHIR server.
  • Terminology: V2 table values (0001 for sex, 0004 for patient class) must be mapped to FHIR-defined code systems. Many organizations need a terminology service or lookup table to handle local codes in OBR-4 or OBX-3.
  • Z-segments: Custom Z-segments (ZDG, ZPI, ZRX) have no FHIR equivalent and require extensions or contained resources, adding project complexity.
  • Versioning: HL7 v2.3.1, v2.4, v2.5, and v2.5.1 differ in field positions and available data types. A robust mapper must handle multiple versions gracefully.
  • Bi-directional flow: Many integration architectures require both v2-to-FHIR and FHIR-to-v2 translation. Design the mapping schema to be reversible where possible.

Frequently Asked Questions

Which HL7 v2 message types are supported?

The tool supports ADT^A01 (admit), ADT^A03 (discharge), ADT^A04 (register outpatient), ADT^A06 (change patient status), ADT^A08 (update demographics), ADT^A02/A11/A13 (transfer/cancel events), ORU^R01 (observation results), and ORM^O01 (general order). Other message types produce a partial Patient bundle from the PID segment with a warning.

What FHIR resources does the converter generate?

ADT messages produce a Patient resource and an Encounter resource. ORU^R01 messages produce a Patient, DiagnosticReport, and one Observation per OBX segment. ORM^O01 messages produce a Patient and a ServiceRequest. All resources are wrapped in a FHIR Bundle.

Is the output valid FHIR R4?

The output follows FHIR R4 resource structures for the supported fields. For production use, validate the bundle against a FHIR validator (e.g., the HL7 FHIR Validator or an implementation guide profile). Patient extensions, local code systems, and unsupported segment data (Z-segments, IN1, DG1) are not represented in the output.

What is the difference between Collection and Transaction bundles?

A Collection bundle is a simple container of resources with no request information — suitable for archiving or display. A Transaction bundle adds a request entry (method: PUT, url: ResourceType/id) to each resource, making it ready to POST to a FHIR server's batch/transaction endpoint for persistence.

Can I use this tool with v2 messages that contain local codes?

Yes. Local and non-standard codes in OBX-3, OBR-4, and other coded fields are preserved as-is in the FHIR coding.code field. The system URI is generated from the HL7 table ID (urn:oid:...). You may need to remap these codes to standard terminologies (LOINC, SNOMED CT) in your production pipeline.

What happens with PHI and HIPAA compliance?

All processing is performed locally in your browser using JavaScript. No HL7 message content is transmitted to any server or stored anywhere outside your browser session. The tool is designed to be HIPAA-compatible for use in healthcare environments. Always verify compliance with your organization's security policies before using any tool with production PHI.

How are Z-segments handled?

Z-segments (custom segments that start with Z) are not mapped to any standard FHIR resource. The tool emits a warning listing the Z-segment names found in the message so you can address them in your custom extension mapping layer.

Can I convert multiple messages at once?

Currently the tool converts one HL7 message per operation. For batch conversion (multiple messages in one file), separate your messages and convert them individually. The tool accepts files via drag-and-drop.

Does this support FHIR R5?

You can select FHIR R5 in the version selector. The R5 output uses the same resource structures as R4 for the supported fields — the primary differences in R4 vs R5 for Patient/Encounter/Observation are in extension patterns and some renamed elements. Validate the R5 output against R5 implementation guides for full compliance.

How do I interpret the mapping table status colors?

Green 'mapped' means the field was fully converted to a FHIR equivalent. Amber 'partial' means the field was partially mapped — for example, only some components of a complex data type (XAD, XCN) were translated. Red 'unmapped' means the field was detected but no standard FHIR mapping exists for it.

Sources

Reviewed by Dr. Marta Ruiz-Castellano, MD MSc — Clinical Informatics Lead · HL7 FHIR Accredited · 14 years in hospital interoperability

Last reviewed: 2026-04-14

Related Articles

hl7-tools

HL7 v2 to FHIR Migration: A Practical Guide for Healthcare Integration Teams

How to map HL7 v2.x ADT, ORU, and ORM messages to FHIR R4 resources. Covers Patient, Encounter, Observation, and ServiceRequest mapping with real examples.

Read more →
Learn more