England Pathology and Laboratory Medicine (PaLM) Technical Framework - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Mapping HL7 v2 and FHIR

This page describes how to convert between the HL7 v2.5.1 messages and the FHIR R4 resources in this guide, in both directions. It follows the HL7 Version 2 to FHIR IG (message, segment, data type and vocabulary maps) and adds the England rules. The mappings are indicative: test them against your own interfaces.

There are four levels:

1. Message - which FHIR container and which resources
2. Segment and field - which element each field goes to
3. Data type - how each HL7 v2 data type becomes a FHIR data type
4. Vocabulary - how HL7 v2 table codes become FHIR codes

Message Level

The Bundle identifier is MSH-10 and timestamp is MSH-7. Each HL7 v2 message becomes one FHIR Message; resources referenced from several segments (the Patient, the requester's PractitionerRole) appear once in the Bundle.

Practitioners and organisations are identifier references in a FHIR Message. HL7 v2 carries only their codes and names - the ODS code (XON-10, MSH-4 / MSH-6, PL-10) and the GMC, GMP or NMC code (XCN-1 with XCN-9). The FHIR Message mirrors that: a Reference with type, identifier and display, and no Practitioner or Organization resource in the Bundle. When a FHIR Document is built (below) they are looked up and added, because the NHS England API needs them.

Segment and Field Level

Field by field mappings are on HL7 v2.5.1 Segments (FHIR column) and on each profile's Mappings tab.

Rules

• One DiagnosticReport per report. In ORU_R01 the OBRs of a PATIENT_RESULT that share a Filler Order Number (OBR-3) are one report - one DiagnosticReport, as NHS England requires for its documents. DiagnosticReport.code is the report type (SNOMED CT 721981007 Diagnostic studies report, LOINC 11502-2), not OBR-4
• Each OBR is a test group. When an OBR has several OBX it becomes an Observation with OBR-4 as code and the OBX as hasMember - NHS England calls this an organizer (for example the FBC, LFT, U&E). When an OBR has a single OBX (a single test, such as HbA1c), that result Observation is used directly. Either way it is one DiagnosticReport.result
• One ServiceRequest per ORC/OBR pair. In ORU_R01 the ServiceRequest carries the order identifiers (ORC-2, ORC-3, ORC-4), OBR-4 as code, and the requester; DiagnosticReport.basedOn and each Observation's basedOn reference it
• Identifier systems are assigned by the receiver. The LIMS sends EI value^namespace (for example REQ-20220307-000046-001^B82033); the FHIR Identifier.system (a URI) is not known at that stage of the pipeline and SHOULD NOT be expected in the HL7 v2 message. The converter - usually the integration engine - assigns it from an agreed table of field (placer order, report, placer specimen, accession) and namespace to system, and keeps the namespace as the assigner (ODS code)
• Placer and filler numbers keep their meaning. Do not copy ORC-3 into a PLAC identifier or ORC-2 into a FILL identifier
• Fixed resource identity. A corrected result (OBR-25 / OBX-11 = C) SHALL update the same DiagnosticReport and Observations. Use stable identifiers - the DiagnosticReport by OBR-3, each Observation by OBR-3 + OBX-3 (+ OBX-4) - and make the FHIR id deterministic from them, not from OBX-1, which can change between versions of a report
• Report comments. NTE after an OBR in ORU_R01 become DiagnosticReport.conclusion (several NTE are joined with new lines); NTE after an OBX become Observation.note
• Text-only reports. A report sent as text - one OBX of type FT with \.br\ line breaks, or several TX OBX with the same OBX-3, one per line as in many microbiology reports - becomes one Observation with the lines joined in valueString, as in the NHS England unstructured examples (GTT, urine MCS), not one Observation per line
• MSH is not clinical. Do not derive the patient's assigning authority, the requester or the performer from MSH-4 / MSH-6 alone

OBX-2 Value Type

An empty OBX-5 with OBX-11 = X (cannot be obtained) or N (not asked) becomes an Observation with no value and dataAbsentReason (error / not-asked).

Reference Ranges

OBX-7 is a string. Parse the common forms; otherwise keep the text.

Embedded Documents

Join split ED OBX (same OBX-3, consecutive) before decoding.

Data Type Level

Vocabulary Level

The HL7 v2 tables that change meaning between HL7 v2 and FHIR are mapped by ConceptMaps in this guide:

Tables used as-is (the FHIR code system is the HL7 v2 table): 0203 Identifier Type (Identifier.type), 0074 Diagnostic Service Section ID (DiagnosticReport.category), 0003 Event Type (MessageHeader.eventCoding).

FHIR to HL7 v2

The same tables read right to left. Points to watch:

• Several FHIR codes map to one v2 code, or none. Use the ConceptMap rows with equivalence equivalent first; registered → OBR-25 I (not O), partial → A, preliminary → P, amended → C, entered-in-error → OBX-11 W
• One DiagnosticReport → one PATIENT_RESULT: one ORC/OBR per ServiceRequest (basedOn), all with OBR-3 = DiagnosticReport.identifier. A test group Observation (with hasMember) becomes the OBR (its code → OBR-4) and its members the OBX; a single result is an OBR with one OBX. OBX-1 is numbered from 1 for each OBR
• Do not send Identifier.system in EI-3 / EI-4 - send value^namespace, the receiver assigns the system
• Identifiers. ServiceRequest.identifier (PLAC) → ORC-2 / OBR-2, (FILL) → ORC-3 / OBR-3; Patient.identifier → PID-3 repeats; an NHS Number SHALL be sent as <number>^^^NHS^NH
• Codes. First coding (SNOMED CT) → CWE-1/2/3, second (LOINC) → CWE-4/5/6
• Quantity with comparator → OBX-2 SN, otherwise NM; valueString → ST (or TX / FT for multi-line text); valueCodeableConcept → CWE
• presentedForm (PDF) → an OBX of type ED, split into chunks if the receiver requires it
• MessageHeader → MSH: sender / destination.receiver ODS codes → MSH-4 / MSH-6, source.name / destination.name → MSH-3 / MSH-5, Bundle.identifier → MSH-10

FHIR Message to FHIR Document

The NHS England Pathology Laboratory Reporting API needs a FHIR Document. From a Laboratory Result (R01) message (or directly from an ORU_R01), for each DiagnosticReport:

1. Look up the Practitioners and Organizations referenced by identifier and add them as resources: organisations from the NHS England Organisation Data Service - the ODS APIs (ORD, or the ODS FHIR API) or the ODS CSV downloads (epraccur.csv GP practices, etr.csv trusts); GP practitioners (GMP codes) from the ODS download egpcur.csv; other clinicians from the system's own practitioner directory
2. Create a Laboratory Report Composition: subject = the Patient, with subject.identifier = the NHS Number; identifier = the DiagnosticReport's Filler Order Number (OBR-3); type = the report type (721981007 and 11502-2, the same as DiagnosticReport.code - HL7 Europe requires the Composition and DiagnosticReport to share an identifier and a code); date = DiagnosticReport.issued; author, attester and custodian = the performing laboratory; one section per test group (OBR) with generated narrative and an entry for its Observation - see Human Readable and Computer Processable
3. Link the DiagnosticReport to the Composition with the R5 DiagnosticReport.composition extension (HL7 Europe DiagnosticReport-eu-lab), and mark each test group Observation with the NHS England Observation.organizer extension
4. Add a Laboratory Report Provenance targeting the Composition, naming the sending product
5. Put the Composition first, then the DiagnosticReport and every resource it references (Patient, ServiceRequest, PractitionerRole, Practitioner, Organization, Specimen, Observations) and the Provenance, in a Bundle of type document with a new identifier and timestamp
6. Set the NHS England meta.profile on every resource and drop the MessageHeader

Worked through for the NHS England examples in notebook 02-fhir-message-to-fhir-document; the HL7 v2 to FHIR Message step is notebook 01-oru-r01-to-fhir-message, and the reverse (FHIR Document to ORU^R01) is scripts/nhse_document_to_oru.py

• see NHS England Examples.

Worked Example

The LAB-3 example ORU^R01 and its FHIR equivalents:

Bundles: FHIR Message and FHIR Document.

For one result, OBX-2:

OBX|2|NM|1022431000000105^Haemoglobin estimation^SCT^718-7^Hemoglobin [Mass/volume] in Blood^LN||112|g/L^^UCUM|115-165|L|||F|||20261103091500|||||||||Manchester University NHS Foundation Trust^^^^^^^^^R0A