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

There are 4 capabilities 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 4 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.
View	/Appointment/[id]	GET	This action, using the id from the List capability, will allow that specific Appointment Resource to be retrieved.
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 invariably be a POST operation however the method for booking will depend on the BaRS Application/use case.
Cancel	/Appointment[id]	PUT	The cancel of a booking will be setting the status of the appointment to "cancelled"
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 booking will constitute a rebook

The specification for these operations can be found here

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 definitiion.

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

Book

Book The method for the initial booking of an appointment depends on the Application specific guidance within BaRS. However a 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

Update

To update an appointment:

Perofrm a GET operation using the id of the appointment to /Appointment[id]
Ammend 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 an update 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": "urn:uuid: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": "urn:uuid: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": "urn:uuid:788660eb-d2c9-4773-abd4-318484673fb2"
			},
			"status": "accepted"
		}
	]
}

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": "urn:uuid: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": "urn:uuid: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": "urn:uuid: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": "urn:uuid: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": "urn:uuid: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": "urn:uuid:788660eb-d2c9-4773-abd4-318484673fb2"
			},
			"status": "accepted"
		}
	]
}

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.

Using PUT:

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]