FHIR ADT^A01, MessageDefinition and GraphDefinition

In my previous posts I looked at building a FHIR Encounter to use in messaging. (Operational FHIR Encounter example and Operational FHIR Encounter plus Patient and ITK HL7v2)

This was based on both the ITK HL7v2 ADT^A01 message and used Digital Child Events as FHIR Examples. Most of the core content has been done but we are missing the FHIR MessageHeader, the message should be defined by a FHIR MessageDefinition it’s not mandatory and DCH Events don’t use one but it’s use in testing/validation will be apparent later on.

The message definition allows us to define the characteristics, such as the event type and content. As we are looking ADT-A01 messages, I’m going to use that as the event type. I’m also going to use Admit/Visit Notification as the name which is the same as v2. This gives

"resourceType": "MessageDefinition",
"url": "https://fhir.leedsth.nhs.uk/MessageDefinition/EncounterNotification-1",
"version": "1.0.0",
"name": "Admit/Visit Notification",
"title": "Example FHIR MessageDefinition for ADT^A01 Admit/Visit Notification",
"status": "draft",
"date": "2019-04-29T00:00:00+00:00",
"copyright": "Copyright © 2019 Aire Logic",
"event": {
  "system": "https://fhir.leedsth.nhs.uk/CodeSystem/HL7v2-MessageEvent-1",
  "code": "ADT-A01",
  "display": "Admit/Visit Notification"
"category": "Notification",
"focus": [
    "code": "Encounter",
    "profile": {
      "reference": "https://fhir.hl7.org.uk/STU3/StructureDefinition/CareConnect-Encounter-1"
    "min": 1,
    "max": 1


You might notice I’ve not included Patient in the definition, this is because the Patient is implied in the Encounter resource and the focus of this message is Encounter notifications. I’ve chosen not to follow conventions in ITK messaging and used the actual uri’s for the endpoints (source and destination), this is more useful in our local system to aid fault finding, support, etc. For responsible I’ve also use identifier references. These both keep messaging out of the payload and avoids clutter.

<id value="5899ec4f-ce2f-49dd-b44c-39819b593888"/>
    <system value="https://fhir.leedsth.nhs.uk/CodeSystem/HL7v2-MessageEvent-1"/>
    <code value="ADT-A01"/>
    <display value="Admit/Visit Notification"/>
    <name value="Trust Integration Engine"/>
    <endpoint value="http://tie.leedsth.nhs.uk/STU3/Bundle"/>
<timestamp value="2019-04-30T09:16:00+00:00"/>
    <name value="PatientCentre PAS"/>
    <endpoint value="http://pas.leedsth.nhs.uk:1234"/>
        <system value="https://fhir.nhs.uk/Id/ods-organization-code"/>
        <value value="RR8"/>
    <reference value="urn:uuid: TODO add in reference to Encounter"/>

This is pretty straightforward, so lets move onto the full message Bundle. The full example can be found on GitHub here

Some points to note:

  • The focused resource (Encounter) is referenced from the MessageHeader, this in turn references Patient and Location.
  • No external references are used and we’ve made a lot of use to national code systems using identifier references.
  • The message is generic and can be used across many systems (but see issues below)


  • Use of a DCH ValueSet+CodeSystem for TREATMENT_FUNCTION_CODE is not ideal and should be a more generic ValueSet+CodeSystem
  • CareConnect-Encounter-1 only allows one type, for practical reasons we need to use TFC and modeler’s want us to move to SNOMED
  • This message could go external to the trust using RESTful interactions, however if it goes via MESH it needs to be transformed
  • If this patient matches DCH requirements (so a child), the message again needs to be transformed to DCH standards (and which DCH profile depends on the payload)
  • It is missing clinical content which the ADT^A01 could carry (see next section)

Clinical Content

Clinical content such as Observations, Conditions and Medications can be added to the above Bundle. What we are missing is a way of doing this, the MessageDefinition only states a focus Encounter and we added Patient and Location.

We can do this via GraphDefinition, if you search for ADT on the CCRI (GraphDefinitions on CCRI) you will find a number of examples of GraphDef’s for ADT^A28. GraphDefinition is a very useful way to add additional rules to both profiles and MessageDefinitions. For the A28 examples you will see it adds in constraints on Patient, it’s left Practitioner (GP) and Organization (surgery) optional in the Bundle but you could make it mandatory.

One issue though, you can’t link GraphDefinition to MessageDefinition using the standard STU3 profiles. You can on R4 of FHIR, however the MessageDefinitions on the CCRI has them linked, how?

The CCRI is using R4 backports which allow STU3 FHIR to use R4 features (have a look at the raw FHIR resources to see how it’s done).

The use of MessageDefinition and GraphDefinition to document and add rules to messaging is useful to reference but the core FHIR team intend to use these in validation of FHIR Messages. (Note: this will probably use R5 FHIR validation, not R4 and STU3 but their are ways of using R5 to validate STU3 resources… maybe more on this later?)

1 Like