From b8d1418c858a5b8bda646f50d6ec263b73cbccce Mon Sep 17 00:00:00 2001 From: Carl De'ath <74620667+cda69@users.noreply.github.com> Date: Thu, 26 Jun 2025 15:08:31 +0100 Subject: [PATCH 1/2] Split-FindResource- Out On RW recommendation, FindResource has been split out as an independent workflow --- .../Cancel-Booking.page.md | 2 +- .../Rebook-Methods.page.md | 2 +- .../Update-Existing-Booking.page.md | 2 +- .../Home/Core/1.3.0/Index.page.md | 1 + .../Cancellation.page.md | 20 ++-------------- .../Find-Resource.md | 24 +++++++++++++++++++ .../toc.yaml | 4 +++- 7 files changed, 33 insertions(+), 22 deletions(-) create mode 100644 guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Find-Resource.md diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Cancel-Booking.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Cancel-Booking.page.md index 79da1ce1..70cd1ac2 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Cancel-Booking.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Cancel-Booking.page.md @@ -6,7 +6,7 @@ topic: core-StandardPattern-appointment-cancel-1.3.0 To cancel an appointment: -* Perform a [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment/-id-) operation using the id of the appointment to /Appointment/\{id\}. Alternatively, if the .id is not known, the read can be undertaken with [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment), using the {{pagelink:core-SPCancellation-1.3.0, text:patient information}}, and selecting the .id by the matching the required resource. NB: If a match cannot be performed, using this method, manual processes should be engaged. +* Perform a [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment/-id-) operation using the id of the appointment to /Appointment/\{id\}. Alternatively, if the .id is not known, the read can be undertaken with [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment), using the {{pagelink:core-SPFindResource-1.3.0, text:find resource}} workflow, and selecting the .id by the matching the required resource. NB: If a match cannot be performed, using this method, manual processes should be engaged. * Set the Appointment.status value to "cancelled" * Perform a [PUT](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#put-/Appointment/-id-) operation using the id of the appointment to /Appointment/\{id\} diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Rebook-Methods.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Rebook-Methods.page.md index 8074e2c6..4c3caf6a 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Rebook-Methods.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Rebook-Methods.page.md @@ -34,7 +34,7 @@ Alternatively, rebooking an appointment can be used outside of use-cases support * Confirm BaRS [Capabilities](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/metadata). * [Request Available slots](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Slot). * Select a slot. -* Perform a [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment/-id-) operation using the id of the appointment to /Appointment/\{id\}. Alternatively, if the .id is not known, the read can be undertaken with [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment), using the {{pagelink:core-SPCancellation-1.3.0, text:patient information}}, and selecting the .id by the matching the required resource. NB: If a match cannot be performed, using this method, manual processes should be engaged. +* Perform a [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment/-id-) operation using the id of the appointment to /Appointment/\{id\}. Alternatively, if the .id is not known, the read can be undertaken with [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment), using the {{pagelink:core-SPFindResource-1.3.0, text:find resource}} workflow, and selecting the .id by the matching the required resource. NB: If a match cannot be performed, using this method, manual processes should be engaged. * Set the Appointment.status value to "cancelled" * Perform a [PUT](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#put-/Appointment/-id-) operation using the id of the appointment to /Appointment/\{id\} diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Update-Existing-Booking.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Update-Existing-Booking.page.md index 11cd8cdc..b7e4ea2f 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Update-Existing-Booking.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Appointment-StandardPattern/Update-Existing-Booking.page.md @@ -6,7 +6,7 @@ topic: core-StandardPattern-appointment-update-1.3.0 To update an appointment: -* Perform a [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment/-id-) operation using the id of the appointment to /Appointment/\{id\}. Alternatively, if the .id is not known, the read can be undertaken with [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment), using the {{pagelink:core-SPCancellation-1.3.0, text:patient information}}, and selecting the .id by the matching the required resource. NB: If a match cannot be performed, using this method, manual processes should be engaged. +* Perform a [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment/-id-) operation using the id of the appointment to /Appointment/\{id\}. Alternatively, if the .id is not known, the read can be undertaken with [GET](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#get-/Appointment), using the {{pagelink:core-SPFindResource-1.3.0, text:find resource}} workflow, and selecting the .id by the matching the required resource. NB: If a match cannot be performed, using this method, manual processes should be engaged. * Amend or append the resource as required. * Perform a [PUT](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1_2_0#put-/Appointment/-id-) operation using the id of the appointment to /Appointment/\{id\} diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Index.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Index.page.md index f3ca3e8f..ea92e514 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Index.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Index.page.md @@ -93,6 +93,7 @@ You will find here a set of documentation, specifications and services that desc     • {{pagelink:core-SPComposites-1.3.0 , text:Standard Pattern for Composites}}
    • {{pagelink:core-SPMessageHeader-1.3.0 , text:Message Headers}}
    • {{pagelink:core-SPCancellation-1.3.0 , text:Cancellation}}
+    • {{pagelink:core-SPFindResource-1.3.0, text:Find Resource Id}}
    • {{pagelink:core-SPUseCaseCategories-1.3.0 , text:Use Case Categories}}
  • {{pagelink:core-StandardPattern-appointment-1.3.0 , text:Standard Pattern - Appointments}}
    • {{pagelink:core-StandardPattern-appointment-booking-1.3.0 , text:Booking}}
diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Cancellation.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Cancellation.page.md index d1cad54f..03df182e 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Cancellation.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Cancellation.page.md @@ -7,25 +7,9 @@ topic: core-SPCancellation-1.3.0 The ability to reverse a digital request, by performing a cancellation, whether booking or referral, is a core workflow within BaRS. It completes the digital workflow, supports genuine interoperability and removes the need for manual intervention by service providers. -Cancellation, for any referral type or booking, is a stripped back request, containing only the specific resources a Receiver requires to the fulfil the request. There are separate MessageDefinitions involved when engaged in [referral](https://simplifier.net/nhsbookingandreferrals/messagedefinition-barsmessagedefinitionservicerequestrequestcancelled/~json) and [booking](https://simplifier.net/NHSBookingandReferrals/MessageDefinition-BARSMessageDefinitionBookingRequestCancelled/~json) cancellation workflows. +There are two potential routes for performing a cancellation of a booking or referral, dependending on Supplier implementation (see - Capability Statement (GET /metadata) for supported methods), either via $process-message or directly against the single resource (RESTfully). Where $process-message is used a stripped back request containing only the specific resources a Receiver requires to the fulfil the update are included. There are separate MessageDefinitions involved when engaged in the respective [referral](https://simplifier.net/nhsbookingandreferrals/messagedefinition-barsmessagedefinitionservicerequestrequestcancelled/~json) and [booking](https://simplifier.net/NHSBookingandReferrals/MessageDefinition-BARSMessageDefinitionBookingRequestCancelled/~json) cancellation workflows. Alternatively, where a RESTful pattern for updating a single resource is followed, the independent endpoints for [booking](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.2.2-alpha#put-/Appointment/-id-) and [referral](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.2.2-alpha#put-/ServiceRequest/-id-) support the update process. This workflow follows {{pagelink:core-StandardPattern-appointment-1.3.0 , text:Standard Pattern - Appointments}}. -A prerequisite when performing a cancellation of any request is to perform a read (GET) of either the booking or referral to be cancelled. The Sender **must** only make a cancellation request if the entity has a status which means it is still current; 'active' in the case of a referral (ServiceRequest) and 'booked' for a booking (Appointment). This ensures the Sender has the latest version of the resource they are about to change or, if it is no longer current (because its been actioned by the Receiver), allows the Sender to advise the end user so an alternative (often manual) workflow can be started. The Receiver **must not** process a cancellation request for a booking or referral which is not current, instead they **must** return an appropriate {{pagelink:core-ErrorHandling-1.3.0, text:error}} response. - -The Sender **must** obtain the (resource).Id value of the booking (Appointment) or referral (ServiceRequest) to be able to generate the cancellation request. If the Sender made the original request, they will likely know this and can directly request the specific resource to check the status, using the GET (read) by Id request. Alternatively, if they did not generate the original request (or there was a problem with the synchronous response being received) the resource can be obtained by searching for active bookings or referrals for the patient, either by using the national identifier (NHS No.) or patient demographics (Name (as defined by [FHIR](https://simplifier.net/packages/hl7.fhir.r4.core/4.0.1/files/2834389 )), Date of Birth, Home Address Postcode) (See diagram under 'Options for obtaining booking or referral' for detailed workflows). This will return a (FHIR) bundle of responses (typically, containing only one entry) which the Sender can match based on dateTime (elements dependent on resource) and use-case category values to identify the resource of interest. If the Sender cannot match the resource they should advise the user the cancellation cannot be performed and to revert to manual cancellation options instead. - -#### Options for obtaining booking or referral - -
-
-

-The below diagram details the options for obtaining the booking (Appointment) or referral (ServiceRequest) resource, prior to cancellation. The Sender must know the (resource).status and (resource).id values, as minimum, to build a valid cancellation request. -

-
-
- -
-
-
+It is a prerequisite, when performing a cancellation, to read (GET) the booking or referral to be cancelled, following the {{pagelink:core-SPFindResource-1.3.0, text:find resource}} steps. This ensure the Sender has the key values to build the request and verifies they can proceed with the workflow. The Sender **must** only make a cancellation request if the entity being cancelled has a status which means it is still current; 'active' in the case of a referral (ServiceRequest) and 'booked' for a booking (Appointment). This ensures the Sender has the latest version of the resource they are about to change or, if it is no longer current (because its been actioned by the Receiver), allows the Sender to advise the end user so an alternative (often manual) workflow can be started. The Receiver **must not** process a cancellation request for a booking or referral which is not current, instead they **must** return an appropriate {{pagelink:core-ErrorHandling-1.3.0, text:error}} response. ## Cancellation Referral Request Payload diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Find-Resource.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Find-Resource.md new file mode 100644 index 00000000..0aae8726 --- /dev/null +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Find-Resource.md @@ -0,0 +1,24 @@ +--- +topic: core-SPFindResource-1.3.0 +--- + + +## {{page-title}} + +A prerequisite, when undertaking any update routine, is to perform a read (GET) of either the booking or referral to be amended (including cancellation routines). This ensures the Sender has the most recent version of the resource being updated and verifies they can proceed with the workflow. For example, to engage in a cancellation workflow, the status of the entity being cancelled must currently be classed as 'active'. + +As a first step the Sender **must** obtain the (resource).Id of the booking (Appointment) or referral/validation (ServiceRequest) and they are several ways to do this. If the Sender made the original request, they will likely know this and can directly request the specific resource to check the status, using the GET (read) by Id endpoint. Alternatively, if they did not generate the original request (or there was a problem with the synchronous response being received) the full resource can be obtained by searching for active bookings or referrals for the patient, either by using the national identifier (NHS No.) or patient demographics (Name (as defined by [FHIR](https://simplifier.net/packages/hl7.fhir.r4.core/4.0.1/files/2834389 )), Date of Birth, Home Address Postcode). This will return a (FHIR) bundle of responses (typically, containing only one entry) which the Sender can match, based on dateTime (elements dependent on resource) and use-case category values, to identify the resource of interest. If the Sender cannot accurately match the resource they should advise the user the update cannot be performed and to revert to manual options instead. The diagram under 'Options for obtaining booking or referral' outlines the options above. + +#### Options for obtaining booking or referral + +
+
+

+The below diagram details the options for obtaining the booking (Appointment) or referral/validation (ServiceRequest) resource, prior to update (including cancellation). The Sender must know the (resource).status and (resource).id values, as minimum, to build a valid update request. +

+
+
+ +
+
+
\ No newline at end of file diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/toc.yaml b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/toc.yaml index 66f49100..6f501ca9 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/toc.yaml +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/toc.yaml @@ -8,5 +8,7 @@ filename: Message-Headers.page.md - name: Cancellation filename: Cancellation.page.md +- name: Find Resource + filename: Find-Resource.page.md - name: Use Case Categories - filename: Use-Case-Categories.page.md + filename: Use-Case-Categories.page.md \ No newline at end of file From a9129932aec78dda2216aeab70d3268acfe77231 Mon Sep 17 00:00:00 2001 From: Carl De'ath <74620667+cda69@users.noreply.github.com> Date: Thu, 26 Jun 2025 15:30:54 +0100 Subject: [PATCH 2/2] typo --- .../Standard-Pattern-Composite-Messages/Cancellation.page.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Cancellation.page.md b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Cancellation.page.md index 03df182e..26e65ec4 100644 --- a/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Cancellation.page.md +++ b/guides/Live-ImplementationGuide-BaRS/Home/Core/1.3.0/Standard-Pattern-Composite-Messages/Cancellation.page.md @@ -9,7 +9,7 @@ The ability to reverse a digital request, by performing a cancellation, whether There are two potential routes for performing a cancellation of a booking or referral, dependending on Supplier implementation (see - Capability Statement (GET /metadata) for supported methods), either via $process-message or directly against the single resource (RESTfully). Where $process-message is used a stripped back request containing only the specific resources a Receiver requires to the fulfil the update are included. There are separate MessageDefinitions involved when engaged in the respective [referral](https://simplifier.net/nhsbookingandreferrals/messagedefinition-barsmessagedefinitionservicerequestrequestcancelled/~json) and [booking](https://simplifier.net/NHSBookingandReferrals/MessageDefinition-BARSMessageDefinitionBookingRequestCancelled/~json) cancellation workflows. Alternatively, where a RESTful pattern for updating a single resource is followed, the independent endpoints for [booking](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.2.2-alpha#put-/Appointment/-id-) and [referral](https://digital.nhs.uk/developer/api-catalogue/booking-and-referral-fhir/v1.2.2-alpha#put-/ServiceRequest/-id-) support the update process. This workflow follows {{pagelink:core-StandardPattern-appointment-1.3.0 , text:Standard Pattern - Appointments}}. -It is a prerequisite, when performing a cancellation, to read (GET) the booking or referral to be cancelled, following the {{pagelink:core-SPFindResource-1.3.0, text:find resource}} steps. This ensure the Sender has the key values to build the request and verifies they can proceed with the workflow. The Sender **must** only make a cancellation request if the entity being cancelled has a status which means it is still current; 'active' in the case of a referral (ServiceRequest) and 'booked' for a booking (Appointment). This ensures the Sender has the latest version of the resource they are about to change or, if it is no longer current (because its been actioned by the Receiver), allows the Sender to advise the end user so an alternative (often manual) workflow can be started. The Receiver **must not** process a cancellation request for a booking or referral which is not current, instead they **must** return an appropriate {{pagelink:core-ErrorHandling-1.3.0, text:error}} response. +It is a prerequisite, when performing a cancellation, to read (GET) the booking or referral to be cancelled, following the {{pagelink:core-SPFindResource-1.3.0, text:find resource}} steps. This ensures the Sender has the key values to build the request and verifies they can proceed with the workflow. The Sender **must** only make a cancellation request if the entity being cancelled has a status which means it is still current; 'active' in the case of a referral (ServiceRequest) and 'booked' for a booking (Appointment). This ensures the Sender has the latest version of the resource they are about to change or, if it is no longer current (because its been actioned by the Receiver), allows the Sender to advise the end user so an alternative (often manual) workflow can be started. The Receiver **must not** process a cancellation request for a booking or referral which is not current, instead they **must** return an appropriate {{pagelink:core-ErrorHandling-1.3.0, text:error}} response. ## Cancellation Referral Request Payload