Use Case

The typical flow to amend an appointment is:

1. Search by NHS Number for, or otherwise obtain, a Patient resource.
2. Search for Appointment resources for the Patient resource.
3. Choose an Appointment resource and update it’s description, comment or reason details.

Security

• GP Connect utilises TLS Mutual Authentication for system level authorization.
• GP Connect utilises a JSON Web Tokens (JWT) to transmit clinical audit & provenance details.

Prerequisites

Consumer

The Consumer system:

• SHALL have previously resolved the organisation’s FHIR endpoint Base URL through the Spine Directory Service
• SHALL have previously traced the patient’s NHS Number using the Personal Demographics Service or an equivalent service.
• SHALL have previously found the appointment id using Retrieve a patient’s appointments.

API Usage

The Consumer System SHALL only use the amend appointment capability to amend future appointments where appointment start dateTime is after the current date and time. If the appointment start date is in the past the provider SHALL return an error.

Request Operation

FHIR Relative Request

PUT /Appointment/[id]

FHIR Absolute Request

PUT https://[proxy_server]/https://[provider_server]/[fhir_base]/Appointment/[id]

Request Headers

Consumers SHALL include the following additional HTTP request headers:

Payload Request Body

The request payload is a profiled version of the standard FHIR Appointment resource, see FHIR Resources page for more detail.

Consumer systems:

• SHALL send an Appointment resource that conform to the GPConnect-Appointment-1 profile.
• SHALL include the URI of the GPConnect-Appointment-1 profile StructureDefinition in the Appointment.meta.profile element of the appointment resource.

Only the following data-elements can be modified when performing an appointment amendment:

• reason
• description
• comment
• Appointment cancellation reason extension, which SHALL only be amended when the appointment status is cancelled.

On the wire a JSON serialised request would look something like the following:

{
	"resourceType": "Appointment",
	"id": "9",
	"meta": {
		"versionId": "636068818095315079",
		"lastUpdated": "2016-08-15T19:16:49.971+01:00",
		"profile": ["https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-Appointment-1"]
	},
	"contained": [{
		"resourceType": "Organization",
		"id": "1",
		"meta": {
			"profile": ["https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Organization-1"]
		},
		"name": "Test Organization Name",
		"telecom": [{
			"system": "phone",
			"value": "0300 303 5678"
		}]
	}],
	"extension": [{
		"url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-BookingOrganisation-1",
		"valueReference": {
			"reference": "#1"
		}
	}],
	"status": "booked",
	"description": "Free text description updated.",
	"start": "2016-05-30T10:00:00+01:00",
	"end": "2016-05-30T10:25:00+01:00",
	"slot": [{
		"reference": "Slot/1",
		"display": "Slot 1"
	}],
	"created": "2017-10-09T13:48:41+01:00",
	"comment": "Free text comment.",
	"participant": [{
		"actor": {
			"reference": "Patient/1",
			"display": "Mr. Mike Smith"
		},
		"status": "accepted"
	},
	{
		"actor": {
			"reference": "Location/32",
			"display": "Leeds GP Clinic"
		},
		"status": "accepted"
	}]
}

Error Handling

The Provider system:

• SHALL return an GPConnect-OperationOutcome-1 resource that provides additional detail when one or more request fields are corrupt or a specific business rule/constraint is breached.
• SHALL return an error if any appointment details other than the appointment reason, comment, description or cancellation reason are amended, the passed in appointment resource should be considered invalid and the provider system should return a 422 error with error code INVALID_RESOURCE.
• SHALL return an error if the appointment being amended is in the past (the appointment start dateTime is before the current date and time).

Refer to Development - FHIR API Guidance - Error Handling for details of error codes.

Request Response

Response Headers

Provider systems are not expected to add any specific headers beyond that described in the HTTP and FHIR® standards.

Payload Response Body

Provider systems:

• SHALL return a 200 OK HTTP status code on successful execution of the operation.
• SHALL return an Appointment resource that conform to the GPConnect-Appointment-1 profile.
• SHALL include the URI of the GPConnect-Appointment-1 profile StructureDefinition in the Appointment.meta.profile element of the returned appointment resource.
• SHALL include the versionId of the current version of the appointment resource.
• SHALL have updated the appointment in accordance with the details supplied in the request. For example, the received reason element will replace the existing element. I.e. where the existing element contained only reason.text, and the received element contained only reason.coding, then the resultant reason element would contain only the reason.coding sub-element.

{
	"resourceType": "Appointment",
	"id": "9",
	"meta": {
		"versionId": "6360688180953112345",
		"lastUpdated": "2017-09-12T19:16:50.971+01:00",
		"profile": ["https://fhir.nhs.uk/STU3/StructureDefinition/GPConnect-Appointment-1"]
	},
	"contained": [{
		"resourceType": "Organization",
		"id": "1",
		"meta": {
			"profile": ["https://fhir.nhs.uk/STU3/StructureDefinition/CareConnect-GPC-Organization-1"]
		},
		"name": "Test Organization Name",
		"telecom": [{
			"system": "phone",
			"value": "0300 303 5678"
		}]
	}],
	"extension": [{
		"url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-BookingOrganisation-1",
		"valueReference": {
			"reference": "#1"
		}
	}],
	"status": "booked",
	"description": "Free text description updated.",
	"start": "2016-05-30T10:00:00+01:00",
	"end": "2016-05-30T10:25:00+01:00",
	"slot": [{
		"reference": "Slot/1",
		"display": "Slot 1"
	}],
	"created": "2017-10-09T13:48:41+01:00",
	"comment": "Free text comment.",
	"participant": [{
		"actor": {
			"reference": "Patient/1",
			"display": "Mr. Mike Smith"
		},
		"status": "accepted"
	},
	{
		"actor": {
			"reference": "Location/32",
			"display": "Leeds GP Clinic"
		},
		"status": "accepted"
	}]
}

Examples

C#

var client = new FhirClient("http://gpconnect.aprovider.nhs.net/GP001/STU3/1");
client.PreferredFormat = ResourceFormat.Json;
var appointment = client.Read<Appointment>("Appointment/9");
// Update The Reason For The Appointment
appointment.Reason.Text = "Free text updated reason.";
var updatedAppointment = client.Update<Appointment>(appointment);
FhirSerializer.SerializeResourceToJson(updatedAppointment).Dump();

Java

// Read appointment to be updated
FhirContext ctx = FhirContext.forStu3();
IGenericClient client = ctx.newRestfulGenericClient("http://gpconnect.aprovider.nhs.net/GP001/STU3/1");
Appointment appointment = client.read().resource(Appointment.class).withId("9").execute();

// Amend appointment comment
appointment.setComment("Java Example Comment");

// Update appointment
MethodOutcome response = client.update()
	.resource(appointment)
	.prefer(PreferReturnEnum.REPRESENTATION)
	.preferResponseType(Appointment.class)
	.execute();

System.out.println(fhirContext.newJsonParser().setPrettyPrint(true).encodeResourceToString(response.getResource()));