NHS Digital FHIR Implementation Guide

This guidance is under active development by NHS Digital and content may be added or updated on a regular basis.

Exchange

FHIR has three main types of interactions.

  • RESTful API A (FHIR) resource exchange framework. A set of core search parameters can be found on the resource profile pages (see Resource Index below)
  • FHIR Messaging A messaging exchange framework. The FHIR equivalent of HL7v2 or traditional messaging
  • FHIR Documents A document based exchange framework. The FHIR equivalent of HL7v3 CDA (clinical document architecture)

Which interaction should be used and general interaction guidance can be found in Integration Patterns Book

FHIR Messaging

This is the FHIR version of traditional messaging. It differs from FHIR RESTful in that all the resources are sent to the recipient in one interaction. This is particularly useful between organisations where all the FHIR resources can be sent in one interaction.

The general FHIR principle that resources MUST be self contained still applies. FHIR Messaging should not be used to send highly coupled complex interactions, the message SHOULD be easily converted into resource based interactions. A FHIR Message bundle is not a storage based concept, it should be expected that all the resources in the Bundle can be processed individually. Should this be required consider using FHIR Documents

FHIR Messaging should only be used for defined interactions/messages, ad-hoc interactions/collections should use transactions

E.g. in the diagram below a prescription consists of one Patient resource and two MedicationRequests. Using FHIR Messaging all the resources are sent within one FHIR Message Bundle. Doing the same with FHIR RESTful would require at least three transactions (possibly more depending on the handling of the Patient resource).

FHIR Message reduces the number of transactions and decouples the sending organisation from local rules. All the resources are handled in a single package and the receiving organisation can handle them according to local procedures.

FHIR Messaging is very similar to the messaging used in HL7 v2 and HL7 v3 (/ITK), hence the term traditional messaging.

FHIR Bundle (type=message)

Profile url
https://fhir.nhs.uk/StructureDefinition/NHSDigital-Bundle-FHIRMessage

useΣ ?!0..1codeBinding
typeΣ0..1CodeableConceptBinding
systemS Σ1..1uri
valueS Σ1..1string
periodΣ I0..1Period
assignerΣ I0..1Reference(Organization)
typeS Σ1..1codeBindingFixed Value
timestampS Σ1..1instant
totalΣ I0..1unsignedInt
fullUrlΣ1..1uri
resourceΣ0..1Resource
modeΣ0..1codeBinding
scoreΣ0..1decimal
methodΣ1..1codeBinding
urlΣ1..1uri
ifNoneMatchΣ0..1string
ifModifiedSinceΣ0..1instant
ifMatchΣ0..1string
ifNoneExistΣ0..1string
statusΣ1..1string
locationΣ0..1uri
etagΣ0..1string
lastModifiedΣ0..1instant
outcomeΣ0..1Resource
fullUrlΣ0..1uri
resourceS Σ I0..1NHSDigitalMessageHeader
signatureΣ0..1Signature

This message consists of a Bundle identified by the type "message", with the first resource in the bundle being a MessageHeader resource. The MessageHeader resource has a code - the message event - that identifies the nature of the request message, and it also carries additional request metadata. The other resources in the bundle depend on the type of the request.

For example a dispense-notification message will be a FHIR Bundle consisting of

  • one MessageHeader resource with an eventCoding dispense-notification
  • one to four MedicationDispense resources
  • one (optional) Patient resource.

Example dispense-notifications can be found in the NHS Digital Medicines Guide Examples

These Bundles are send to a $process-message operation, e.g.

POST baseUrl/$process-message

In the example above we stated rules for the dispense-notification message, these will be contained in a FHIR MessageDefinition and the message definition for this is https://fhir.nhs.uk/MessageDefinition/dispense-notification

{
    "resourceType": "MessageDefinition",
    "id": "bf729ea8-280b-4109-b2f5-02ce8e51d870",
    "url": "https://fhir.nhs.uk/MessageDefinition/dispense-notification",
    "identifier":  [
        {
            "system": "https://tools.ietf.org/html/rfc4122",
            "value": "bf729ea8-280b-4109-b2f5-02ce8e51d870"
        }
    ],
    "version": "1.0.0",
    "name": "NHSDigitalDispenseNotification",
    "title": "Pharmacy/Treatment Dispense",
    "status": "active",
    "date": "2020-10-02",
    "eventCoding": {
        "system": "https://fhir.nhs.uk/CodeSystem/message-event",
        "code": "dispense-notification",
        "display": "Dispense Notification"
    },
    "description": "Notification of dispensed medication",
    "category": "notification",
    "focus":  [
        {
            "code": "MedicationDispense",
            "profile": "https://fhir.nhs.uk/StructureDefinition/NHSDigital-MedicationDispense-Message",
            "min": 1,
            "max": "*"
        }
    ]
}

Some of the key points are:

  • element eventCoding This is the code that identifies the MessageDefinition and will match the eventingCode in the dispense-notification FHIR Message
  • element focus This lists the principal resources; in the example this is FHIR MedicationDispense resources which follows the NHSDigital-MedicationDispense profile. One and up to four resources can be supplied.
  • Patient resource is not in the focus section. The rule that a Patient resource is required is contained in the FHIR MedicationDispense profile.
  • MessageHeader resource is not in the focus section. It is mandatory in all FHIR Messages.

The FHIR MessageHeader contains the message metadata only and is designed to support message handling without having to process the full message. The use of FHIR MessageHeader with NHSDigital API's is discussed in NHSDigital-MessageHeader. Note this FHIR R4 NHSDigital-MessageHeader is designed to handle all message types and contains rules from both previous MessageHeaders used in Transfer of Care (point to point messages) and National Event Messaging System (pub/sub messages).

FHIR Documents

This is the FHIR method of exchanging clinical documents. where content to be exchanged is wrapped by a Composition that provides the context of the content, and that has a fixed presentation for a human reader. The document framework is provided to help with computer-assisted human to human communication uses - which are not uncommon in healthcare.

Typically, exchanging documents is associated with exchanging clinical information across NHS organisation and care setting boundaries (e.g., Transfer of Care), while data-based exchange using the RESTful API is appropriate within where there are well established clinical governance arrangements.

The FHIR document is a FHIR Bundle with the type of document

Profile url
https://fhir.nhs.uk/StructureDefinition/NHSDigital-Bundle-FHIRDocument

identifierΣ0..1Identifier
typeΣ1..1codeBindingFixed Value
timestampΣ0..1instant
totalΣ I0..1unsignedInt
fullUrlΣ1..1uri
resourceΣ0..1Resource
modeΣ0..1codeBinding
scoreΣ0..1decimal
methodΣ1..1codeBinding
urlΣ1..1uri
ifNoneMatchΣ0..1string
ifModifiedSinceΣ0..1instant
ifMatchΣ0..1string
ifNoneExistΣ0..1string
statusΣ1..1string
locationΣ0..1uri
etagΣ0..1string
lastModifiedΣ0..1instant
outcomeΣ0..1Resource
fullUrlΣ0..1uri
resourceΣ I0..1NHSDigitalComposition
modeΣ0..1codeBinding
scoreΣ0..1decimal
methodΣ1..1codeBinding
urlΣ1..1uri
ifNoneMatchΣ0..1string
ifModifiedSinceΣ0..1instant
ifMatchΣ0..1string
ifNoneExistΣ0..1string
statusΣ1..1string
locationΣ0..1uri
etagΣ0..1string
lastModifiedΣ0..1instant
outcomeΣ0..1Resource
fullUrlΣ0..1uri
resourceΣ I0..1NHSDigitalPatient
signatureΣ0..1Signature

The FHIR Documents are exchanged using FHIR Messaging (which is also a FHIR Bundle of type of message), as shown in the diagram below:

The NHSDigital-Composition is subdivided into sections which are equivalent to PRSB headings.

back to top