ESMD FHIR Implementation Guide
1.0.0 - esmd

ESMD FHIR Implementation Guide - Local Development build (v1.0.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Operation Definition

Overview

The generate-presigned-url operation is a custom esMD FHIR Operation that is based on the HL7 OperationDefinition resource. It allows clients to request presigned URLs that are used to upload files to and download files from esMD's secure storage without the need to obtain direct access.

This OperationDefinition resource provides information about the operation's behavior, parameters, and expected results. It integrates smoothly with esMD's FHIR workflows, and is central to esMD's ability to handle large files associated with DocumentReference resources. The operation's input and output parameters are clearly defined, ensuring proper functionality and security.

Key Components of the OperationDefinition

  1. Name and Versioning:
    • name: The operation is named GeneratePreSignedUrl, indicating its function to generate presigned URLs for file operations.
    • version: Version 1.0.0 is specified to track the operation's version, making it easy to manage updates and changes in the future.
  2. Status and Kind:
    • status: Set to #active, indicating that the operation is currently in use and available for clients to call.
    • kind: Defined as #operation, meaning this is a custom FHIR operation that performs a specific task beyond the standard FHIR RESTful interactions (such as read, create, update, delete).
  3. Code and Resource:
    • code: The operation code is #generate-presigned-url. This is the identifier clients use when invoking the operation. It acts as a command to trigger the URL generation process.
    • resource: The operation is associated with the DocumentReference resource. This means the operation is relevant to documents, such as clinical notes, reports, or imaging results, that are being uploaded or downloaded.
  4. System, Type, and Instance Usage:
    • system = false: This operation is not system-wide, meaning it cannot be applied across all resources or operations on the server.
    • type = true: Indicates that this is a type-level operation, meaning it operates on specific resources, in this case, DocumentReference.
    • instance = false: The operation is not instance-specific, meaning it is not tied to a particular instance of a DocumentReference but rather to the resource type as a whole.
  5. Description:
    • description: The operation is described as a mechanism to generate presigned URLs for uploading or downloading files from an esMD storage. This description provides clarity to developers and users about the operation’s purpose and usage.

Parameter Definitions

The operation uses both input and output parameters, which are defined in the parameter array. Each parameter includes attributes such as name, use (input/output), cardinality (min/max), documentation, and type.

Input Parameters

  1. organizationid:
    • name: #Organizationid
    • use: Input (#in)
    • min/max: Exactly one (1..1), meaning it is a required parameter.
    • type: The type is #string, indicating that the client should provide the sender's OID (Object Identifier) as a string.
    • documentation: Describes the sender's OID that is requesting to upload the file. This parameter helps ensure the presigned URL is generated for the correct user or system.
  2. filename:
    • name: #filename
    • use: Input (#in)
    • min/max: Exactly one (1..1), meaning it is a required parameter.
    • type: The type is #string, indicating that the client must specify the file name as a string.
    • documentation: Describes the file to be uploaded. The filename parameter allows the operation to prepare the presigned URL for the correct file destination.

Output Parameters

  1. uploadUrl:
    • name: #uploadUrl
    • use: Output (#out)
    • min/max: Exactly one (1..1), meaning it is a required output.
    • type: The type is #uri, meaning the output is a URL (Uniform Resource Identifier).
    • documentation: Describes the generated presigned URL, which is used by the client to upload or download the file to/from the esMD storage. The URL is time-limited, providing secure access to the file.
  2. expiresIn:
    • name: #expiresIn
    • use: Output (#out)
    • min/max: Exactly one (1..1), meaning it is a required output.
    • type: The type is #duration, which represents the expiration time of the presigned URL in seconds.
    • documentation: Describes how long the presigned URL will remain valid before it expires. This is important for ensuring that access to the esMD storage file is secure and limited to a specific time window.

Example Workflow

  1. Client Request:
    • The client sends a request to the FHIR server invoking the $generate-presigned-url operation.
    • The request includes the organizationid and filename parameters as inputs.

    Example Request:

    {
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "organizationid",
      "valueString": "2.16.840.1.113883.4.1.1.1234"
    },
    {
      "name": "filename",
      "valueString": "clinical-document.pdf"
    }
  ]
}
  2. Server Processing:
    • The FHIR server processes the request, generating a presigned URL for the specified file in the esMD storage.
    • The server returns the presigned URL (uploadUrl) and the expiration time (expiresIn) as output parameters.
  3. Client Receives the Response:
    • The client receives the presigned URL and uses it to upload or download the file.
    • The URL is valid for a specified period, defined by expiresIn.

    Example Response:

    {
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "uploadUrl",
      "valueUri": "https://my-fhir-bucket.s3.amazonaws.com/uploads/clinical-document.pdf?AWSAccessKeyId=..."
    },
    {
      "name": "expiresIn",
      "valueDuration": {
        "value": 3600,
        "unit": "seconds",
        "system": "http://unitsofmeasure.org",
        "code": "s"
      }
    }
  ]
}

Security Considerations

  • presigned URLs: presigned URLs provide secure, time-limited access to the esMD storage for uploading or downloading files. By ensuring the URLs expire after a certain period, security is maintained, reducing the risk of unauthorized access.
  • OID Verification: The organizationid input parameter ensures that the presigned URL is only generated for the correct sender, preventing unauthorized users from gaining access to the esMD storage.

Conclusion

The generate-presigned-url operation allows clients to obtain presigned URLs for securely uploading or downloading files to/from an esMD storage in an AWS environment. It integrates smoothly with FHIR workflows, particularly for handling large files associated with DocumentReference resources. The operation's input and output parameters are clearly defined, ensuring proper functionality and security.