Introduction

FHIR supports multiple exchange paradigms, which are all equally valid: REST, Documents, Messages and Services. FHIR messaging is very similar to HL7 v2 and supports the use of FHIR resources in a traditional messaging context. In this module you will learn more about:

• The structure of a FHIR message
• The impact of a FHIR message
• Message exchange patterns
• How to use the MessageDefinition resource

Reading material

1. FHIR messaging framework

The FHIR messaging framework supports the use of FHIR resources in a traditional messaging context, which may facilitate the transformation from traditional standards to FHIR. FHIR servers may choose to support FHIR messaging, REST or a combination of both. For example, you may allow clients to send FHIR messages and store resources individually in a RESTful way or store the entire message. The difference between these approaches is the granularity and the choice depends on how you want to use the data at a later stage. For analytics, you will need to be able to access individual resources, while for exchange of messages this is not absolutely necessary.

1.1 What is a FHIR message?

A FHIR message is a set or a Bundle of resources passed between a source and a destination application, expecting some kind of action from the destination application. Two main types of messages exist: request messages and response messages. A request message is sent from a source application to a destination application whenever an event takes place such as the booking of an appointment or requesting an overview of all lab values. The destination application takes care of the request and replies with a response message.

1.2 Message structure

A FHIR message is a Bundle of type message. The first entry of the Bundle is always a MessageHeader resource. The MessageHeader specifies the message event (e.g. booking an appointment or linking two patients) in its code element. The MessageHeader may contain additional request metadata, such as the endpoint of the source application or the entity responsible for triggering the event (e.g. the practitioner booking the appointment).

The focus element of the MessageHeader specifies the content of the message. The MessageHeader is followed by other resources depending on the type of request. For example, a request to book an appointment may contain the Patient to book the appointment for, the Practitioner to book the appointment with and the actual Appointment that is requested.

1.3 Message identification

FHIR messages have two identifiers: the technical id of the Bundle and the technical id of the MessageHeader. The technical id of the MessageHeader should be unique for each new message that is sent within a message stream. Whenever a message is resent, the technical id of the MessageHeader remains the same, but the technical id of the Bundle changes. The response message has its own unique MessageHeader id, but the MessageHeader id of the request message is provided in the MessageHeader.response.identifier element.

In addition, a FHIR Message Bundle has two important timestamps:

• The time of sending the message is captured in the timestamp element
• The last time the message was updated (e.g. by storing or modification) is captured in the meta.lastUpdated element

2. Message resources

2.1 MessageDefinition

The MessageDefinition resource can be used to capture the definition of a message describing characteristics like:

• the title of the message
• the type of event that initiates the message
• the message significance category
• the content of the message (e.g. at least one Patient resource)
• whether a response is required
• which response messages are allowed

Below is a simple example of a MessageDefinition for booking an appointment. Note that the content is not specified, but would normally include at least an Appointment resource and maybe one or more participants (e.g. Patients and/or Practitioners).

<MessageDefinition xmlns="http://hl7.org/fhir">
  <id value="bkapp"/> 
  <url value="http://hl7.org/fhir/MessageDefinition/bkapp"/> 
  <name value="BKAPP"/> 
  <title value="Book appointment"/> 
  <status value="draft"/> 
  <eventCoding> 
    <system value="http://example.org/fhir/message-events"/> 
    <code value="book-appointment"/> 
  </eventCoding> 
  <category value="consequence"/> 
  <responseRequired value="always"/>
</MessageDefinition> 

2.2 MessageHeader

The MessageHeader is the first resource in the FHIR Message Bundle. This mandatory resource specifies the event that is triggered. For this reason, the cardinality of the event element of this resource is 1..1 In addition, it is mandatory to provide the endpoint of the source application sending the message. The MessageHeader may contain additional information, such as:

• information about the destination application
• the cause of the event
• the party responsible for the event
• the party sending or entering the information
• the actual content of the message
• a link to the definition of the message (MessageDefinition)

Below is a simple example of a MessageHeader for booking an appointment.

<MessageHeader xmlns="http://hl7.org/fhir">
  <id value="1cbdfb97-5859-48a4-8301-d54eab818d68"/> 
  <eventCoding> 
    <system value="http://example.org/fhir/message-events"/> 
    <code value="book-appointment"/> 
  </eventCoding> 
  <sender> 
    <reference value="Practitioner/1"/> 
  </sender> 
  <source> 
    <endpoint value="http://example.org/clients/ehr"/> 
  </source> 
  <focus> 
    <reference value="Patient/2"/> 
    <reference value="Practitioner/1"/> 
    <reference value="Appointment/1"/> 
  </focus> 
  <definition value="MessageDefinition/bkapp"/> 
</MessageHeader>

2.3 Other resources

Other resources used in the Document Framework are:

• Bundle; as explained earlier Bundles of type message contain the actual FHIR Message
• Any resource can be used in the content of the message

3. Message processing

3.1 Message significance category

The nature of a message has impact on the way it should be processed. There are three message categories that determine how the message can be processed and whether one or more receivers are allowed.

3.2 Exchange patterns

A server may choose between the following exchange patterns:

• Synchronous (wait for a response before sending a next message)
• Asynchronous (do not wait for a response before sending a next message)

Although synchronous messages is most common and easiest to understand, asynchronous messaging may be more practical e.g. when working with high volumes. The downside of asynchronous messaging is however that it is harder to implement and more can go wrong when messages are not processed correctly.

3.3 RESTful operations

The FHIR messaging framework offers functionality that is very similar to that of the RESTful API. For example, it is possible to invoke RESTFUL operations (e.g. a search) by using FHIR messages. Note however that these operations (which are part of the REST API) require special definitions in the messaging framework (which are not provided). On the other hand, FHIR messages can implemented a series of RESTful (as well as other) operations, so the server will do all the work when processing a single message.

Real-life examples

NHS Digital

NHS Digital is the national body of England responsible for information, data and IT systems in health and social care. An example of a use case that uses the FHIR Messaging Framework is the Female Genital Mutilation (FGM) Risk Indication System (RIS). The FGM RIS has been developed as part of the FGM Prevention Programme and is part of the national Spine architecture. The FGM RIS supports storing and sharing FGM risk information across relevant NHS healthcare professionals.

The following link provides an example of one of the profiles that is used in this context, a common profile on MessageHeader for request messages: https://fhir.nhs.uk/StructureDefinition/spine-request-messageheader-2-0

For other examples of use cases in which NHS Digital uses messaging, you may visit their API Hub: https://developer.nhs.uk/apis/ There's also a link from here to the FGM API.

Exercise

In this exercise you will create some profiles and FHIR Messages. Start by reading the case description. Here below are a couple of links that you may find useful during this exercise:

• Download Forge
• FHIR Resourcelist: http://hl7.org/fhir/resourcelist.html
• FHIR Messaging Framework: https://www.hl7.org/fhir/messaging.html

Case description
Hospital X wants to use messages to exchange information between systems. Your first assignment is to support the event of discharging a patient from the hospital. When a practitioner discharges a patient, the information needs to be updated in all the connected clinical systems. The hospital needs the following information: update of the admission status, the discharge destination, discharge date and the practitioner responsible for discharging the patient. The hospital already has profiles in place for the required clinical resources (e.g. patient), but not for messages.

Steps to follow

1. Identify the business concepts that are relevant in this use case, which profiles will you need to send in your message?
2. Open Forge (or any other tool) and create a new profile to capture the definition of your request message.
   1. Specify name, title, coding and category of the message.
   2. Specify which resources should be in the content of the message.
   3. A response is required, the following responses are allowed: either a successfull response or a message that the system failed to complete the request.
3. Create the required profile(s) to capture the definition of your response message(s).
   1. Again, specify name, title, coding and category.
   2. Specify which resources should be in the content of the message.
   3. Is a response required for this message? Define this in your profile.
4. Create an example of a FHIR Message Bundle for a discharge request.
5. Create (an) example(s) of FHIR Message Bundle(s) for the response message(s).

Feedback

We are always looking for ways to improve our products. The Profiling Academy was built using our own IG-editor in Simplifier. If you have any feedback on this module or on our Profiling Academy in general, please leave a comment in the Issue Tracker of the project.

Get in touch

Start profiling

Most modules end with an exercise. Use Forge to start profiling yourself. Just contact us at simplifier@fire.ly if you need any help.

Learn more

Follow one of our predefined or tailor-made courses. We will make sure you know FHIR inside-out.

Need help or advice?

Let us assist you with your FHIR use case. Visit our company website to know more about our services or get into contact with Rien Wertheim right away.