NHS England FHIR Implementation Guide (deprecated)

The header for a FHIR Message exchange that is either requesting or responding to an action. The reference(s) that are the subject of the action as well as other information related to the action are typically transmitted in a bundle in which the MessageHeader resource instance is the first resource in the bundle.

Messaging middleware systems are expected to use this MessageHeader resource to route, deliver and handle messages correctly.

This profile is not tied to any specific transport/API requirement or clinical requirement. Intermediaries are not expected to perform detailed routing on clinical content. Some clinical information will be required for routing purposes and this will be held within eventCoding and reason sections as discussed in the Message Event section below. In circumstances where more detailed information is required for routing this MUST be carried in the relevant FHIR Resource in the payload only. For example, document types should be recorded in FHIR DocumentReference.type and health service/specialty type can be recorded in FHIR Encounter.serviceType or DocumentReference.context.practiceSetting.

Systems involved in NHSDigital/UKCore messaging are expected to support this profile only, extensions or derived profiles are permitted but they may only have limited (internal) scope and will not be supported outside of this scope (e.g. externally). This resource SHOULD NOT be profiled to further define the contents of the resources and FHIR MessageDefinition MUST be used instead.

identifiers and message timings

FHIR messages have two identifiers: the messageIdentifier of the Message (Bundle.identifier) and a messageId (Bundle.id) which is used in each transport channel . The messageId should be unique within a each message channel/stream. Whenever a message is resent, the messageIdentifier of the Bundle remains the same, but the messageId may change. The response message has its own unique messageIdentifier, the messageIdentifier of the request message can be referenced in the MessageHeader.response.identifier element.

The Bundle.identifier, the messageIdentifier, MUST have a UUID value.

Systems may chose to map X-Request-ID header to the Bundle.id, messageId. If both are supplied to a $process-messge endpoint it is recommended they hold the same values.

MessageHeader can hold previous and extra messageId's in the {{link:https://fhir.nhs.uk/StructureDefinition/Extension-MessageHeader-messageId}}

Local Part/Addressing (sender and/or destination.receiver)

When exchanging messages between organisations, local references SHOULD NOT be used for sender and destination.receiver references. Local references can make use of the Extension {{link:https://fhir.nhs.uk/StructureDefinition/Extension-MessageHeader-LocalPart}}. Messages between Organisations should be directed to the Organisation. The receiving organisation will take responsibility for delivering to the local address. Sending organisations are not expected to be able to deliver to local entities in another organisation/domain/facility.

This concept is similar to email addresses local-part@domain and also HL7 version 2 combination of Sending/Receiving Application | Sennding/Receiving Facility in the MSH segment.

In the example below, the destination is a clinic (A99968) which part of NHS Trust (RBA). Note also the destination endpoint is for the NHS Trust, who will route the message as required.

"destination": [
    {
        "endpoint": "urn:nhs-uk:addressing:ods:RBA",
        "receiver": {
          "extension": [
              {
                  "url": "https://fhir.nhs.uk/StructureDefinition/Extension-MessageHeader-LocalPart",
                  "valueReference": {
                        "identifier": {
                        "system": "https://fhir.nhs.uk/Id/ods-organization-code",
                        "value": "A99968"
                    }
                }

              }
          ],
            "identifier": {
                "system": "https://fhir.nhs.uk/Id/ods-organization-code",
                "value": "RBA"
            },
            "display": "TAUNTON AND SOMERSET NHS FOUNDATION TRUST"
        }
    }
],

example - Prescription, Pharmacy known

{{render:nominatedPharmacy}}

In the example below, the prescriber Taunton and Somerset Foundation Trust (RBA), is sending a message to The Simple Pharmacy (VNE51). The destination.receiver and sender are references to these organisations.

This message is to be sent via the Electronic Prescription Service, the http address of EPS is held in destination.endpoint. Replies to this message can only be received by MESH and the source.endpoint is the MESH address of the sending organisation.

"destination": [
    {
        "endpoint": "https://sandbox.api.service.nhs.uk/electronic-prescriptions/$post-message",
        "receiver": {
            "identifier": {
                "system": "https://fhir.nhs.uk/Id/ods-organization-code",
                "value": "VNE51"
            },
            "display": "The Simple Pharmacy"
        }
    }
],
"sender": {
    "identifier": {
        "extension": [
            {
                "url": "https://fhir.nhs.uk/StructureDefinition/Extension-MessageHeader-LocalPart",
                "valueReference": {
                        "identifier": {
                        "system": "https://fhir.nhs.uk/Id/ods-organization-code",
                        "value": "A99968"
                    }
                }
            }
        ],
        "system": "https://fhir.nhs.uk/Id/ods-organization-code",
        "value": "RBA"
    },
    "display": "TAUNTON AND SOMERSET NHS FOUNDATION TRUST"
},
"source": {
    "endpoint": "urn:nhs-uk:addressing:ods:RBA"
}

EPS will now send this message to the pharmacy. This message is collected by the pharmacy using MESH and so the destination.endpoint is now the MESH address of the pharmacy. Replies to this message are sent to EPS and so the source.endpoint is now the http address of the EPS $process-message endpoint.

"destination": [
    {
        "endpoint": "urn:nhs-uk:addressing:ods:VNE51",
        "receiver": {
            "identifier": {
                "system": "https://fhir.nhs.uk/Id/ods-organization-code",
                "value": "VNE51"
            },
            "display": "The Simple Pharmacy"
        }
    }
],
"sender": {
    "extension": [
            {
                "url": "https://fhir.nhs.uk/StructureDefinition/Extension-MessageHeader-LocalPart",
                "valueReference": {
                        "identifier": {
                        "system": "https://fhir.nhs.uk/Id/ods-organization-code",
                        "value": "A99968"
                    }
                }

            }
        ],
    "identifier": {
        "system": "https://fhir.nhs.uk/Id/ods-organization-code",
        "value": "RBA"
    },
    "display": "TAUNTON AND SOMERSET NHS FOUNDATION TRUST"
},
"source": {
    "endpoint": "https://sandbox.api.service.nhs.uk/electronic-prescriptions/$post-message"
}

example - Prescription, Pharmacy not known

{{render:noNominatedPharmacy}}

In this example the destination is not known and the message is sent to NHS Digital (X26).

"destination": [
    {
        "endpoint": "https://sandbox.api.service.nhs.uk/electronic-prescriptions/$post-message",
        "receiver": {
    
{{render:messageIDs}}



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.

```json
{
    "resourceType": "Bundle",
    "id": "884cfa4f-7a56-4be5-9592-783ef4f3992a",
    "meta": {
        "lastUpdated": "2020-11-02T01:43:30+00:00"
      },
    "identifier": {
        "system": "https://tools.ietf.org/html/rfc4122",
        "value": "ad945a29-85f8-439a-b590-6789719adc16"
    },
    "type": "message",
    "timestamp": "2020-11-02T01:43:30+00:00",
    "entry": [
        {
            "fullUrl": "urn:uuid:311316d3-1de0-4f7c-8109-c950ead1c717",
            "resource": {
                "resourceType": "MessageHeader",
                "extension": [
                    {
                        "url": "https://fhir.nhs.uk/StructureDefinition/Extension-Spine-MessageHeader-messageId",
                        "valueIdentifier": {
                            "system": "https://fhir.nhs.uk/Id/prescription-order-number",
                            "value": "DC2C66-A1B2C3-23407B"
                        }
                    }
                ]

From (source and sender) and To (destination)

The From is contained in both the sender and source elements and the To is contained in the destination array. One source, sender and at least one destination MUST be present.

Messages may be sent over multiple transmission legs (i.e. the first leg uses http and the second MESH). The contents of elements SHOULD reflect the current leg only.

• destination.endpoint
• source.endpoint
• MessageHeader.extension(messageId)

Endpoints MUST point to valid endpoint uri's on each leg of the messages journey, they may not refer to inaccessible endpoints on other legs. See also the destination section below.