	Whitepaper

HL7 Message examples: version 2 and FHIR

The contents of this whitepaper are published under the Creative Commons Attribution-Share Alike license.
See https://www.ringholm.com/docs/04350_mapping_HL7v2_FHIR.htm for the latest version of this document.
Editor: René Spronk - Lead Trainer, Ringholm bv
Document status: Version 2.0 (2025-01-21)
Please sent questions and comments to Rene.Spronk@Ringholm.com

Summary

This whitepaper contains a HL7 version 2 to FHIR mapping scenario. This example scenario is based on a FHIR server that supports the messaging interoperability paradigm, whereby the v2 message should be mapped to a FHIR message. The whitepaper aims to show some the differences as well as similarities between example v2.x and FHIR resource instances.

1. Introduction

This whitepaper has the aim to illustrate how v2 message strcutures are present in FHIR. As you're probably aware of, FHIR is not backwards compatible with the v2.x standard although some of the data constructs (e.g. data types) are similar in nature. Please note that it is not the intent of this whitepaper to discuss migration issues from v2.x to FHIR, nor to discuss the circumstances where using FHIR may be more (or less) appropriate than v2.x as a messaging standard. It merely attempts to show some of the similarities between v2.x and FHIR using message examples.

2. FHIR Server - with support for messaging

This section contains an example business use case related to a laboratory results message, as well as a V2.4 and a FHIR R5 message examples. The use case is the completion of a serum glucose laboratory result of 182 mg/dL authored by Howard H. Hippocrates. The laboratory test was ordered by Patricia Primary for patient Eve E. Everywoman. The use case takes place in the US Realm.

2.1 The V2.4 Message

The V2.4 representation of the use-case is a ORU^R01 message. The syntax encoding is based on the classic HL7 v2 syntax, commonly referred to as the vertical-bar syntax. The MSH (Message Header) segment contains the message type, in this case, ORU^R01, which identifies the message type and the trigger event. The sender is the GHH Lab in ELAB-3. The receiving application is the GHH OE system located in BLDG4. The message was sent on 2023-02-15 at 09:30. The MSH segment is the initial segment of the message structure.

 MSH|^~\&|GHH LAB|ELAB-3|GHH OE|BLDG4|202302150930||ORU^R01|CNTRL-3456|P|2.4<cr>
 PID|||555-44-4444||EVERYWOMAN^EVE^E^^^^L|JONES|19620320|F|||153 FERNWOOD DR.^
 ^STATESVILLE^OH^35292||(206)3345232|(206)752-121||||AC555444444||67-A4335^OH^20030520<cr>
 OBR|1|845439^GHH OE|1045813^GHH LAB|1554-5^GLUCOSE|||202302150730|||||||||
 555-55-5555^PRIMARY^PATRICIA P^^^^MD^^|||||||||F||||||444-44-4444^HIPPOCRATES^HOWARD H^^^^MD<cr>
 OBX|1|SN|1554-5^GLUCOSE^POST 12H CFST:MCNC:PT:SER/PLAS:QN||^182|mg/dl|70_105|H|||F<cr>

The PID (Patient Identification) segment contains the demographic information of the patient. Eve E. Everywoman was born on 1962-03-20 and lives in Statesville OH. Her patient ID number (presumably assigned to her by the Good Health Hospital) is 555-44-4444.

The OBR (Observation Request) segment identifies the observation as it was originally ordered: 15545^GLUCOSE. The observation was ordered by Particia Primary MD and performed by Howard Hippocrates MD.

The OBX (Observation) segment contains the results of the observation: 182 mg/dl.

2.2 The FHIR Message

The FHIR R5 representation consists of a Message bundle of resources, starting with the MessageHeader resource. The overall structure is depicted below.

FHIR message structure in terms of resource

The DiagnosticReport FHIR resource (the equivalent of ORC/OBR) references the ServiceRequest (with details such as the Lab test being ordered, the order filler number and the ordering person) and has a 0..* relationship with the Observation resource (the equivalent of OBX). The Patient, Practitioners and organizations are represented as individual resources, representing the 'leaf-nodes' in the overall model.

2.2.1 The FHIR Message - Bundle and MessageHeader

The FHIR representation of the use case is a Bundle of resources representing a message (Bundle.type=message) of type observation-provide (MessageHeader.event.code=onservation-provide, the equivalent of the R01 trigger event). In FHIR the addressing of the sender and/or receiver would be typically done using an IP address and a port number, the use of named addressing (e.g. GHH-LAB system) is however still supported.

 <Bundle xmlns="http://hl7.org/fhir">
  <id value="b5be9983-c913-4d54-b2bb-8e848056662a"/>
  <type value="message"/>
  <entry>
    <resource>
     <MessageHeader>
        <id value="CNTRL-3456"/> <!-- ControlID of the v2 message -->
        <meta> <tag>
            <system value="urn:oid:2.16.840.1.113883.5.100"/> <code value="P"/> <display value="Production"/>
        </tag> </meta>
        <eventCoding> <system value="http://hl7.org/fhir/message-type"/> <code value="observation-provide"/> </eventCoding>
        <destination> <endpointUrl value="urn:GHH-OE"/> <name value="GHH OE"/> </destination>
        <source> <endpointUrl value="urn:GHH-LAB"/> <name value="GHH LAB"/> </source>
        <focus> <reference value="DiagnosticReport/1045813"/> </focus>
      </MessageHeader>
    </resource>
  </entry>
 
  ... other bundle entries with resources (see below) ...

 </Bundle>

2.2.2 The FHIR Message - Observation resources

The DiagnosticReport resource and observation resources form the ehart of the report. In our example there's only one OBX/Observation, in practice a DiagnosticReport reports may include many Observations, as well as other clinical data (e.g. AllergyIntolerance, Condition, Procedure) used to reach a conclusion.

<entry>
    <resource>
          <Observation>
            <id value="2836644"/>
            <status value="final"/> 
            <code> <coding> <system value="http://loinc.org"/> <code value="1554-5"/>
                <display value="Glucose [Mass/volume] in Serum or Plasma --12 hours fasting"/> </coding> </code>
            <subject> <reference value="Patient/555-44-4444"/> <display value="Eve E. Everywoman"/> </subject>
            <issued value="2023-02-15T07:30:00-04:00"/>
            <performer> <reference value="Practitioner/444-44-4444"/> <display value="Harold H. Hippocrates"/> </performer>
            <valueQuantity> <value value="182"/> <unit value="mg/dL"/> 
               <system value="http://unitsofmeasure.org"/> <code value="mg/dL"/> 
            </valueQuantity>
            <interpretation> <coding> 
               <system value="http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation"/> <code value="N"/> 
            </coding> </interpretation>         
            <referenceRange>
              <low> <value value="70"/> <unit value="mg/dL"/> 
                 <system value="http://unitsofmeasure.org"/> <code value="mg/dL"/> 
              </low>
              <high> <value value="105"/> <unit value="mg/dL"/> 
                 <system value="http://unitsofmeasure.org"/> <code value="mg/dL"/> 
              </high>
            </referenceRange>
          </Observation>
    </resource>
</entry>

<entry>
    <resource>
     <DiagnosticReport>
        <id value="1045813"/> 
        <identifier> <system value="https://ghh.org/lab/reports"/> <value value="1045813"/> </identifier>
        <basedOn> <reference value="ServiceRequest/845439"/> </basedOn>
        <status value="final"/>
        <code> <coding>
            <system value="http://loinc.org"/> <code value="1554-5"/> 
            <display value="Glucose [Mass/volume] in Serum or Plasma --12 hours fasting"/>
        </coding> <text value="Glucose Post 12H"/> </code>
        <subject> <reference value="Patient/555-44-4444"/> <display value="Eve E. Everywoman"/> </subject>
        <effectiveDateTime value="2023-02-15T07:30:00-04:00"/>
        <issued value="2023-02-15T07:30:00-04:00"/>
        <performer> <reference value="Practitioner/444-44-4444"/> <display value="Harold H. Hippocrates"/> </performer>     
        <result> <reference value="Observation/2836644"/> </result>
      </DiagnosticReport>    
     </resource>
  </entry>

2.2.3 The FHIR Message - Reference to the order

The DiagnosticReport resource references the ServiceRequest resource, which contains the placer order number, the ordering party as well as the ordered service (LOINC 1554-5).

  <entry>
    <resource>
      <ServiceRequest>
        <id value="845439"/>
        <identifier> <system value="https://ghh.org/oe/placerorder"/> <value value="845439"/> </identifier>
        <status value="completed"/>
        <intent value="original-order"/>
        <code> <concept> <coding> <system value="http://loinc.org"/> <code value="1554-5"/> 
            <display value="Glucose [Mass/volume] in Serum or Plasma --12 hours fasting"/> 
        </coding> </concept> </code>
        <subject> <reference value="Patient/555-44-4444"/> <display value="Eve E. Everywoman"/> </subject>
        <requester> <reference value="Practitioner/555-55-5555"/> <display value="Patricia Primary MD"/> </requester>    
      </ServiceRequest>    
    </resource>
  </entry>

2.2.4 The FHIR Message - Patient

The patient resource contains the demographic details of the patient.

  <entry>
    <resource>
      <Patient>
        <id value="555-44-4444"/>
        <extension url="http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName">
          <valueString value="Jones"/> 
        </extension>
        <identifier> <use value="official"/> <system value="http://ghh.org/patient"/> <value value="555-44-4444"/> </identifier>
        <identifier> <use value="official"/> <system value="http://www.ohio.gov/dmv/driverslicence"/> <value value="67-A4335"/>
          <period> <end value="2003-05-20"/> </period>
        </identifier>
        <active value="true"/>
        <name> <use value="official"/> <family value="Everywoman"/> <given value="Eve E."/> </name>
        <telecom> <system value="phone"/> <value value="(206)3345232"/> <use value="home"/> </telecom>
        <telecom> <system value="phone"/> <value value="(206)752-121"/> <use value="work"/> </telecom>
        <gender value="female"/>
        <birthDate value="1962-03-20"/>
        <address> <line value="153 Fernwood Dr."/> <city value="Statesville"/> 
           <state value="OH"/> <postalCode value="35292"/> 
        </address>
        <managingOrganization> <reference value="Organization/GHH"/> <display value="Good Health Hospital"/> </managingOrganization>
      </Patient>
    </resource>
  </entry>

2.2.5 The FHIR Message - Other persons, organizations

These resources act as 'leaf nodes' (they are referenced, but don't reference any other resources): Organization resources that capture the details of the GHH hospital, the GHH-LAB department, and Practitioner resources to convey the details of Patricia Primary and Howard Hippocrates (both healthcare providers).

  <entry>
    <resource>
      <Organization> 
        <id value="GHH"/>
        <identifier> <use value="official"/> <system value="http://ghh.org/department"/> <value value="GHH"/> </identifier>
        <active value="true"/>  
        <type> <!-- GHH is a Hospital -->
          <coding> <system value="http://snomed.info/sct"/> <code value="22232009"/> <display value="Hospital"/> </coding>
        </type>
        <name value="Good Health Hospital"/>
      </Organization>
    </resource>
  </entry>

  <entry>
    <resource>
      <Organization>
        <id value="GHH-LAB"/>
        <identifier> <use value="official"/> <system value="http://ghh.org/department"/> <value value="GHH LAB"/> </identifier>
        <active value="true"/>
        <type> <!-- GHH Lab is a Laboratory within the GHH Hospital -->
          <coding> <system value="http://snomed.info/sct"/> <code value="73588009"/> 
          <display value="Hospital-based laboratory facility"/> </coding>
        </type>
        <name value="Laboratory of the Good Health Hospital"/>
      </Organization>
    </resource>
  </entry>

  <entry>
    <resource>
      <Practitioner>
        <id value="555-55-5555"/>
        <!-- 555-55-5555^PRIMARY^PATRICIA P^^^^MD^^ -->
        <identifier> <use value="official"/> <system value="http://ghh.org/practitioner"/> <value value="555-55-5555"/> </identifier>
        <name> <use value="official"/> <family value="Patricia"/> <given value="Primary"/> <suffix value="MD"/> </name>
      </Practitioner>
    </resource>
  </entry>

  <entry>
    <resource>
      <Practitioner>
        <id value="444-44-4444"/>
        <!-- 444-44-4444^HIPPOCRATES^HOWARD H^^^^MD -->
        <identifier> <use value="official"/> <system value="http://ghh.org/practitioner"/> <value value="444-44-4444"/> </identifier>
        <name> <use value="official"/> <family value="Hippocrates"/> <given value="Howard H"/> <suffix value="MD"/> </name>
       </Practitioner>
    </resource>
  </entry>

3 Summary

This whitepaper focuses on the relatively straightforward mapping of HL7v2 messages to FHIR messages. HL7 has created an excellent HL7 Version 2 to FHIR implementation guide with general mapping guidance. The mappings shown may have to be tweaked for a specific context, but they are an excellent starting point.

FHIR Servers are unlikely to support FHIR Messages, most of them implement the exchange of FHIR resources via a REST API. In that case, the main mapping challenge won't be the mapping of segments to resources, but bridging the fundamental differences between the messaging and REST exchange mechanisms.

About Ringholm bv

Ringholm bv is a group of European experts in the field of messaging standards and systems integration in healthcare IT. We provide the industry's most advanced training courses and consulting on healthcare information exchange standards.