Handling External Files

Introduction

While the most valuable way of storing healthcare information is in a structured FHIR representation, healthcare apps often need to store and index documents from external systems. For example, patients may submit medical records from other providers in the form of PDF documents.

The DocumentReference resource serves as a "pointer" to these external documents so that they can be indexed and searched. Specifically, DocumentReference.content.attachment can refer to a Binary resource (PDFs, images, videos, etc.), a URL, or anything else supported by the Attachment datatype.

See the DocumentReference API guide for more info.

Example: Creating a DocumentReference for a binary file

This is a similar process to creating a PDF file from a Bot .

First, upload the binary file as a Binary resource. Then, create the corresponding DocumentReference as a pointer. For more details on using [Binary] resources see the Binary Data guide.

Typescript

import { MedplumClient, getReferenceString } from '@medplum/core';

// Create a `Binary` resource with file data
const binary = await medplum.createBinary(data, 'records.pdf', 'application/pdf');

// Create the `DocumentReference` resource
const docReference = await medplum.createResource({
  resourceType: 'DocumentReference',
  status: 'current',
  content: [
    {
      attachment: {
        title: 'External Records',
        url: getReferenceString(binary),
      },
    },
  ],
});

CLI

medplum login
medplum post Binary 'data-as-string'

# {
#   "resourceType": "Binary",
#   "id": "example-binary-id",
#   "url": "https://storage.medplum.com/binary/..."
#    ...
# }

medplum post DocumentReference '{"resourceType":"DocumentReference","content":[{"attachment":{"contentType":"application/pdf","url":"Binary/example-binary-id","title":"External Records"}}],"status":"current"}'

# {
#   "resourceType": "DocumentReference",
#   "id": "example-doc-reference-id",
#   "content": [
#     {
#       "attachment": {
#         "contentType": "text/plain",
#         "url": "https://storage.medplum.com/binary/...",
#         "title": "External Records"
#       }
#     }
#   ],
#   "status": "current",
#   ...
# }

cURL

curl 'https://api.medplum.com/fhir/R4/Binary?_filename=records.pdf' \
  -H 'authorization: Bearer $ACCESS_TOKEN' \
  -H 'content-type: text/plain' \
  --data-raw '{"resourceType":"Binary","contentType":"text/plain", "data": "$DATA"}' \

# {
#   "resourceType": "Binary",
#   "id": "example-binary-id",
#   "url": "https://storage.medplum.com/binary/..."
#    ...
# }

  curl -X POST 'https://api.medplum.com/fhir/R4/DocumentReference' \
  -H 'authorization: Bearer $ACCESS_TOKEN' \
  -H 'content-type: application/fhir+json' \
  --data-raw '{"resourceType":"DocumentReference","content":[{"attachment":{"contentType":"text/plain","url":"Binary/10c959e4-4d70-4c25-a58c-c1c4f604b15a","title":"External Records"}}],"status":"current"}' \

  # {
#   "resourceType": "DocumentReference",
#   "id": "example-doc-reference-id",
#   "content": [
#     {
#       "attachment": {
#         "contentType": "text/plain",
#         "url": "https://storage.medplum.com/binary/...",
#         "title": "External Records"
#       }
#     }
#   ],
#   "status": "current",
#   ...
# }

Note

DocumentReference.content.attachment.url can refer to any external url. The Medplum server handles urls of the form "Binary/id" as a special case and converts them to pre-signed URLs at storage.medplum.com. You can read more about pre-signed URLs on the AWS docs