From 8535a9e39a7d9c036950f6ccd7c77b6a7e2d08b8 Mon Sep 17 00:00:00 2001 From: naveed rafeeq Date: Wed, 16 Sep 2026 12:56:46 +0000 Subject: [PATCH 1/2] [RAA-9685]-[RK]-[OAS Document SPC/SPCA support for A015 Retrieve Appointment Slots]-[NR] --- CHANGELOG.md | 9 +++++--- .../a015-retrieve-appointment-slots.yaml | 21 +++++++++++++++++++ .../ErrorOutcome.yaml | 2 +- 3 files changed, 28 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f1dfeaff2..41bc49b6e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,7 @@ # Changelog - -## {{ ansible_date_time.date }} -* Initial commit +## 15/09/2026 +* A015 (Retrieve Appointment Slots): documented support for `SERVICE_PROVIDER_CLINICIAN` and `SERVICE_PROVIDER_CLINICIAN_ADMIN` roles. +* A015 - Enhanced ErrorOutcome.yaml with comprehensive error code documentation for retrieveAppointmentSlots + - Documented error conditions for referral state validation (NOT_BOOKED, TRIAGE service checks) + - Added response headers: X-Correlation-ID, X-Request-ID, Content-Type + - Configured FHIR JSON error response schema with STU3-OperationOutcome reference diff --git a/specification/components/stu3/schemas/endpoints/a015-retrieve-appointment-slots.yaml b/specification/components/stu3/schemas/endpoints/a015-retrieve-appointment-slots.yaml index 8703217b2..59b9d9642 100644 --- a/specification/components/stu3/schemas/endpoints/a015-retrieve-appointment-slots.yaml +++ b/specification/components/stu3/schemas/endpoints/a015-retrieve-appointment-slots.yaml @@ -4,6 +4,12 @@ description: | ## Overview Use this endpoint to retrieve available appointment slots for a service. + Service provider clinicians can also use this endpoint, but only to retrieve slots for the purpose of redirecting a referral to another directly bookable service. This is only permitted when all of the following conditions are met: + - the referral's current holding service is of type `TRIAGE` + - the referral is in the `NOT_BOOKED` state + - the requested service is of type `APPOINTMENT` + - the user has a Legitimate Relationship with the referral + ## Supported security patterns - Healthcare worker, user-restricted access @@ -11,9 +17,15 @@ description: | In order to use this endpoint you must be an authenticated e-RS user and use one of the following e-RS roles: - `REFERRING_CLINICIAN` - `REFERRING_CLINICIAN_ADMIN` + - `SERVICE_PROVIDER_CLINICIAN` + - `SERVICE_PROVIDER_CLINICIAN_ADMIN` + + If using the `SERVICE_PROVIDER_CLINICIAN` or `SERVICE_PROVIDER_CLINICIAN_ADMIN` role, this endpoint is only usable under the narrow conditions described in the Overview above (referral redirection from a `TRIAGE` holding service, referral in `NOT_BOOKED` state, requested service of type `APPOINTMENT`, and an existing Legitimate Relationship with the referral). Outside of these conditions, calls from these roles will be rejected. You need to have identified a directly bookable `service` that is on the current referral shortlist. You can do this by using [[HYPERLINK_A005]]. + The `NHSD-eRS-Business-Function` header must be set to a role that is permitted to call this endpoint - `REFERRING_CLINICIAN`, `REFERRING_CLINICIAN_ADMIN`, `SERVICE_PROVIDER_CLINICIAN`, or `SERVICE_PROVIDER_CLINICIAN_ADMIN` are all now accepted, subject to the conditions above for the service provider roles. + ## Use case As an authenticated user @@ -22,6 +34,12 @@ description: | So that I can offer them to the patient for booking. + As a service provider clinician (`SERVICE_PROVIDER_CLINICIAN`/`SERVICE_PROVIDER_CLINICIAN_ADMIN`) + + I need to retrieve a list of available appointment slots for a service while a referral is held in `TRIAGE` and not yet booked + + So that I can redirect the referral to a suitable directly bookable service and book an appointment via [[HYPERLINK_A016]]. + ## Important note You need to provide the 'commissioning rule organisation' when calling [[HYPERLINK_A015]] to ensure only suitable slots are returned. You can obtain the 'commissioning rule organisation' from [[HYPERLINK_A005]]. @@ -38,6 +56,8 @@ description: | - when trying to book an appointment into a service, the slot advertised is no longer available - when trying to book an appointment into a service, no response is received within message timeout period (currently 2 minutes) + Service provider clinicians (`SERVICE_PROVIDER_CLINICIAN`/`SERVICE_PROVIDER_CLINICIAN_ADMIN`) use [[HYPERLINK_A015]] as part of the referral redirection workflow: retrieving slots for a suitable service before booking the redirected referral using [[HYPERLINK_A016]]. + ## Known Issues This endpoint is using the :Practitioner search parameter. The "schedule.actor" search parameter is incorrectly using the ":Practitioner" modifier. As per the [FHIR standard](https://hl7.org/fhir/R4/) the ":identifier" modifier should be used when searching to indicate that an Identifer is used rather than a literal, relative, internal or absolute reference. See our [problems and fixes](https://digital.nhs.uk/services/e-referral-service/api/updates-and-releases/problems-and-fixes) section for more information. @@ -65,6 +85,7 @@ parameters: - $ref: '../headers/request/BusinessFunction.yaml' - $ref: '../headers/request/CorrelationID.yaml' - $ref: '../headers/request/ErsCommRuleOrg.yaml' + - $ref: '../headers/request/OnBehalfOfUserID.yaml' - $ref: '../queryParameters/ServiceId.yaml' - $ref: '../queryParameters/Priority.yaml' - $ref: '../queryParameters/Status.yaml' diff --git a/specification/components/stu3/schemas/responses/retrieveAppointmentSlots/ErrorOutcome.yaml b/specification/components/stu3/schemas/responses/retrieveAppointmentSlots/ErrorOutcome.yaml index 03b3bbff6..77a8ab800 100644 --- a/specification/components/stu3/schemas/responses/retrieveAppointmentSlots/ErrorOutcome.yaml +++ b/specification/components/stu3/schemas/responses/retrieveAppointmentSlots/ErrorOutcome.yaml @@ -9,7 +9,7 @@ description: | | INVALID_CODE | The input provided for a field is not one of the defined legal values. | | MISSING_PARAMETER | Indicates missing mandatory FHIR search parameter. | | MISSING_HEADER | Indicates missing mandatory HTTP header. | - | INVALID_STATE | Indicates that the referenced item is not in the correct state for the request to be processed. | + | INVALID_STATE | Indicates that the referenced item is not in the correct state for the request to be processed. This applies when:
- the referral is not in the `NOT_BOOKED` state;
- (`SERVICE_PROVIDER_CLINICIAN`/`SERVICE_PROVIDER_CLINICIAN_ADMIN` only) the referral's current holding service is not of type `TRIAGE`. | | SERVICE_UNAVAILABLE | Indicates that a service is no longer available. | headers: X-Correlation-ID: From b3f532db0695b17f4d751f12c39048aff3719891 Mon Sep 17 00:00:00 2001 From: naveed rafeeq Date: Thu, 17 Sep 2026 15:22:52 +0000 Subject: [PATCH 2/2] [RAA-9685]-[RK]-[Added Sandox functionality to test endpoint directly]-[NR] --- sandbox/src/routes/stu3/retrieveAppointmentSlots.js | 2 +- tests/sandbox/stu3/test_a015_get_appointment_slots.py | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/sandbox/src/routes/stu3/retrieveAppointmentSlots.js b/sandbox/src/routes/stu3/retrieveAppointmentSlots.js index 84e98f886..67d48ed9f 100644 --- a/sandbox/src/routes/stu3/retrieveAppointmentSlots.js +++ b/sandbox/src/routes/stu3/retrieveAppointmentSlots.js @@ -10,7 +10,7 @@ module.exports = [ path: '/FHIR/STU3/Slot', handler: (request, h) => { - const allowedBusinessFunctions = ["REFERRING_CLINICIAN", "REFERRING_CLINICIAN_ADMIN"] + const allowedBusinessFunctions = ["REFERRING_CLINICIAN", "REFERRING_CLINICIAN_ADMIN", "SERVICE_PROVIDER_CLINICIAN", "SERVICE_PROVIDER_CLINICIAN_ADMIN"] const validationResult = validationUtils.validateBusinessFunction(request, h, allowedBusinessFunctions) if (validationResult) { diff --git a/tests/sandbox/stu3/test_a015_get_appointment_slots.py b/tests/sandbox/stu3/test_a015_get_appointment_slots.py index c2c11a266..a7e1ca690 100644 --- a/tests/sandbox/stu3/test_a015_get_appointment_slots.py +++ b/tests/sandbox/stu3/test_a015_get_appointment_slots.py @@ -14,6 +14,8 @@ class TestGetAdviceAndGuidanceConversation(SandboxTest): allowed_business_function_data = [ "REFERRING_CLINICIAN", "REFERRING_CLINICIAN_ADMIN", + "SERVICE_PROVIDER_CLINICIAN", + "SERVICE_PROVIDER_CLINICIAN_ADMIN", ] authorised_actor_data = Actor.all(