Bulk data

Bulk Data allows for the export of one or more patients along with their associated data.

Requests are made to [base url]/Group/[group id]/$export. The group IDs are established and maintained separately from the FHIR server.

A valid OAuth2 token is required to schedule an export. The subject of the token is used as the user ID and is recorded on the export request. Only HTTP requests with the same subject can be used to check on the status of that export request, cancel that request, or retrieve bulk data files for that request.

Once an export request has finished, the results are stored for seven days. After the export request has expired, the export request and all exported files are deleted.

When scheduling an export, an HTTP GET request is made to [base url]/Group/[group id]/$export. As mentioned above, the groups are maintained separately from the FHIR server. As well, the base URL is unique and will be provided when requested. A valid OAuth2 token is required. Upon success, there is no HTTP body, but there will be an HTTP header called Content-Location whose value is the URL that can be used to retrieve the status of the request, cancel the request, or retrieve the ndjson file locations.

The _type query parameter can be used to specify which FHIR resources to export for the patients contained in the group id. A request will be rejected if the _type query parameter contains resource names for which the user does not have permission to access. Omitting the _type query parameter will export all resources the user is allowed to export. Only patients and their data that the user has access to will be exported.

When checking the status of an export request, there are three possible responses:

1.The export request cannot be found:

•In the event an export request cannot be found, an HTTP 404 status code is returned, and a forbidden OperationOutcome is returned. The text of the OperationOutcome will specify that the queried request is not available.

2.The export is not yet complete:

•In the event an export request hasn’t yet started, or hasn’t yet finished, an HTTP 202 status code is returned. There will be no body to the response, but several HTTP headers will be included:

oRetry-After: the number of milliseconds to wait before the next status check should take place.

oX-Progress: the status of the export request. Can be one of: scheduled, started, or completed.

3.The export has completed:

•In the event an export request has finished, an HTTP 200 status code is returned, and a body containing application/json is returned. The body of the response is as follows:

otransactionTime: the time formatted as yyyy-MM-ddTHH:mm:ssZ when the request finished.

orequest: the URL of the original request made.

orequiresAccessToken: will always by true. An OAuth2 token is always required, and the token needs to be made for the same user that scheduled the export.

ooutput: an array of JSON objects representing each ndjson file produced by the export. The type property will be the FHIR resource name, and the url property will be the URL to access a specific ndjson file containing the exported FHIR resources.

oerror: an array of JSON objects formatted similar to the output array, except that it contains objects that encountered some kind of error in their production.

Exports can be canceled by issuing an HTTP DELETE request to the status check URL returned in the Content-Location HTTP header when the export request was first scheduled. A valid OAuth2 token issued to the same user that scheduled the export request is required.