From d1b3398a7abd66f23e94cb35989ec6732b8f3aa4 Mon Sep 17 00:00:00 2001 From: "naveed.rafeeq" Date: Thu, 27 Aug 2026 10:03:57 +0100 Subject: [PATCH 1/3] RAA-9623 OAS Document SPC/SPCA support for A016 Book or Defer Appointment --- CHANGELOG.md | 2 ++ .../endpoints/a016-book-or-defer-appointment.yaml | 9 ++++++++- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f1dfeaff2..690bb5d72 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,6 @@ # Changelog +2026-08-27 +A016 (Book or Defer Appointment): documented support for `SERVICE_PROVIDER_CLINICIAN` and `SERVICE_PROVIDER_CLINICIAN_ADMIN` roles, including the "Triaged - Provider To Action" state precondition for these roles (RAA-9623) ## {{ ansible_date_time.date }} * Initial commit diff --git a/specification/components/stu3/schemas/endpoints/a016-book-or-defer-appointment.yaml b/specification/components/stu3/schemas/endpoints/a016-book-or-defer-appointment.yaml index 98856c076..571dc8009 100644 --- a/specification/components/stu3/schemas/endpoints/a016-book-or-defer-appointment.yaml +++ b/specification/components/stu3/schemas/endpoints/a016-book-or-defer-appointment.yaml @@ -13,12 +13,18 @@ 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` You need to check if the service is directly bookable, indirectly bookable, or triage by either using [[HYPERLINK_A033]] or [[HYPERLINK_A035]]. You can then offer appropriate actions to authenticated users, i.e. the ability to book an appointment into a directly bookable service if an appointment slot is available, defer the booking responsibility to a directly bookable service if no appointment slot is available, refer a patient into a triage service. If the service is directly bookable, you need to retrieve available appointment slots for the service using [[HYPERLINK_A015]]. - You need to use the Unique Booking Reference Number (UBRN) of a referral request in order to use this endpoint. + You need to use the Unique Booking Reference Number (UBRN) of a referral request in order to use this endpoint. + + If `businessFunction` is `SERVICE_PROVIDER_CLINICIAN` or `SERVICE_PROVIDER_CLINICIAN_ADMIN`, the referral must be in the "Triaged - Provider To Action" state (i.e. it has been redirected to your organisation and is awaiting booking, deferral, or triage). Calling this endpoint as a Service Provider Clinician when the referral is not in this state will return a `422` error with error code `INVALID_REQUEST_STATE`. + + Where a `SERVICE_PROVIDER_CLINICIAN_ADMIN` (SPCA) is acting on behalf of a `SERVICE_PROVIDER_CLINICIAN` (SPC), the on behalf of user ID must be that of an appropriate SPC. You can use endpoint [[HYPERLINK_A040]] to determine which e-RS users a `SERVICE_PROVIDER_CLINICIAN_ADMIN` is allowed to work "on-behalf-of". ## Important note when deferring to provider @@ -64,6 +70,7 @@ parameters: - $ref: '../headers/request/OdsCode.yaml' - $ref: '../headers/request/BusinessFunction.yaml' - $ref: '../headers/request/CorrelationID.yaml' + - $ref: '../headers/request/OnBehalfOfUserID.yaml' requestBody: required: true content: From 06eeb008bc3936fb2d3afdb1b882d0badd224737 Mon Sep 17 00:00:00 2001 From: "naveed.rafeeq" Date: Thu, 27 Aug 2026 11:25:22 +0100 Subject: [PATCH 2/3] RAA-9623 OAS Document SPC/SPCA support for A016 Book or Defer Appointment --- .../stu3/schemas/endpoints/a016-book-or-defer-appointment.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/components/stu3/schemas/endpoints/a016-book-or-defer-appointment.yaml b/specification/components/stu3/schemas/endpoints/a016-book-or-defer-appointment.yaml index 571dc8009..ff3870af2 100644 --- a/specification/components/stu3/schemas/endpoints/a016-book-or-defer-appointment.yaml +++ b/specification/components/stu3/schemas/endpoints/a016-book-or-defer-appointment.yaml @@ -22,7 +22,7 @@ description: | You need to use the Unique Booking Reference Number (UBRN) of a referral request in order to use this endpoint. - If `businessFunction` is `SERVICE_PROVIDER_CLINICIAN` or `SERVICE_PROVIDER_CLINICIAN_ADMIN`, the referral must be in the "Triaged - Provider To Action" state (i.e. it has been redirected to your organisation and is awaiting booking, deferral, or triage). Calling this endpoint as a Service Provider Clinician when the referral is not in this state will return a `422` error with error code `INVALID_REQUEST_STATE`. + If `businessFunction` is `SERVICE_PROVIDER_CLINICIAN` or `SERVICE_PROVIDER_CLINICIAN_ADMIN`, the referral must be in the 'Not Booked' state (i.e. it has been redirected to a directly bookable or triage service and is awaiting a booking, deferral, or triage decision). Calling this endpoint as a Service Provider Clinician when the referral is not in this state will return a `422` error with error code `INVALID_REQUEST_STATE`. Where a `SERVICE_PROVIDER_CLINICIAN_ADMIN` (SPCA) is acting on behalf of a `SERVICE_PROVIDER_CLINICIAN` (SPC), the on behalf of user ID must be that of an appropriate SPC. You can use endpoint [[HYPERLINK_A040]] to determine which e-RS users a `SERVICE_PROVIDER_CLINICIAN_ADMIN` is allowed to work "on-behalf-of". From 165e4a1f4f12a44e957094e03a28e2d6bf372563 Mon Sep 17 00:00:00 2001 From: naveed rafeeq Date: Thu, 17 Sep 2026 16:02:33 +0000 Subject: [PATCH 3/3] [RAA-9623]-[RK]-[Added Sandox functionality to test endpoint directly]-[NR] --- sandbox/src/routes/stu3/bookOrDeferAppointment.js | 2 +- tests/sandbox/stu3/test_a016_book_or_defer_appointment.py | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/sandbox/src/routes/stu3/bookOrDeferAppointment.js b/sandbox/src/routes/stu3/bookOrDeferAppointment.js index 39c92ce9a..ec889e6af 100644 --- a/sandbox/src/routes/stu3/bookOrDeferAppointment.js +++ b/sandbox/src/routes/stu3/bookOrDeferAppointment.js @@ -10,7 +10,7 @@ module.exports = [ path: '/FHIR/STU3/Appointment', 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_a016_book_or_defer_appointment.py b/tests/sandbox/stu3/test_a016_book_or_defer_appointment.py index cbe61221a..43dd77eb0 100644 --- a/tests/sandbox/stu3/test_a016_book_or_defer_appointment.py +++ b/tests/sandbox/stu3/test_a016_book_or_defer_appointment.py @@ -14,6 +14,8 @@ class TestBookOrDeferAppointment(SandboxTest): allowed_business_function_data = [ "REFERRING_CLINICIAN", "REFERRING_CLINICIAN_ADMIN", + "SERVICE_PROVIDER_CLINICIAN", + "SERVICE_PROVIDER_CLINICIAN_ADMIN", ] authorised_actor_data = Actor.all(