Use case
This API is used to amend the Description or Comment, or Cancellation Reason where applicable, of a patient’s future appointment, obtained via use of either Retrieve a Patient’s Appointments, or Read an Appointment APIs. Any appointment, ie irrespective of booking organisation, can be amended by a consuming organisation participating with the appointment hosting organisation in a GP Connect deployment.
The typical flow to amend an appointment is:
- Search by
NHS Number
for, or otherwise obtain, aPatient
resource. - Search for
Appointment
resources for thePatient
resource. - Choose an
Appointment
resource and update itsdescription
and/orcomment
. If the appointment has been cancelled then thecancellation reason
may also be updated.
Security
- GP Connect utilises TLS Mutual Authentication for system level authorization
- GP Connect utilises a JSON Web Tokens (JWT) to transmit clinical audit and 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:
Header | Value |
---|---|
Ssp-TraceID |
Consumer’s TraceID (i.e. GUID/UUID) |
Ssp-From |
Consumer’s ASID |
Ssp-To |
Provider’s ASID |
Ssp-InteractionID |
urn:nhs:names:services:gpconnect:fhir:rest:update:appointment-1 |
If-Match |
The Appointment’s current ETag, e.g. W/"23" |
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 conforms to the GPConnect-Appointment-1 profile. -
SHALL include the URI of the
GPConnect-Appointment-1
profile StructureDefinition in theAppointment.meta.profile
element of the appointment resource.Important: It is recommended that Consumers read the Appointment they wish to amend (via Read an appointment or Retrieve a patient’s appointments), then update the fields allowed below in place. Attempting to recreate the Appointment resource from local transformed data formats/structures is not advised, and may result in the provider system rejecting the amendment due to an unintended change or missing field.
Only the following data-elements can be modified when performing an appointment amendment:
description
comment
-
Appointment cancellation reason
extension, which SHALL only be amended when the appointment status iscancelled
.Note: For providers who only support the mandatorydescription
element and not thecomment
element. If acomment
is received as part of the amendment the provider SHOULD append the content of the comment to the description within the appointment so that the additional information is not lost.
To reduce the risk of information being truncated when stored on the providers side, consumers SHALL impose:
- a 100 character limit on the appointment
description
element when editing a GP Connect appointment. - a 500 character limit on the appointment
comment
element when editing a GP Connect appointment.
On the wire a JSON serialised request would look something like the following:
{
"resourceType": "Appointment",
"id": "9",
"meta": {
"versionId": "636068818095315079",
"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"
]
},
"identifier": [
{
"system": "https://fhir.nhs.uk/Id/ods-organization-code",
"value": "A00001"
}
],
"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
comment
,description
orcancellation reason
are amended. The appointment resource should be considered invalid and the provider system should return a422
error with error codeINVALID_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).
- SHALL return an error if the version identifier in the
If-Match
header does not match the Appointment’s current version identifier. See Managing resource contention.
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 conforms to the GPConnect-Appointment-1 profile. - SHALL include the URI of the
GPConnect-Appointment-1
profile StructureDefinition in theAppointment.meta.profile
element of the returned appointment resource. -
SHALL include the
versionId
of the current version of the appointment resource. -
SHALL meet General FHIR resource population requirements populating all fields where data is available, excluding those listed below
- SHALL NOT populate the following fields:
reason
specialty
{
"resourceType": "Appointment",
"id": "9",
"meta": {
"versionId": "6360688180953112345",
"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"
]
},
"identifier": [
{
"system": "https://fhir.nhs.uk/Id/ods-organization-code",
"value": "A00001"
}
],
"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"
}
},
{
"url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-PractitionerRole-1",
"valueCodeableConcept": {
"coding": [
{
"system": "https://fhir.nhs.uk/STU3/CodeSystem/CareConnect-SDSJobRoleName-1",
"code": "R0260",
"display": "General Medical Practitioner"
}
]
}
},
{
"url": "https://fhir.nhs.uk/STU3/StructureDefinition/Extension-GPConnect-DeliveryChannel-2",
"valueCode": "In-person"
}
],
"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 Comment For The Appointment
appointment.comment = "Free text updated comment.";
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()));