Standard Pattern - Appointments

Important: Release information

This Section of the Implementation Guide is currently a preview, in an Alpha state and subject to change.

Introduction

The BaRS API suite can be used where there is no specific use-case supported by the Applications to fulfil generic Appointment workflows, referred to as Appointment Management Foundation. This section outlines the functionality supported, workflows involved and how these correspond with the API Specification.

This includes using DocumentReference Standard Pattern to write pointers for Appointments to a central respository, commonly referred to as the Registry.

The Appointment Management Foundation is based on BaRS Core and an understanding of the central tenets is essential before beginning. This includes: -

End to end workflow - how Senders and Receivers, interacting through the central Proxy, negotiate compatibility and engage
Service Discovery - every workflow must include the resolution of a receiving Service Identifier
Authentication and Authorisation - the central Proxy will handle Authentication but Authorisation is handled by Receivers
Onboarding to environments - getting access to the central Proxy. This differs for Senders (OAuth) and Receivers (mTLS)

There are four functions that are required surrounding appointments. This section will provide information on how to meet them using the Appointment Resource.

The ability to book an appointment.
The ability to cancel an appointment.
The ability to update an appointment.
The ability to rebook an appointment.

Interface

The following table describes how the BaRS API accomodates these four capabilities using the /Appointment endpoint and the /Appointment/{id} endpoint

Capability	Endpoint	VERB	Description
List	/DocumentReference	GET	Using the DocumentReference pattern, a list of existing appointments for a patient can be viewed with the central Registry.
View	/Appointment/{id}	GET	This action, using the id from the List capability, will allow that specific Appointment Resource to be retrieved from the healthcare service who owns it.
Get Slots	/Slots	GET	Obtain a list of available booking slots from a specified receiving system using the GET /Slots endpoint
Book	/Appointment or /$process-message	POST	This will be a POST operation, with a BaRS Application /$process-message is typically used, outside of supported use cases /Appointment is adopted.
Cancel	/Appointment/{id}	PUT	The cancel of a booking will be setting the status of the appointment to "cancelled". Cancel is also possible using /$process-message
Update	/Appointment/{id}	PUT / PATCH	An update to an appointment will be a direct update to the existing resource
Rebook	Composite of Cancel and then Book	Composite	Requesting a new booking and then cancelling the existing one will constitute a rebook

In line with the BaRS standard all operations used to modify a resource must be preceded by a read of the resource by means of a GET operation.

Appointment Resource

Below are examples of each of the described interactions. The appointment resource adheres to the UKCore-Appointment definition.

Any operations that modify an existing resource must perform a read before a write. GET /Appointment/{id}

Book

The method for the initial booking of an appointment depends on the Application specific guidance within BaRS. Within BaRS Applications, making a booking will involve building a FHIR bundle and making a POST to the $process-message endpoint. Alternatively, booking an appointment can be used outside of use-cases supported by a BaRS Application, to fulfil a generic Appointment Management Foundation workflow against the discete booking endpoints, either way, the typical sequence of events is:

Select the service to book an appointment with.
Confirm BaRS Capabilities.
Request Available slots.
Select a slot.
Send a Request to book an appointment in that slot

Request Body

{
	"resourceType": "Appointment",
    "id":"aca94bdb-2e38-4399-9ece-2ba083ce65b5"
	"meta": {
		"lastUpdated": "2024-01-11T15:01:30.8185338+00:00",
		"profile": [
			"https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment"
		]
	},
	"status": "booked",
    "slot": [
        {
            "reference": "Slot/deb4c4b3-870b-4599-84df-5e54cef7afda"
        }
    ],
	"description": "Reason for calling",
	"start": "2024-02-12T12:30:30+00:00",
	"end": "2024-02-12T12:40:30+00:00",
	"created": "2024-10-08T15:01:30+00:00",
	"participant": [
		{
			"actor": {
				"reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2"
			},
			"status": "accepted"
		}
	]
}

Once the appointment is created, the Receiver is responsible for managing the pointer in the central Registry, as described here.

Update

To update an appointment:

Perform a GET operation using the id of the appointment to /Appointment/{id}
Amend or append the resource as required.
Perform a PUT operation using the id of the appointment to /Appointment/{id}

In this example a placeholder was created, and updated when the slot is selected. This is a hypothetical scenario.

resource returned:

{
	"resourceType": "Appointment",
    "id":"aca94bdb-2e38-4399-9ece-2ba083ce65b5"
	"meta": {
		"lastUpdated": "2024-01-11T15:01:30.8185338+00:00",
		"profile": [
			"https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment"
		]
	},
	"status": "waitlist",
	"description": "Reason for calling",
	"created": "2024-10-08T15:01:30+00:00",
	"participant": [
		{
			"actor": {
				"reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2"
			},
			"status": "accepted"
		}
	]
}

Request Body

{
	"resourceType": "Appointment",
    "id":"aca94bdb-2e38-4399-9ece-2ba083ce65b5"
	"meta": {
		"lastUpdated": "2024-01-11T15:01:30.8185338+00:00",
		"profile": [
			"https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment"
		]
	},
	"status": "booked",
    "slot": [
        {
            "reference": "Slot/deb4c4b3-870b-4599-84df-5e54cef7afda"
        }
    ],
	"description": "Reason for calling",
	"start": "2024-02-12T12:30:30+00:00",
	"end": "2024-02-12T12:40:30+00:00",
	"created": "2024-10-08T15:01:30+00:00",
	"participant": [
		{
			"actor": {
				"reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2"
			},
			"status": "accepted"
		}
	]
}

Once the appointment is updated, the Receiver is responsible for managing the pointer in the central Registry, as described here.

Cancel

To cancel an appointment:

Perform a GET operation using the id of the appointment to /Appointment/{id}
Set the Appointment.status value to "cancelled"
Perform a PUT operation using the id of the appointment to /Appointment/{id}

resource returned:

{
	"resourceType": "Appointment",
    "id":"aca94bdb-2e38-4399-9ece-2ba083ce65b5"
	"meta": {
		"lastUpdated": "2024-01-11T15:01:30.8185338+00:00",
		"profile": [
			"https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment"
		]
	},
	"status": "booked",
    "slot": [
        {
            "reference": "Slot/deb4c4b3-870b-4599-84df-5e54cef7afda"
        }
    ],
	"description": "Reason for calling",
	"start": "2024-02-12T12:30:30+00:00",
	"end": "2024-02-12T12:40:30+00:00",
	"created": "2024-10-08T15:01:30+00:00",
	"participant": [
		{
			"actor": {
				"reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2"
			},
			"status": "accepted"
		}
	]
}

Request body:

{
	"resourceType": "Appointment",
    "id":"aca94bdb-2e38-4399-9ece-2ba083ce65b5"
	"meta": {
		"lastUpdated": "2024-01-11T16:01:30.8185338+00:00",
		"profile": [
			"https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment"
		]
	},
	"status": "cancelled",
    "slot": [
        {
            "reference": "Slot/deb4c4b3-870b-4599-84df-5e54cef7afda"
        }
    ],
	"description": "Reason for calling",
	"start": "2024-02-12T12:30:30+00:00",
	"end": "2024-02-12T12:40:30+00:00",
	"created": "2024-10-08T15:01:30+00:00",
	"participant": [
		{
			"actor": {
				"reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2"
			},
			"status": "accepted"
		}
	]
}

OR if the appointment was entered in error

Request body:

{
	"resourceType": "Appointment",
    "id":"aca94bdb-2e38-4399-9ece-2ba083ce65b5"
	"meta": {
		"lastUpdated": "2024-01-11T16:01:30.8185338+00:00",
		"profile": [
			"https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment"
		]
	},
	"status": "entered-in-error",
    "slot": [
        {
            "reference": "Slot/deb4c4b3-870b-4599-84df-5e54cef7afda"
        }
    ],
	"description": "Reason for calling",
	"start": "2024-02-12T12:30:30+00:00",
	"end": "2024-02-12T12:40:30+00:00",
	"created": "2024-10-08T15:01:30+00:00",
	"participant": [
		{
			"actor": {
				"reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2"
			},
			"status": "accepted"
		}
	]
}

Once the appointment is cancelled, the Receiver is responsible for managing the pointer in the central Registry, as described here.

Rebook

Notes on Rebook from https://hl7.org/fhir/R4/appointment.html

Waitlisting the Appointment (optional)

This optional step permits creating a waitlisted appointment. This could occur if an appointment needs to be booked into a time that is not ideal for the patient due to lack of available time slots. In this workflow, there would be two appointments, the booked appointment in the time slot that is currently available, and the waitlisted appointment with a requestedPeriod spanning the time that the patient would prefer if new slots become available.

If new time slots become available during the requestedPeriod, the scheduling system, or staff at the scheduling organization, can notify the patient that a new time slot is available. If the patient chooses, the waitlisted appointment would then be booked into that specific slot, and the previously booked appointment would be cancelled. The specific business process for notifying patients of new availability is not specified, and is up to the implementing system to determine.

under section 12.10.4.5 Flow for a patient waitlist:

Activity Description	Appointment (inconvenient)	Appointment (preferred)
An appointment is booked for an inconvenient time using a typical status flow	status = bookedparticipant.status = accepted
Waitlist appointment created	status = bookedparticipant.status = accepted	status = waitlistrequestedPeriod = (more convenient time period)
Patient notified of availability of a better slot	status = booked	status = proposedparticipant.status = needs-action
Patient accepts better slot	status = cancelled	status = bookedparticipant.status = accepted

The FHIR guidance indicates that the Appointment that is no longer needed should be updated with a PUT status=cancelled

A new Appointment can then be created as needed using the same existing workflow, whether this is using the Slot/Schedule or a POST Appointment resource. Use the cancel method described above.

Process for rebook

The method for the subsequent booking of an appointment depends on the Application specific guidance within BaRS. The only difference would be the Appointment Resource would include Appointment.replaces referencing the previous appointment for provenance. Alternatively, rebooking an appointment can be used outside of use-cases supported by a BaRS Application, to fulfil a generic Appointment workflow, either way, the typical sequence of events using PUT or POST is:

Select the service to book an appointment with.
Confirm BaRS Capabilities.
Request Available slots.
Select a slot.
Perform a GET operation using the id of the appointment to /Appointment/{id}
Set the Appointment.status value to "cancelled"
Perform a PUT operation using the id of the appointment to /Appointment/{id}

Request Body

{
	"resourceType": "Appointment",
    "id":"1ed510f2-df15-45b7-8852-8adfb0fcf4f3"
	"meta": {
		"lastUpdated": "2024-01-11T15:01:30.8185338+00:00",
		"profile": [
			"https://fhir.hl7.org.uk/StructureDefinition/UKCore-Appointment"
		]
	},
	"status": "booked",
    "slot": [
        {
            "reference": "Slot/deb4c4b3-870b-4599-84df-5e54cef7afda"
        }
    ],
	"description": "Reason for calling",
	"start": "2024-02-12T12:30:30+00:00",
	"end": "2024-02-12T12:40:30+00:00",
	"created": "2024-10-08T15:01:30+00:00",
	"participant": [
		{
			"actor": {
				"reference": "Patient/788660eb-d2c9-4773-abd4-318484673fb2"
			},
			"status": "accepted"
		}
	],
    "replaces": [
		{
			"reference": "Appointment/aca94bdb-2e38-4399-9ece-2ba083ce65b5"
		}		
	]
}

Using PATCH:

Select the service to book an appointment with.
Confirm BaRS Capabilities.
Request Available slots.
Select a slot.
Perform a GET operation using the id of the appointment to /Appointment/{id}
Set the Appointment.status value to "cancelled"
Perform a PATCH operation using the id of the appointment to /Appointment/{id}

{
	"resourceType": "Appointment",
    "id":"1ed510f2-df15-45b7-8852-8adfb0fcf4f3",
	"status": "booked",
    "slot": [
        {
            "reference": "Slot/deb4c4b3-870b-4599-84df-5e54cef7afda"
        }
    ],
	"description": "Reason for calling",
	"start": "2024-02-12T12:30:30+00:00",
	"end": "2024-02-12T12:40:30+00:00",
	"created": "2024-10-08T15:01:30+00:00",
}

Once the appointment is rebooked, the Receiver is responsible for managing the pointer in the central Registry, as described here.

NHS Booking and Referral Standard

Standard Pattern - Appointments

Introduction

Interface

Appointment Resource

Book

Update

Cancel

Rebook

Waitlisting the Appointment (optional)

Process for rebook