[ERSSUP-80439]-[JW/AP]-[Finalise R4 download endpoint schema, wording and examples]-[FV]

Author: francisco-videira-nhs

sandbox/src/mocks/r4/requestUrlForFileDownload/example_attachment.pdf

@@ -2,11 +2,11 @@ const businessFunctionValidator = require('../../services/businessFunctionValida
 
 module.exports = [
   /**
-   * Sandbox implementation for retrieveBinary A039 (R4) endpoint
+   * Sandbox implementation for retrieveBinary A042 (R4) endpoint
    */
   {
     method: 'GET',
-    path: '/FHIR/R4/Binary/{attachmentUuid}',
+    path: '/FHIR/R4/Binary/{attachmentId}',
     handler: (request, h) => {
 
       const allowedBusinessFunctions = ["REFERRING_CLINICIAN", "REFERRING_CLINICIAN_ADMIN", "SERVICE_PROVIDER_CLINICIAN", "SERVICE_PROVIDER_CLINICIAN_ADMIN"]
@@ -16,17 +16,20 @@ module.exports = [
         return validationResult
       }
 
-      const uuid = request.params.attachmentUuid;
+      const attachmentId = request.params.attachmentId;
       const url = request.url.href;
       const objectStore = "/ObjectStore/RetrieveBinary/d497bbe3-f88b-45f1-b3d4-9c563e4c0f5f";
       const location = url.split('/FHIR')[0] + objectStore;
+      const uuidPattern = /^[0-9a-f]{8}-([0-9a-f]{4}-){3}[0-9a-f]{12}$/i;
+      const attPattern = /^att-\d+-\d+$/;
 
-      if (uuid === '704c3791-0873-45e9-9a04-b51996f8d93f' && request.method === 'get') {
+
+      if ((uuidPattern.test(attachmentId) || attPattern.test(attachmentId)) && request.method === 'get') {
         const response = h.response().code(307)
         response.headers["Location"] = location;
         return response
       } else {
-        return h.file('SandboxErrorOutcome.json').code(422);
+        return h.file('./r4/R4-SandboxErrorOutcome.json').code(400);
       }
 
     }

sandbox/src/routes/r4/retrieveBinary.js

@@ -1,24 +1,21 @@
 module.exports = [
   /**
    * Sandbox implementation for retrieveBinary (R4) endpoint helper, 
-   * with an ObjectStore 'mock', allowing redirection and example file retrieval.
+   * with an ObjectStore 'mock', allowing redirection and simple file retrieval.
    */
   {
     method: 'GET',
-    path: '/ObjectStore/RetrieveBinary/{fileDownloadUuid}',
+    path: '/ObjectStore/RetrieveBinary/{fileId}',
     handler: (request, h) => {
 
-      const uuid = request.params.fileDownloadUuid
-      const exampleResponsePath = 'retrieveAttachment/responses/example_attachment.pdf'
+      const fileId = request.params.fileId
       const filename = 'example_attachment.pdf'
+      const filePath = `./r4/requestUrlForFileDownload/${filename}`
       const responseCode = 200
 
-      if (uuid === 'd497bbe3-f88b-45f1-b3d4-9c563e4c0f5f') {
-        return h.file(exampleResponsePath, {
-          mode: 'attachment',
-          filename: filename,
-          etagMethod: false
-        }).code(responseCode);
+      if (fileId === 'd497bbe3-f88b-45f1-b3d4-9c563e4c0f5f') {
+        return h.file(filePath).code(responseCode).header('Content-Disposition', `attachment; filename*=UTF-8''${filename}`)
+          .header('Content-Type', 'application/pdf');
       }
     }
   }

sandbox/src/routes/r4/retrieveBinaryHelper.js

@@ -16,7 +16,7 @@ module.exports = [
       }
 
       // this should never happen as we always get a valid response for this endpoint
-      return h.file('R4-SandboxErrorOutcome.json').code(400);
+      return h.file('./r4/R4-SandboxErrorOutcome.json').code(400);
 
 
     }

sandbox/src/routes/r4/retrieveBusinessFunctions.js

@@ -12,7 +12,7 @@ module.exports = [
             // check that the query exists and is correct
             const query = request.query._query;
             if (query == undefined || query != "onBehalfOf") {
-                return h.file('R4-SandboxErrorOutcome.json').code(400);
+                return h.file('./r4/R4-SandboxErrorOutcome.json').code(400);
             }
 
             if (request.headers["nhsd-ers-business-function"] !== "SERVICE_PROVIDER_CLINICIAN_ADMIN")
@@ -27,7 +27,7 @@ module.exports = [
             }
 
             // this should never happen as we always get a valid response for this endpoint
-            return h.file('R4-SandboxErrorOutcome.json').code(400);
+            return h.file('./r4/R4-SandboxErrorOutcome.json').code(400);
 
 
         }

sandbox/src/routes/r4/retrieveOboUsers.js

@@ -43,7 +43,7 @@ def main():
         "[[HYPERLINK_A038]]": "[Retrieve appointment (A038)](#get-/STU3/Appointment/-id-)",
         "[[HYPERLINK_A040]]": "[Retrieve “on-behalf-of” practitioner user information (A040)](#get-/R4/Practitioner)",
         "[[HYPERLINK_A041]]": "[Search for service requests (A041)](#get-/R4/ServiceRequest)",
-        "[[HYPERLINK_A042]]": "[Request pre-signed URL to download file from document store (A042)](#get-/R4/Binary/-id-)",
+        "[[HYPERLINK_A042]]": "[Retrieve attachment (A042)](#get-/R4/Binary/-id-)",
         "[[HYPERLINK_A043]]": "[Retrieve advice and guidance overview PDF (A043)](#post-/STU3/CommunicationRequest/-ubrn-/$ers.generateCRI)",
         "[[HYPERLINK_A044]]": "[Create advice and guidance request (A044)](#post-/STU3/CommunicationRequest/$ers.createAdviceAndGuidance)",
         "[[HYPERLINK_ONBOARDING]]": "[onboarding](#overview--onboarding)",

scripts/populate_placeholders.py

@@ -0,0 +1,97 @@
+security:
+  - bearerAuth: []
+description: |
+  ## Overview
+  Use this endpoint to retrieve a file that is attached to a referral or advice request.
+
+  ## Supported security patterns
+  - Application-restricted, unattended access
+  - Healthcare worker, user-restricted access
+
+  ## Pre-requisites
+  ### Application-restricted, unattended access
+  In order to use this endpoint you must be an authenticated e-RS calling application, working in the context of a Service Provider Organisation.
+
+  ### Healthcare worker, user-restricted access
+  In order to use this endpoint you must be an authenticated e-RS user or application and use one of the following e-RS roles:
+    - `REFERRING_CLINICIAN`
+    - `REFERRING_CLINICIAN_ADMIN`
+    - `SERVICE_PROVIDER_CLINICIAN`
+    - `SERVICE_PROVIDER_CLINICIAN_ADMIN`
+
+  ### Attachment availability
+  To use this endpoint, the attachment must be available for download. Attachments are only available after successful validation and malware scans. A request to retrieve an attachment that is not available for download will result in a 400 error. See the Response HTTP 400 section for further information.
+  
+  The availability status of an attachment can be retrieved via any endpoint that provides details of an attachment in the success response. Details of the availability statuses that may be returned via these endpoints can be found in the specification for [[HYPERLINK_A005]].
+  
+  Prior to retrieving an attachment, you will need to have retrieved the referral or advice request the attachment is associated with (via the [[HYPERLINK_A005]] or [[HYPERLINK_A024]] endpoints, for example). Referrals and advice requests include resolvable URLs to the files currently attached to them, which can be used with this endpoint to retrieve the attachments themselves.
+  
+  ## Support for a temporary redirect
+  This endpoint makes use of a HTTP 307 temporary redirect. It redirects the caller to a temporary location from which the file contents can be downloaded directly.
+
+  The temporary location is only valid for a short period of time and should be used immediately. 
+
+  Callers of this endpoint must ensure they:
+    - follow this redirect to retrieve the file
+    - do not cache the temporary location
+    - generate a new redirect each time the file is downloaded
+
+  See the Response HTTP 307 section for further information.
+
+  ## Important notes
+  A referral pathway in e-RS can be made up of more than one UBRN. For example: a referral is booked and seen in a general knee clinical assessment service (UBRN #1), and the service decides to onward refer to a more specialist knee meniscus service (UBRN #2). This would result in two UBRNs for the referral pathway. There may be additional related UBRNs if there are multiple onward referrals.
+
+  As such, it is important that all clinical information is obtained from across all the related UBRNs referenced in [[HYPERLINK_A005]]. You can do this using the following endpoints:
+    - [[HYPERLINK_A006]]
+    - [[HYPERLINK_A007]]
+
+  Note: It is possible that the initial UBRN may be the only one in the referral pathway to have clinical information and/or attachments associated.
+
+  ## Use case 
+  As an authenticated user
+
+  I need to retrieve a clinical attachment associated with a referral or advice request
+
+  So that I can assess its content and decide what further action may be needed.
+
+  ## Related endpoints
+    - [[HYPERLINK_A005]] to retrieve details of a referral. This includes references to clinical attachments, related referrals and other important data.
+    - [[HYPERLINK_A024]] to retrieve the summary of an advice and guidance request. This endpoint provides important contextual information about the advice and guidance request (e.g. the service/specialty to which advice has been requested, etc).
+    - [[HYPERLINK_A025]] to retrieve the advice and guidance conversation between the referring organisation and service providing organisation.
+    - [[HYPERLINK_A007]] to generate a PDF file that summarises clinical information for a referral.
+
+  ## Sandbox test scenarios
+  The sandbox for this endpoint is a simple implementation that only supports success cases.
+
+  Inline with the behaviour described in "Support for a temporary redirect", the sandbox will return a HTTP 307 temporary redirect. For simplicity, the temporary location will be static and never expire, unlike the live environment.
+
+  A successful response will always be returned, provided the Binary ID is in a valid format. The Availability Status of a file is not considered in the sandbox and a file will always be considered to be available for retrieval.
+
+  Successful responses will always return the same example PDF file.
+
+summary: Retrieve attachment (A042, FHIR R4)
+operationId: a042-retrieve-attachment
+tags:
+  - Retrieve clinical information
+parameters:
+  - $ref: '../headers/request/BearerAuthorization.yaml'
+  - $ref: '../headers/request/CorrelationID.yaml'
+  - $ref: '../headers/request/BusinessFunctionOnlyUserRestricted.yaml'
+  - $ref: '../headers/request/OdsCodeOnlyUserRestricted.yaml'
+  - $ref: '../headers/request/OnBehalfOfUserIDOnlyUserRestricted.yaml'
+  - $ref: '../pathParameters/BinaryId.yaml'
+responses:
+  '307':
+    $ref: '../responses/retrieveBinary/307Response.yaml'
+  '400':
+    $ref: '../responses/retrieveBinary/400Response.yaml'
+  '401':
+    $ref: '../responses/Unauthorized.yaml'
+  '403':
+    $ref: '../responses/ForbiddenOrNoLR.yaml'
+  '404':
+    $ref: '../responses/NotFound.yaml'
+  '429':
+    $ref: '../responses/TooManyRequests.yaml'
+  '500':
+    $ref: '../responses/InternalServerError.yaml'

specification/components/r4/schemas/endpoints/a042-request-pre-signed-url-for-file-download.yaml

@@ -0,0 +1,17 @@
+in: header
+name: NHSD-eRS-On-Behalf-Of-User-ID
+description: | 
+  The (SDS) user ID of the user that the authenticating user wishes to act on behalf of (OBO). 
+
+  "On behalf of" is only supported for a Service Provider Clinician Admin (SPCA) acting on behalf of a Service Provider Clinician (SPC). 
+
+  Where an OBO User ID is supplied the authenticating user must be an SPCA and the OBO User ID must be that of an appropriate SPC.
+
+  Not allowed for application-restricted access.
+
+  Required for user-restricted access where the Service Provider Clinician Admin Business Function is used for authentication.
+required: false
+schema:
+  type: string
+  example: '021600556514'
+