Skip to main content

External Files and Document References

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 Binary Data guide for how Medplum stores file payloads, and the DocumentReference API guide for the resource itself.

Example: Creating a Document Reference 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.

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

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

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

See Also​