[RAA-703] Update OAS docs for available actions and cancel referral

Author: nicolebalmer1-nhs

specification/components/stu3/schemas/endpoints/a029-available-actions-for-user-list.yaml

@@ -23,6 +23,7 @@ description: |
 
   Supported action:
     - Record Review Outcome
+    - Cancel Referral
   
   ### Healthcare worker, user-restricted access
   
@@ -54,7 +55,8 @@ description: |
     - Change Shortlist and Send for Triage
 
   As a service provider, the only action returned will be:
-    - Record Review Outcome 
+    - Record Review Outcome
+    - Cancel Referral
 
   ## Related endpoints
 

specification/components/stu3/schemas/endpoints/a036-cancel-referral.yaml

@@ -19,13 +19,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`
 
   You must use [[HYPERLINK_A004]] to retrieve a list of reference data, which detail the reason the cancellation is being performed. You can only use reference data from the set `REFERRAL-CANCELLATION-REASON`.
 
 
   To find out which reference data from this set can be used, the following filters can be used depending on the cancellation scenario:
 
-  ***1. I want to cancel the referral and the current appointment***
+  ***1. I want to cancel the referral and the current appointment as a Referrer***
 
   * Obtain reference data from `REFERRAL-CANCELLATION-REASON` and filter:
 
@@ -40,7 +42,7 @@ description: |
     * if provided, `effectiveTo` must **not** be in the past
 
 
-  ***2. I want to cancel a referral, for which there is no current appointment***
+  ***2. I want to cancel a referral, for which there is no current appointment as a Referrer***
 
   * Obtain reference data from `REFERRAL-CANCELLATION-REASON` and filter:
 
@@ -53,6 +55,34 @@ description: |
     * `effectiveFrom` must be in the past, and
 
     * if provided, `effectiveTo` must **not** be in the past
+  
+  ***3. I want to cancel the referral and the current appointment as a Service Provider***
+
+  * Obtain reference data from `REFERRAL-CANCELLATION-REASON` and filter:
+
+    * `referrerUsage` must be `CANCEL_REFERRAL`, and
+
+    * `businessFunction` must be `SERVICE_PROVIDER_CLINICIAN` or `SERVICE_PROVIDER_CLINICIAN_ADMIN` (depending which authenticated user will be performing the action), and
+
+    * `canCancelAppointment` must be true, and
+
+    * `effectiveFrom` must be in the past, and 
+
+    * if provided, `effectiveTo` must **not** be in the past
+
+  ***4. I want to cancel a referral, for which there is no current appointment as a Service Provider***
+  
+  * Obtain reference data from `REFERRAL-CANCELLATION-REASON` and filter:
+
+    * `referrerUsage` must be `CANCEL_REFERRAL`, and
+
+    * `businessFunction` must be `SERVICE_PROVIDER_CLINICIAN` or `SERVICE_PROVIDER_CLINICIAN_ADMIN` (depending which authenticated user will be performing the action), and
+
+    * `canCancelAppointment` must be true, and
+
+    * `effectiveFrom` must be in the past, and 
+
+    * if provided, `effectiveTo` must **not** be in the past
 
 
   You need to use [[HYPERLINK_A005]] to retrieve details of the referral in order to make this clinical decision.
@@ -89,14 +119,16 @@ description: |
 
   You can test the following scenarios in our sandbox environment:
 
-  | Scenario                                                                 | Request details                   |
-  | ------------------------------------------------------------------------ | --------------------------------- |
-  | Reason for Cancellation without Comment (Comment Not Mandatory)          | Intend Private With No Comment    |
-  | Reason for Cancellation with Comment (Comment Mandatory)                 | Patient Cancellation With Comment |
-  | Cancelled Referral                                                       | Raised in Error                   |
-  | Cancelled Appointment and Referral                                       | Referrer Cancellation             |
-  | Cancelled Referral After Prior Appointment Cancellation                  | Treatment No Longer Required      |
-  | Cancelled Referral with Existing Review Outcome                          | Intend Private With Comment       |
+  | Scenario                                                                 | Request details                       |
+  | ------------------------------------------------------------------------ | ------------------------------------- |
+  | Reason for Cancellation without Comment (Comment Not Mandatory)          | Intend Private With No Comment        |
+  | Reason for Cancellation with Comment (Comment Mandatory)                 | Patient Cancellation With Comment     |
+  | Cancelled Referral                                                       | Raised in Error                       |
+  | Cancelled Appointment and Referral                                       | Referrer Cancellation                 |
+  | Cancelled Referral After Prior Appointment Cancellation                  | Treatment No Longer Required          |
+  | Cancelled Referral with Existing Review Outcome                          | Intend Private With Comment           |
+  | Cancelled Referral (Provider) without Comment (Comment Not Mandatory)    | Provider Cancellation With No Comment |
+  | Cancelled Referral with Triage Response                                  | Provider Cancellation via End Triage  |
 summary: Cancel referral (A036, FHIR STU3)
 operationId: a036-cancel-referral
 tags:
@@ -139,6 +171,14 @@ requestBody:
           summary: Cancelled Referral with Existing Review Outcome
           value:
             $ref: '../../examples/cancelReferral/requests/IntendPrivateWithComment.json'
+        cancel-referral-provider-without-comment:
+          summary: Cancelled Referral (Provider) without Comment (Comment Not Mandatory)
+          value:
+            $ref: ''
+        cancel-referral-with-triage-response:
+          summary: Cancelled Referral with Triage Response
+          value:
+            $ref: ''
 responses:
   '200':
     $ref: '../responses/cancelReferral/200Response.yaml'

specification/e-referrals-service-api.yaml

@@ -39,6 +39,7 @@ info:
       -	accept or reject a referral request
       -	retrieve Advice & Guidance (A&G) conversations and send responses
       -	convert Advice & Guidance (A&G) conversations into a referral
+      - cancel a referral
 
     **You cannot use this API to:**
 
@@ -78,7 +79,7 @@ info:
 
     | Access mode                   | Authentication via    | Functions               | Availability                    |
     | ----------------------------- | -------------------------- | ----------------------- | ------------------------------- |
-    | Application-restricted,<br/>unattended access | [[HYPERLINK_SIGNED_JWT]]   | <ul><li>[[HYPERLINK_A004]]</li><li>[[HYPERLINK_A005]]</li><li>[[HYPERLINK_A007]]</li><li>[[HYPERLINK_A008]]</li><li>[[HYPERLINK_A013]]</li><li>[[HYPERLINK_A024]]</li><li>[[HYPERLINK_A025]]</li><li>[[HYPERLINK_A028]]</li><li>[[HYPERLINK_A029]]</li><li>[[HYPERLINK_A033]]</li><li>[[HYPERLINK_A035]]</li><li>[[HYPERLINK_A037]]</li><li>[[HYPERLINK_A042]]</li><li>[[HYPERLINK_A043]]</li></ul> | [[HYPERLINK_PRODUCTION]] |
+    | Application-restricted,<br/>unattended access | [[HYPERLINK_SIGNED_JWT]]   | <ul><li>[[HYPERLINK_A004]]</li><li>[[HYPERLINK_A005]]</li><li>[[HYPERLINK_A007]]</li><li>[[HYPERLINK_A008]]</li><li>[[HYPERLINK_A013]]</li><li>[[HYPERLINK_A024]]</li><li>[[HYPERLINK_A025]]</li><li>[[HYPERLINK_A028]]</li><li>[[HYPERLINK_A029]]</li><li>[[HYPERLINK_A033]]</li><li>[[HYPERLINK_A035]]</li><li>[[HYPERLINK_A036]]</li><li>[[HYPERLINK_A037]]</li><li>[[HYPERLINK_A042]]</li><li>[[HYPERLINK_A043]]</li></ul> | [[HYPERLINK_PRODUCTION]] |
     | Healthcare worker,<br/>user-restricted access | [[HYPERLINK_CIS_AUTH_SHORT]]  | All Endpoints | [[HYPERLINK_PRODUCTION]] |
 
     ##### Application-restricted, unattended access
@@ -89,8 +90,9 @@ info:
     Write operations are currently supported for specific use cases via:
     - [[HYPERLINK_A028]]
     - [[HYPERLINK_A013]]
+    - [[HYPERLINK_A036]]
 
-    You will be required to submit your use case for review when using this endpoint via application-restricted, unattended access.
+    You will be required to submit your use case for review when using these endpoints via application-restricted, unattended access.
 
     ##### Healthcare worker, user-restricted access