Standard Pattern - Composite Messages

Most implementations of the BaRS that are applying the standard to support a particular use case or operational workflow will follow the same basic set of foundational operations with little deviation.

In order to establish a guarantee of compatibility between different solutions compliant with the standard, all implementations must support all the underlying foundational operations and patterns.

Standard Pattern For Composites

The majority of BaRS operations utilise a single standard approach. Since most BaRS operations involve composites of FHIR resources supporting a particular workflow they all utilise a single type of endpoint designed for processing and consuming of composite resources. This is the $process-message endpoint from the FHIR operations framework. The resource being transmitted in the body of the http request is a FHIR "Bundle" resource. This request payload needs to support two purposes, both the transmission of information as well as an indicator to direct the recieving system to how this particular bundle of resources is to be processed and what workflow should be triggered as a result of its consumption.

These core functions are:

• making a referral
• cancelling/amending a referral
• making a booking
• cancelling/amending a booking
• providing a response/feedback communication

At the highest level this pattern follows the following key steps:

• Sender GET the message definition for the payload/workflow being attempted
• Sender composes the bundle (as defined by the message definition) ready for POST-ing.
• Sender does a POST request to the receivers' /$process-message endpoint.
• Receiver inspects the request header and the bundle MessageHeader resource for the core workflow variables indicating how to process and consume the bundle.
• Receiver send http response message back to the sender.

Below is a pseudo code example, showing the above process in detail, illustrating how a message could be interpreted using core workflow variables for a message sent to POST /$process-message.

Each Application will have a tailored example of the below pseudo code.

Receive_Request
{
	initialise_variable "messageType" 
	initialise_variable "MessageReason" 
	initialise_variable "RequestType"
	
	//HTTP_Headers
	{
		if (HttpHeaders is null || HttpHeaders not Guid )
			OperationOutcome.issue.code = "invalid"
			throw exception with "REC_BAD_REQUEST"
			then return with HTTP.ResponseCode 400
		else if (HttpHeaders.RequestId == RequestId.AlreadyReceived)
			OperationOutcome.issue.code = "duplicate"
			throw exception with "REC_CONFLICT"
			then return with HTTP.ResponseCode 409
	}
	//Bundle
	{
		if(Bundle.meta.versionID is null)
			OperationOutcome.issue.code = "invariant"
			throw exception with "REC_BAD_REQUEST"
			then return with HTTP.ResponseCode 400
		else if!(Bundle.meta.versionID in versionID.supported)
			OperationOutcome.issue.code = "not-supported"
			throw exception with "REC_UNPROCESSABLE_ENTITY"
			then return with HTTP.ResponseCode 422
	}
	//Contents;
	{
		switch(MessageHeader.eventCoding)
		{
			case "servicerequest-request":
				if (MessageHeader.reason.code == "new" && ServiceRequest.status == "active")
					{
						switch(ServiceRequest.Category)
						{
							case "Validation":
								if (CarePlan.status != "active")
									{							
										RequestType = "unknown";
										OperationOutcome.issue.code = "invariant";//A content validation rule failed
										throw exception with "REC_BAD_REQUEST";
										then return  HTTP.ResponseCode 400;
									}
								else if(Encounter.Status.In("triaged","in-progress")
									{RequestType = "Im Receiving a new Validation Request";}
								else
									{
										RequestType = "unknown";
										OperationOutcome.issue.code = "invariant";//A content validation rule failed
										throw exception with "REC_BAD_REQUEST";
										then return  HTTP.ResponseCode 400;
									}
								break;
							case "Referral":
								if (Careplan.status != "completed")
								{
									RequestType = "unknown"
									OperationOutcome.issue.code = "invariant"//A content validation rule failed
									throw exception with "REC_BAD_REQUEST"
									then return  HTTP.ResponseCode 400
								}
								else if(Encounter.Status.In("triaged","finished"))
									RequestType = "Im Receiving a new Referral"
								else
									RequestType = "unknown"
									OperationOutcome.issue.code = "invariant"//A content validation rule failed
									throw exception with "REC_BAD_REQUEST"
									then return  HTTP.ResponseCode 400
								break;
							default:
								RequestType = "unknown"
								OperationOutcome.issue.code = "invariant"//A content validation rule failed
								throw exception with "REC_BAD_REQUEST"
								then return  HTTP.ResponseCode 400;
						}
					}
				else if (MessageHeader.reason.code == "update")
					{
						switch(ServiceRequest.category)
						{
							case "Validation":
								if(ServiceRequest.status.In("entered-in-error","revoked"))
									{RequestType = "im receiving a cancelled validation request";}
								else if(ServiceRequest.status.In("active","on-hold"))
									{RequestType = "im receiving an update to a validation request";} 
								else
								{
									RequestType = "unknown"
									OperationOutcome.issue.code = "invariant"//A content validation rule failed
									throw exception with "REC_BAD_REQUEST"
									then return  HTTP.ResponseCode 400								
								}
								break;
							case "Referral":
								if(ServiceRequest.status.In("entered-in-error","revoked"))
								{RequestType = "im receiving a cancelled referral"}
								else
								{
									RequestType = "unknown"
									OperationOutcome.issue.code = "invariant"//A content validation rule failed
									throw exception with "REC_BAD_REQUEST"
									then return  HTTP.ResponseCode 400								
								}
								break;
							default:
								RequestType = "unknown"
								OperationOutcome.issue.code = "invariant"//A content validation rule failed
								throw exception with "REC_BAD_REQUEST"
								then return  HTTP.ResponseCode 400;
						}

					}
				else
				{
					RequestType = "unknown"
					OperationOutcome.issue.code = "invariant"//A content validation rule failed
					throw exception with "REC_BAD_REQUEST"
					then return  HTTP.ResponseCode 400}
				break;
			case "servicerequest-response":
				if (MessageHeader.Response is null )
				{
						RequestType = "Invalid servicerequest-response"
						OperationOutcome.issue.code = "invariant"//A content validation rule failed
						throw exception with "REC_BAD_REQUEST"
						then return  HTTP.ResponseCode 400;
				}
				else if ( !Message.Response.identifier.existsLocally())
				{
						RequestType = "none or invalid response ID"
						OperationOutcome.issue.code = "not-found"//A content validation rule failed
						throw exception with "REC_NOT_FOUND"
						then return  HTTP.ResponseCode 404;
				}
				switch (ServiceRequest.Category)
					{
						case "Referral":
							if (ServiceRequest.status == "revoked" && MessageHeader.reason.code == "new")
							{ RequestType = "im receiving a Safeguarding DNA response (noshow)" } 
							else
							{
								RequestType = "unknown"
								OperationOutcome.issue.code = "invariant"//A content validation rule failed
								throw exception with "REC_BAD_REQUEST"
								then return  HTTP.ResponseCode 400;
							}
							break;
						case "Validation":
							if(!AnyEncounter.Originates.Local && Encount.Count()<=3)
							{
								if (MessageHeader.Reason.code == "new" && ServiceRequest.status == "active" && MessageHeader.FocusEncounter.status=="in-progress")
								{Request Type = "im receiving a Validation Response interim update" }
								else if (MessageHeader.Reason.code.In ("new","update") && ServiceRequest.status == "completed" && MessageHeader.FocusEncounter.status.In("triaged","complete")
								{Request Type = "im receiving a final Validation Response" }
								else
								{
									RequestType = "unknown"
									OperationOutcome.issue.code = "invariant"//A content validation rule failed
									throw exception with "REC_BAD_REQUEST"
									then return  HTTP.ResponseCode 400;
								}
							}
							else if(MessageHeader.FocusEncounter.status = "triaged" && ServiceRequest.status == "revoked" && MessageHeader.Reason.code.In("new","update"))
							{ RequestType = "im receiving  a Rejected validation response" } // a new encounter here is an edge case.
							else
							{
								RequestType = "unknown"
								OperationOutcome.issue.code = "invariant"//A content validation rule failed
								throw exception with "REC_BAD_REQUEST"
								then return  HTTP.ResponseCode 400;
							}
						default:
							RequestType = "unknown"
							OperationOutcome.issue.code = "invariant"//A content validation rule failed
							throw exception with "REC_BAD_REQUEST"
							then return  HTTP.ResponseCode 400;
					}
			case "booking-request":
				if (MessageHeader.Reason.code== "new" && Appointment.Status == "booked")
					if(slot.IsFree())
					{RequestType = "Im Receiving a new booking.";}
					else
					{
						OperationOutcome.issue.code = "conflict"
						throw exception with "REC_CONFLICT"
						then return with HTTP.ResponseCode 409
					}
				else if (MessageHeader.Reason.code == "update")
					MessageHeaderIsUpdate = true;
					switch (Appointment.Status)
					{
						case "cancelled":
							RequestType = "Im Receiving a booking cancellation."
							break						
						case "entered-in-error":
							RequestType = "Im Receiving a booking cancellation."
							break
						case "booked":
							RequestType = "Im Receiving an update to a booking."
							break
						default:
							OperationOutcome.issue.code = "invariant"//A content validation rule failed
							throw exception with "REC_BAD_REQUEST"
							then return with HTTP.ResponseCode 400;
							break;
					}
				else
				{
					OperationOutcome.issue.code = "invariant"//A content validation rule failed
					throw exception with "REC_BAD_REQUEST"
					then return with HTTP.ResponseCode 400;
				}
				break;
			case "booking-response":
					OperationOutcome.issue.code = "invariant"//A content validation rule failed
					throw exception with 'REC_BAD_REQUEST'
					then return with HTTP.ResponseCode 400
					break;
			default:
				OperationOutcome.issue.code = "invariant"//A content validation rule failed
				throw exception with 'REC_BAD_REQUEST'
				then return with HTTP.ResponseCode 400
				break;
		}
		
	}
	//Submit
	{
		
		if (Message == "update")
		{
			if (currentLocalData.LastUpdated > originaRequest.ReceivedDate)
			{
				OperationOutcome.issue.code = "conflict"
				throw exception with 'REC_CONFLICT'
				then return with HTTP.ResponseCode 409
				break;
			}		
			foreach (Entry in Bundle)
			{
				if (currentLocalData.Item.exists)
				{
					if (currentLocalData.LastUpdated > originaRequest.Received)
					{
						OperationOutcome.issue.code = "conflict"
						throw exception with 'REC_CONFLICT'
						then return with HTTP.ResponseCode 409
						break;
					}
					if(Entry.LastUpdated > currentLocalData.Item.meta.LastUpdated && Entry.fullUrl = currentLocalData.Item.fullUrl)
						currentLocalData.Item = Entry.Item
						Entry.SubmitWith(currentLocalData.Item.meta.LastUpdated == Entry.LastUpdated )
					else
						ignore
				}
				else
					Entry.SubmitWith(currentLocalData.Item.meta.LastUpdated == Entry.LastUpdated )					
			}
			Submit(currentLocalData.Bundle.meta.LastUpdated = Bundle.Meta.LastUpdated)
			return HTTP.ResponseCode 200 'OK'
		}
		else
			{
				foreach(Entry in Bundle)
				{
					Entry.SubmitWith(currentLocalData.Item.meta.LastUpdated == Entry.LastUpdated )
					Submit(currentLocalData.Bundle.meta.LastUpdated = Bundle.Meta.LastUpdated)
					return HTTP.ResponseCode 200 'OK'
				}
			}
	}	
}	

Message Headers

MessageHeader Resource

BaRS payloads (FHIR message bundles) require a MessageHeader FHIR resource which provides key information to drive workflow and start interpreting the data contained within. This resource is central to making a request or asynchronous response and must be present in all payloads.

The MessageHeader resource contains the following element which must be used as outlined:

• MessageHeader.source - stipulates where the payload originated. The Sender must, under MessageHeader.source.endpoint, include a valid URI which could be used as a NHSD-Target-Identifier (their reference on the Endpoint Catalogue) for the Receiver to send an asynchronous response.
• MessageHeader.destination - designates who the payload is intended for, including reference to an Organisation resource and a valid URI (MessageHeader.destination.endpoint) which is the NHSD-Target-Identifier (their reference on the Endpoint Catalogue) the payload is being sent to.
• MessageHeader.eventCoding - determines the 'type' of payload, whether booking, referral, request or asynchronousus response. The value must be populated from this CodeSystem. In referrals, this value, combined with the ServiceRequest.category element, allows supports for different styles of referral to support various use-cases. The value must be populated from CodeSystems for specific type and use-case.
• MessageHeader.reason.code - indicates whether the message is 'new' or an 'update' to something the Receiver is already aware of. The value must be populated from this CodeSystem.
• MessageHeader.focus - specifies the root resource through which to start interpreting the payload.
• MessageHeader.definition - cites the MessageDefinition the payload must adhere to and must be rejected by the Receiver if it fails to do so. Note: payload conformance to MessageDefinitions is not checked as part of FHIR validation.

When a Receiver begins to process the payload, they must initially ensure it is for them and they know who it is from:

• check the MessageHeader.destination and verify the MessageHeader.destination.receiver.reference refers to their Organisation.
• check the MessageHeader.destination.endpoint is the Service ID they are expected to be processing the request on behalf of.
• Store MessageHeader.source.endpoint as NHSD-Target-Identifier to enable an asynchronous response back to the Sender. Not all workflows will require this type of response but this data must be stored for audit purposes.

Certain elements in MessageHeader explicitly drive workflow, check MessageHeader.eventCoding to determine whether a booking or referral payload is being sent, and whether this is an initial or update request or an asynchronous response to a pre-existing request. There are various styles of referral too, a request could be made for a simple 'transfer of care' or, currently, something termed a 'validation', where one service requests another to validate the assessment outcome they have reached. The intention of supporting gradation of referral is to provide BaRS the malleability to support further subtlety of referrals for future use cases. Combining the MessageHeader.eventCoding with the ServiceRequest.cateory provides this functionality and, with the addition of use-case categories (again populated under ServiceRequest.category) specific services are pinpointed through every BaRS workflow.

Once the above checks have been made, the detail of the payload can start to be unpacked and processed. The structure of the payload must be checked first to ensure it adheres to the MessageHeader.definition it claims to. The MessageDefinitions will principally be defined by BaRS, at a national level (although bespoke definitions can be used through BaRS), and the Receiver is checking to ensure all mandatory FHIR resources are present and meet their assigned cardinality. This is a manual, business logic, check and not something which is supported through standard FHIR validation of the payload (bundle). Next, MessageHeader.focus is the root resource through which the payload is intended to be understood. In an initial referral request, this will typically be the ServiceRequest FHIR resource. This root will link to other resources to build a narrative for the payload, for example, the ServiceRequest will link to the Encounter which led to the referral being made and the Careplan detailing next actions. The Entity Relationship Diagrams (included in each Application) are used as a visual representation of the FHIR resource links in the payloads.

Asynchronous Response Workflows

For certain Applications, an initial request by a Sender expects an asynchronous response (as opposed to an HTTP synchronous response (200) message). These responses are defined by the workflow of the Application and may be consistently returned or conditional. When an asynchronous response is initiated, the original Sender and Receiver roles are switched, the Sender becoming the Receiver and vice versa. This allows BaRS to support complex workflows through support for multiple requests (initial and update) and, potentially, multiple asynchronous responses, for example, an initial status update followed by a more detailed final outcome (as defined in Application 4). The asynchronous response should be thought of as merely another payload, adhering to all the same rules as an initial request or update. Similarly, Sender and Receiver roles are intended to be interchangeable in BaRS and, in most BaRS Applications a supplier is expected to build both Sender and Receiver functionality, something which is reflected in the assurance process, especially BaRS Core.

Where the workflow dictates an asynchronous response is to be sent, the Sender (originally the Receiver) must populate:

• MessageHeader.response.identifier with the Bundle.Id of the original request payload and set the MessageHeader.response.code value to 'ok'.
• Additionally, they must follow the above guidance on populating the MessageHeader.

Cancellation

The ability to reverse a digital request, by performing a cancellation, whether booking or referral, is a core workflow within BaRS. It completes the digital workflow, supports genuine interoperability and removes the need for manual intervention by service providers.

Cancellation, for any referral type or booking, is a stripped back request, containing only the specific resources a Receiver requires to the fulfil the request. There are separate MessageDefinitions involved when engaged in referral and booking cancellation workflows.

A prerequisite when performing a cancellation of any request is to perform a read (GET) of either the booking or referral to be cancelled. The Sender must only make a cancellation request if the entity has a status which means it is still current; 'active' in the case of a referral (ServiceRequest) and 'booked' for a booking (Appointment). This ensures the Sender has the latest version of the entity they are about to change or, if it is no longer current (because its been actioned by the Receiver), allows the Sender to advise the end user so an alternative (often manual) workflow can be started. The Receiver must not process a cancellation request for a booking or referral which is not current, instead they must return an appropriate error response.

Cancellation Referral Request Payload

MessageHeader Resource

Standard Patterns for BaRS Operations explains in detail how the MessageHeader resource must be used.

When cancelling a referral, in conjunction with the guidance provided under the Standard Patterns, the four important elements which drive workflow must be used as follows:

• eventCoding - this must be the same code as used in the request.
• reasonCode - a cancellation follows an initial request, therefore, this must always be 'update' for cancellation.
• definition - cancellation has a unique MessageDefinition the request must adhere to.
• focus - must point to the ServiceRequest resource.

ServiceRequest Resource

The 'focus' resource in a cancellation referral request is the ServiceRequest resource. When the payload is created by the Sender and processed by the Receiver, this is the starting point from which it (the bundle) is understood and provides either the detail or references to all key FHIR resources, for example, the Patient. The guidance for this resource below provides more granular, element level, detail.

When a Receiver processes the cancellation referral request, the two key elements used are the ServiceRequest.id and ServiceRequest.status. The .id must already exist as an 'active' (status) ServiceRequest on the Receiver system (this must have been confirmed by a prior read (GET) by the Sender) and the .status, in the request, must either be 'revoked' or 'entered-in-error'. There is a distinct difference between these two ServiceRequest.status(es). 'Revoked' should be used to denote the original request was intentional but, due to a change in circumstances, is no longer valid, whereas, 'entered-in-error' should be used when original request was in error. The purpose of this differentiation is to allow service providers to accurately report the reason for cancellations.

Patient Resource

Key patient demographics should be cross-referenced between the current 'active' referral and incoming cancellation referral request to ensure validity.

Payload for Referral Cancellation Request

This payload is used to transmit all the necessary information that is required to transmit the cancellation of a Referral.

Bundle.type

message

Bundle.timestamp

MessageHeader.event[x].system

MessageHeader.event[x].code

MessageHeader.destination

MessageHeader.destination.receiver.reference

MessageHeader.sender.reference

MessageHeader.sender.identifier.assigner.reference

MessageHeader.source.extension

MessageHeader.source.extension:myExtension

MessageHeader.source.endpoint

MessageHeader.reason

MessageHeader.reason.coding.system

https://fhir.nhs.uk/CodeSystem/message-reason-bars

MessageHeader.focus.reference

ServiceRequest.intent

plan

ServiceRequest.category

ServiceRequest.subject

ServiceRequest.occurrence[x]

ServiceRequest.authoredOn

ServiceRequest.performer

Entity Relationship Diagram - Cancellation Referral Request

Cancellation Booking Request Payload

MessageHeader Resource

Standard Patterns for BaRS Operations explains in detail how the MessageHeader resource must be used.

When cancelling a booking, in conjunction with the guidance provided under the Standard Patterns, the three important elements which drive workflow must be used as follows:

• eventCoding - this must be the same code as used in the request.
• reasonCode - a cancellation follows an initial request, therefore, this must always be 'update' for cancellation.
• definition - cancellation has a unique MessageDefinition the request must adhere to.
• focus - must point to the Appointment resource.

Appointment Resource

The 'focus' resource in a cancellation booking request is the Appointment resource. When the payload is created by the Sender and processed by the Receiver, this is the starting point from which it (the bundle) is understood and provides either the detail or references to all key FHIR resources, for example, the Patient. The guidance for this resource below provides more granular, element level, detail.

When a Receiver processes the cancellation booking request, the two key elements used are the Appointment.id and Appointment.status. The .id must already exist as a 'booked' (status) booking on the Receiver system (this must have been confirmed by a prior read (GET) by the Sender) and the .status, in the request, must be 'cancelled'. No other status is valid in the cancellation booking request.

Patient Resource

Key patient demographics should be cross-referenced between the current 'booked' (status) booking and incoming cancellation booking request to ensure validity.

Payload for Booking Cancellation Request

This payload is used to transmit all the necessary information that is required to transmit the cancellation of a Booking.

Bundle.type

message

Bundle.timestamp

MessageHeader.event[x].system

MessageHeader.event[x].code

MessageHeader.destination

MessageHeader.destination.receiver.reference

MessageHeader.sender.reference

MessageHeader.sender.identifier.assigner.reference

MessageHeader.source.extension

MessageHeader.source.extension:myExtension

MessageHeader.source.endpoint

MessageHeader.reason

MessageHeader.reason.coding.system

https://fhir.nhs.uk/CodeSystem/message-reason-bars

MessageHeader.focus.reference

Entity Relationship Diagram - Cancellation Booking Request

Use Case Categories

What are use case categories?

Use case categories define the specific type of referral being requested. The type is categorised at the service level. A BaRS Application can support multiple use cases; a use case can only ever belong to one BaRS Application. For instance, in Application 6 there are three defined use cases: Out of Area, Mutual Aid and Call Assist. All of these use cases relate to referrals between Ambulance Service Trusts but the workflow, timeframes and responses are not universal across all three scenarios.

The BaRS use case categories are defined in the BARS CodeSystem (https://simplifier.net/nhsbookingandreferrals/usecases-categories-bars). All BaRS compliant solutions must adopt use case categories.

How to use BaRS use case categories

The use case category is used in the initial content negotiation phase:

• when a Sender makes a request for MessageDefinitions and the Receiver responds
• when the Sender makes a referral request to the Receiver

When a Sender makes a request for MessageDefinitions, the MessageDefinitions returned by the Receiver will contain a use case category code (from the use case categories code system) under Message.Definition.useContext.code. The Sender must read this field to verify the Receiver supports the use case workflow they require. The use case category code will also be included in:

• the Sender's service request under ServiceRequest.category
• the Sender’s booking request under Appointment.ServiceCategory

If this is not a use case supported by the Receiver, they will respond with an error (Operation Outcome).

The sequence of events occurs as follows:

• the Sender requests the MessageDefinitions
• the Receiver indicates the use-case categories they support
• the Sender reads and only engages in the use-case workflows supported
• the Sender's request includes the use-case category code (the same code they read from the MessageDefinition), under ServiceRequest.category (referral) or Appointment.ServiceCategory (booking)
• the Receiver processes accordingly