On this page:

15.1FHIR Bulk Export Operation

 

The FHIR Bulk Data Access protocol describes a mechanism for efficiently requesting large amounts of data in a convenient format. This protocol can be used to request all data on a server, or a specific subset that is useful for a given use cas.

15.1.1Enabling Bulk Export

 

Bulk export support is configured on the FHIR Storage module via the bulk_export.enabled property.

Note that Bulk Export file generation can involve the creation of many large Binary resources, so it is recommended to enable Externalized Binary Storage when using this feature.

15.1.2Supported Requests

 

The FHIR Bulk Data Access specification describes several invocation styles. The following table outlines currently supported functionality.

Name Description URL Syntax Supported
Endpoint - All Patients Export a detailed set of FHIR resources of diverse resource types pertaining to all patients. [fhir base]/Patient/$export
Endpoint - Group of Patients Export a detailed set of FHIR resources of diverse resource types pertaining to all patients in specified Group. [fhir base]/Group/[id]/$export
Endpoint - System Level Export Export data from a FHIR server, whether or not it is associated with a patient. [fhir base]/$export

All Patients Parameters

The following parameters are supported for the Endpoint - All Patients invocation style.

Name Optional? Multiple Allowed? Description Example
_outputFormat Yes No Specifies the output encoding style that should be used. Currently only application/fhir+ndjson is supported. application/fhir+ndjson
_type Yes No Specifies a comma-separated list of resource types to include. If this parameter is absent, all resource types except Binary will be exported. The Binary type must not be included in this list. Patient, Practitioner
_since Yes No Only resources that were last updated on or after the given time will be included. 2019-10-25T11:14:00Z
_typeFilter Yes Yes Specifies a search URL that can be used to narrow the scope of the export. Multiple repetitions of this parameter may be used to narrow the scope of multiple resources. Patient?identifier=foo

15.1.3Requesting A Bulk Extract

 
Initiating a Bulk Export requires the FHIR_OP_INITIATE_BULK_DATA_EXPORT permission.

This section describes the user flow when requesting a bulk extract.

First, a user invokes the $export operation to initiate the request. This can be done using either an HTTP GET request with export request parameters included in the URL or as an HTTP POST with the export request parameters included in a FHIR Parameters resource.

Initiating Using HTTP GET

The following example shows a URL that can be used to initiate a Bulk Export using an HTTP GET. For readability, the URL is split over multiple lines but it would not be in a real invocation. https://fhir.example.com:8000/$export
   
?_outputFormat=application%2Ffhir%2Bndjson
   
&_type=Patient%2C%20Practitioner
   
&_since=2019-10-25T10%3A07%3A58.788-04%3A00
   
&_typeFilter=Patient%3Fidentifier%3Dfoo
   
&_typeFilter=Practitioner%3Fidentifier%3Dbar

The complete HTTP Request is shown below:

GET /$export?[params]
Prefer: respond-async

Initiating Using HTTP POST

The following example shows an example Parameters resource that can be used to initiate a Bulk Export using an HTTP POST.

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "_outputFormat",
      "valueString": "application/fhir+ndjson"
    },
    {
      "name": "_type",
      "valueString": "Patient, Practitioner"
    },
    {
      "name": "_since",
      "valueInstant": "2019-10-25T11:01:45.660-04:00"
    },
    {
      "name": "_typeFilter",
      "valueString": "Patient?identifier=foo"
    }
  ]
}

The complete HTTP Request is shown below:

POST /$export
Prefer: respond-async
Content-Type: application/fhir+json

{ ...payload... }

Initiation Response

Once the server has processed the request, it will respond with a response similar to the following:

HTTP/1.1 202 Accepted
Content-Location: https://fhir.example.com:8000/$export-poll-status?_jobId=0000000-1111111-2222222

The status of 202 means that the server has successfully received the request and has scheduled a background job that will assemble the Bulk Export payload. The Content-Location header indicates a URL that may be used by the client to request an update on the status of the background job.

15.1.4Retrieving Data

 
Polling for Bulk Export job status requires the FHIR_OP_INITIATE_BULK_DATA_EXPORT permission.

Once a job has been initiated, the client may poll the server to request information about the status. This is done by requesting an HTTP GET for the URL specified in the Content-Location header in the previous step.

GET https://fhir.example.com:8000/$export-poll-status?_jobId=0000000-1111111-2222222

The server will respond with a response similar to the following while the job is still being built.

HTTP/1.1 202 Accepted
X-Progress: Build in progress - Status set to BUILDING at 2019-10-25T11:27:16.763-04:00
Retry-After: 120

When the server has completed assembling the export payload, the same polling request will return a response similar to the following. The response payload is a list of files that were assembled by the Binary export job. Note that the payloads are assembled using Binary resources, so the client will need to have appropriate permission on the server to download Binary resources in order to be able to access the export contents.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 311 

{
  "transactionTime" : "2019-10-25T11:31:22.487-04:00",
  "output" : [ {
    "type" : "Patient",
    "url" : "https://fhir.example.com:8000/Binary/111"
  }, {
    "type" : "Patient",
    "url" : "https://fhir.example.com:8000/Binary/222"
  }, {
    "type" : "Patient",
    "url" : "https://fhir.example.com:8000/Binary/333"
  } ]
}