[ERSSUP-64033]-[]-[Application-restricted OAS Document Update for A02…

specification/components/stu3/schemas/endpoints/a024-retrieve-advice-and-guidance-versioned.yaml

@@ -6,6 +6,7 @@ description: |
   Use this endpoint to retrieve a specific version of `CommunicationRequest`.
 
   ## Supported security patterns
+  - Application-restricted access, unattended access
   - Healthcare worker, user-restricted access
 
   ## Pre-requisites
@@ -14,6 +15,10 @@ description: |
 
   Note: e-RS only supports the retrieval of the most recent version of `CommunicationRequest`. You cannot retrieve earlier versions.
 
+  ## Important note
+
+  The Important notes for this endpoint are the same as for endpoint [[HYPERLINK_A024]].
+
   ## Use case
 
   See [[HYPERLINK_A005]].
@@ -36,9 +41,9 @@ parameters:
   - $ref: '../pathParameters/Ubrn.yaml'
   - $ref: '../pathParameters/Version.yaml'
   - $ref: '../headers/request/BearerAuthorization.yaml'
-  - $ref: '../headers/request/OdsCode.yaml'
-  - $ref: '../headers/request/BusinessFunction.yaml'
-  - $ref: '../headers/request/OnBehalfOfUserID.yaml'
+  - $ref: '../headers/request/OdsCodeOnlyUserRestricted.yaml'
+  - $ref: '../headers/request/BusinessFunctionOnlyUserRestricted.yaml'
+  - $ref: '../headers/request/OnBehalfOfUserIDOnlyUserRestricted.yaml'
   - $ref: '../headers/request/CorrelationID.yaml'
 responses:
   '200':

specification/components/stu3/schemas/endpoints/a024-retrieve-advice-and-guidance.yaml

@@ -9,22 +9,29 @@ description: |
   The conversation can be retrieved via [[HYPERLINK_A025]].
 
   ## Supported security patterns
+  - Application-restricted access, unattended access
   - Healthcare worker, user-restricted access
 
   ## Pre-requisites
 
+  You need to use the `Unique Booking Reference Number` (UBRN) of the advice and guidance request. 
+  For service provider users, you may have identified the UBRN via [[HYPERLINK_A023]].
+
+  ## Application-restricted access
+
+  In order to use this endpoint you must be an authenticated e-RS calling application.
+
+  ## Healthcare worker, user-restricted access
+
   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 use the `Unique Booking Reference Number` (UBRN) of the advice and guidance request. 
-  For service provider users, you may have identified the UBRN via [[HYPERLINK_A023]].
-
   ## Use case
 
-  As an authenticated user
+  As an authenticated user or application
 
   I need to retrieve the summary of an advice and guidance request
 
@@ -36,12 +43,20 @@ description: |
   convert the advice and guidance request into an appointment request. 
   If authorised, [[HYPERLINK_A027]] can be used to convert the advice and guidance request into an appointment request.
 
+  An advice and guidance request may have been converted to a referral (with the same UBRN), 
+  and in addition a referral pathway in e-RS can be made up of more than one UBRN. As such, 
+  it is important that all clinical information is obtained across all the related UBRNs in the pathway. 
+  These may be identified using [[HYPERLINK_A005]] and will be returned if the user is authorised to view this.
+
+  If the converted advice and guidance request is referred to a service outside of your organisation, 
+  the subsequent referral information may not be accessible due to existing data-access rules. However, 
+  the advice and guidance summary ([[HYPERLINK_A024]]), attachments ([[HYPERLINK_A006]]), advice and guidance conversation ([[HYPERLINK_A025]]) and 
+  clinical information ([[HYPERLINK_A043]]) which took place before such a conversion still forms part of the clinical information and can still be retrieved.
+
   ## Related endpoints
 
   After using this endpoint, use [[HYPERLINK_A025]] to retrieve the Advice and Guidance conversation itself.
 
-  Use [[HYPERLINK_A043]] to generate a PDF file overview relating to an advice and guidance request.
-
   ## Sandbox test scenarios
 
   You can test the following scenarios in our sandbox environment
@@ -56,9 +71,9 @@ operationId: a024-retrieve-advice-and-guidance
 parameters:
   - $ref: '../pathParameters/Ubrn.yaml'
   - $ref: '../headers/request/BearerAuthorization.yaml'
-  - $ref: '../headers/request/OdsCode.yaml'
-  - $ref: '../headers/request/BusinessFunction.yaml'
-  - $ref: '../headers/request/OnBehalfOfUserID.yaml'
+  - $ref: '../headers/request/OdsCodeOnlyUserRestricted.yaml'
+  - $ref: '../headers/request/BusinessFunctionOnlyUserRestricted.yaml'
+  - $ref: '../headers/request/OnBehalfOfUserIDOnlyUserRestricted.yaml'
   - $ref: '../headers/request/CorrelationID.yaml'
 responses:
   '200':

specification/components/stu3/schemas/endpoints/a025-retrieve-advice-and-guidance-conversation.yaml

@@ -8,25 +8,32 @@ description: |
   A 'conversation' takes the form of the messages between a referrer (seeking advice) and a provider or specialist. Messages can include attachments.
 
   ## Supported security patterns
+  - Application-restricted access, unattended access
   - Healthcare worker, user-restricted access
 
   ## Pre-requisites
 
-  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 use the `Unique Booking Reference Number` (UBRN) of the advice and guidance request. For service provider users, 
   you may have identified the UBRN via [[HYPERLINK_A023]].
 
   You need to use [[HYPERLINK_A024]] to retrieve the summary of an advice and guidance request. 
   This will importantly include the latest version of the request which must be used.
 
+  ## Application-restricted access
+
+  In order to use this endpoint you must be an authenticated e-RS calling application.
+
+  ## Healthcare worker, user-restricted access
+
+  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`
+
   ## Use case
 
-  As an authenticated user
+  As an authenticated user or application
 
   I need to retrieve the conversation that is present on an advice and guidance request
 
@@ -35,6 +42,16 @@ description: |
   ## Important note
 
   The conversation returned includes links to any attachments associated with the conversation.
+  This can be done via endpoint [[HYPERLINK_A006]]. 
+  Note, dependent on how attachments were added they may be linked to the Advice and Guidance summary instead of the conversation. 
+  These may be retrieved from [[HYPERLINK_A024]].
+
+  If the converted advice and guidance request is referred to a service outside of your organisation, 
+  the subsequent referral information may not be accessible due to existing data-access rules. 
+  However, the advice and guidance summary ([[HYPERLINK_A024]]), attachments ([[HYPERLINK_A006]]), 
+  advice and guidance conversation ([[HYPERLINK_A025]]) and 
+  clinical information ([[HYPERLINK_A043]]) which took place before such a conversion still forms part of the clinical information and can still be retrieved.
+  The conversation also gets included in the form of a PDF file returned by [[HYPERLINK_A007]].
 
   ## Related endpoints
 
@@ -62,9 +79,9 @@ parameters:
   - $ref: '../queryParameters/BasedOn.yaml'
   - $ref: '../queryParameters/Include-Communication.yaml'
   - $ref: '../headers/request/BearerAuthorization.yaml'
-  - $ref: '../headers/request/OdsCode.yaml'
-  - $ref: '../headers/request/BusinessFunction.yaml'
-  - $ref: '../headers/request/OnBehalfOfUserID.yaml'
+  - $ref: '../headers/request/OdsCodeOnlyUserRestricted.yaml'
+  - $ref: '../headers/request/BusinessFunctionOnlyUserRestricted.yaml'
+  - $ref: '../headers/request/OnBehalfOfUserIDOnlyUserRestricted.yaml'
   - $ref: '../headers/request/CorrelationID.yaml'
 responses:
   '200':

specification/components/stu3/schemas/endpoints/a043-retrieve-advice-and-guidance-overview-pdf.yaml

@@ -7,32 +7,39 @@ description: |
   This endpoint cannot be used to obtain a PDF file for a referral request.
 
   ## Supported security patterns
+  - Application-restricted access, unattended access
   - Healthcare worker, user-restricted access
 
   ## Pre-requisites
+
+  You need to use the `Unique Booking Reference Number` (UBRN) of an advice and guidance request.
+
+  ## Application-restricted access
+  In order to use this endpoint you must be an authenticated e-RS calling application.
+
+  ## Healthcare worker, user-restricted access
   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 use the `Unique Booking Reference Number` (UBRN) of an advice and guidance request.
-
   ## Important note
-  As noted for the [[HYPERLINK_A007]] endpoint that applies to referrals rather than advice and guidance requests, 
-  a referral pathway in e-RS can be made up of more than one UBRN. As such, it is important that all clinical information is obtained from across all the related 
-  UBRNs in the pathway as referenced in [[HYPERLINK_A005]].
-
-  An advice and guidance request can only ever exist as a single entity with no related UBRNs *unless* the advice and guidance request is converted to a referral. 
-  This can be done via endpoint [[HYPERLINK_A027]]. When the conversion is complete, the advice and guidance request becomes a 
-  referral (retaining the same UBRN) and continues its existence as such. Meaning that it may gain related referrals.
+
+  An advice and guidance request may have been converted to a referral (with the same UBRN), 
+  and in addition a referral pathway in e-RS can be made up of more than one UBRN. 
+  As such, it is important that all clinical information is obtained across all the related UBRNs in the pathway. 
+  These can be identified using [[HYPERLINK_A005]].
 
-  The advice and guidance conversation that took place before such a conversion still forms part of the clinical information. 
-  This conversation *does* get included in the PDF file returned by [[HYPERLINK_A007]].
+  If the converted advice and guidance request is referred to a service outside of your organisation, 
+  the subsequent referral information may not be accessible due to legitimate relationship rules. 
+  However, the advice and guidance summary ([[HYPERLINK_A024]]), 
+  attachments ([[HYPERLINK_A006]]), advice and guidance conversation ([[HYPERLINK_A025]]) and 
+  clinical information ([[HYPERLINK_A043]]) which took place before such a conversion still forms part of the clinical information and can still be retrieved.
 
   ## Use case
 
-  As an authenticated user
+  As an authenticated user or application
 
   I need to retrieve a PDF file overview of the advice and guidance request
 
@@ -51,9 +58,9 @@ summary: A043 - Retrieve advice and guidance overview PDF
 operationId: a043-retrieve-advice-and-guidance-overview-pdf
 parameters:
   - $ref: '../headers/request/BearerAuthorization.yaml'
-  - $ref: '../headers/request/OdsCode.yaml'
-  - $ref: '../headers/request/BusinessFunction.yaml'
-  - $ref: '../headers/request/OnBehalfOfUserID.yaml'
+  - $ref: '../headers/request/OdsCodeOnlyUserRestricted.yaml'
+  - $ref: '../headers/request/BusinessFunctionOnlyUserRestricted.yaml'
+  - $ref: '../headers/request/OnBehalfOfUserIDOnlyUserRestricted.yaml'
   - $ref: '../headers/request/CorrelationID.yaml'
   - $ref: '../pathParameters/UbrnAdviceAndGuidance.yaml'
 responses: