Bulk Export

FHIR is normally used to access data one patient or resource at a time. However, providers and organizations accountable for managing the health of populations often need to efficiently access large volumes of information on a group of individuals. To support this use case, a custom Group Export operation (aka FLAT FHIR, FHIR Bulk Data, and Bulk FHIR) was implemented to return only FHIR resources as defined by the ATR data model. Use the FHIR $export operator to request the analytics bulk-data endpoint and retrieve a list of bulk data files for your client application to download.

The base endpoint that supports the bulk export is:

https://api.in.opalahealth.io:45000/Group/{id}/$export

The basic query of that endpoint is:

GET https://api.in.opalahealth.io:45000/Group/{id}/$export

The returned data from this query (barring the use of any additional query parameters) includes all clinical and admininistrative data for the patients in the specified group.

Workflow

The Bulk Export process works like this:

1. The requester is authenticated using the Authorization Server and gains access to the API.
2. The requester sends a bulk query using the base endpoint listed above.
3. The FHIR server sends an HTTP 202 response that includes the polling URL the requester can use to poll for the status of the export action. This URL can be accessed by means of the Response Header: Location.
4. The requester, when they choose, sends a request to the polling URL.
5. The FHIR server responds with either an HTTP 202 response (if the export is still in progress) or an HTTP 200 response (if it is not).
   
   • The HTTP 202 response includes the status of the request, the percent complete, and the retry value (in seconds) after which the server is polled again.
   • The HTTP 200 response includes a FHIR structure that specifies one or more URLs that can be used to retrieve binary packages (NDJSON files) that contain all the fire resources associated with this ATR Group.
6. The requester uses the provided URLs to retrieve the bulk data.

Note: The FHIR Bulk Data Access specification employs an asynchronous interaction model.

Using bulk data export a consumer organization can use the APIs to request the full Member Attribution List that is applicable to their specific organization for a specific contract.

This feature also enables registered parties to receive a custom set of FHIR resources which are listed below.

FHIR Resource	Data That Can Be Retrieved
Group	Retrieve Group identified in the ATRGroup export request
Patient	Patient, where Patient in Group:member Patient, where Patient in Coverage:subscriber Patient, where Patient in Coverage:beneficiary Patient, where Patient in Coverage:payor
Practitioner	Practitioner, where Practitioner in Group:ext-attributedProvider Practitoner, where Practitioner in PractitionerRole:practitioner, and PractitionerRole in Group:ext-attributedProvider
PractitionerRole	PractitionerRole, where PractitionerRole in Group:ext-attributedProvider
Location	Location, where Location in PractitioinerRole:location
Organization	Organization, where Organization in Group:managing-entity Organization, where Organization in Group:ext-attributedProvider Organization, where Organization in Coverage:policy-holder Organization, where Organization in Coverage:payor Organization, where Organization in PractitionerRole:organization, and PractitionerRole in Group:ext-attributedProvider
Coverage	Coverage, where Coverage in Group:ext-coverageReference
Related Person	Related Person, where Related Person in Coverage:policy-holder, and Coverage in Group:ext-coverageReference Related Person, where Related Person in Coverage:subscriber, and Coverage in Group:ext-coverageReference Related Person, where Related Person in Coverage:payor, and Coverage in Group:ext-coverageReference

Bulk Data Poll Request

In addition to exporting bulk data, you can also poll the Content Location received as part of Member Attribution List export request. Polling is required to determine completion status of the export request and retrieve a FHIR structure that specifies one or more URLs containing the exported data.

Download the Results

A consumer organization can also retrieve each of the files that represent the Member Attribution List.

Asynchronous Requests

All interactions defined in a RESTful API are described as synchronous operations — that is, the client makes a query and waits for the server to respond. This is not sufficient once significant server side processing becomes necessary or when substantial amounts of data must be returned. As a result, asynchronous operations are required.

The asynchronous request pattern is applicable for all the defined interactions and for operations, though servers can choose which interactions the pattern should be supported and may choose to support only some operations.

Kick-off Request

The Kick-off Request is an asynchronous requests with status polling. It includes the URL and parameters that would apply to a normal request but must also include specific header information.

The following URLs apply to the Kick-off Request:

https://api.in.opalahealth.io:45000/Patient/$export	FHIR Operation for all data on all patients (all data in the patient “compartment”).
https://api.in.opalahealth.io:45000/Group/[group id]/$export	FHIR Operation for all data on a group of patients (eg., research cohort, plan members).
https://api.in.opalahealth.io:45000/$export	FHIR Operation for all data on the server.

Response Header

Bulk Data Delete Request

After a bulk data request has been kicked-off, you can send a delete request to the URL provided in the Content-Location header to cancel the request.

Bulk Data Status Request

After a bulk data request has been kicked-off, you can poll the URL provided in the Content-Location header to obtain the status of the request.

Response Header

File Requests

You can download the generated bulk data files (one or more per resource type) using the URLs supplied in the completed status request body.

For More Information

• Bulk Data Access IG
• Member Attribution List Export Request (4.2.2)
• Poll the Content Location for Request Completion (4.2.3)
• FHIR Request (4.2.4)
• Bulk Data Export
• Asynchronous Request Pattern (3.1.6)
• Kick-off Request (3.1.6.2)
• Bulk Data Delete Request (3.1.6.3)
• Bulk Data Status Request (3.1.6.4)
• File Requests (3.1.6.5)