Bulk Data

The Allscripts FHIR API is used to pass clinical data on a single patient or small group of patients. However, it is not technically feasible to use the usual Allscripts FHIR API requests to pass bulk data because of the number of requests and system resources involved. In these cases, bulk data requests are available.

There are a variety of reasons why external systems would request bulk data from an Allscripts product. A few examples include:

• Clinical studies based on conditions and treatment plans
• Population health studies
• Transfer of patient records from one clinical system to another

Note: For more information from HL7 on the FHIR specification for bulk data exports, see Export : /export/ (hl7.org).

Request and Data Flow

Unlike other Allscripts FHIR API requests, requesting bulk data is an asynchronous process; the Allscripts product does not immediately return information. The application makes the initial request and then waits for the Allscripts product to prepare the data.

The process of requesting and receiving bulk data flows as follows:

1. The application requests bulk data from an Allscripts product via FHIR.
   • FHIR returns the Export Request ID and the total number of resources. No actual data is included in the response.
2. The application requests the status of the bulk data request by sending the ExportRequestID.
   • If processing is not complete, FHIR returns status and progress (percentage complete).
   • If processing is complete, FHIR returns the URL for the location of the data file.
3. Application requests the data by sending a request to the URL.

Application Configuration Considerations in the ADP Portal

When the developer creates their FHIR application in the Allscripts Developer Program portal, the following must be true in order for the application to request bulk data:

• On the FHIR App page, the App Type must be set to System.
• Backend authentication for access tokens via JWKS must be configured.

Supported Resources

The Allscripts FHIR Bulk Data API can extract bulk data from the following FHIR resources:

• AllergyIntolerance
• CarePlan
• CareTeam
• Condition
• Binary
• Device
• DiagnosticReport
• DocumentReference
• Encounter
• Goal
• Group
• Immunization
• Location
• Medication
• MedicationRequest
• Observation
• Organization
• Patient
• Practitioner
• PractitionerRole
• Procedure
• Provenance
• RelatedPerson

Provenance considerations

The bulk data request supports the Provenance resource. The response file includes provenance data under the following conditions:

• Provenance is included by default for those requests that do not specify which resource to include.
  • [FHIR path]/Group/ABC/$export
  • Means: “Get all the information for the patients in group ABC.” Because a specific resource (such as the MedicationRequest or Condition resource is not included in the request, provenance data is included.
• Provenance is included when explicitly listed in the request for a specific resource.
  • [FHIR path]/MedicationRequest?code=&_revinclude=Provenance:target
  • Means: “Get”

If provenance is passed as a requested resource, all other resources that are included in the request should then include provenance.

If provenance is not passed as a requested resource, no resources that are included in the request should include provenance.

For more information on the Provenance resource, see link to Searching page.

Creating an export request

The application makes the initial bulk data request using $export. For example:

[FHIR path]/Group/INF-101/$export

Means: “Get all the patients in the Group resource with the ID INF-101.”

• The Allscripts FHIR API responds with the following information:
  • Export Request ID
  • Content Location URL

Note: The requesting application must be authorized to access the data requested.

Requesting an export request status

The application requests a status of the export package progress.

GET [Content Location URL]

• The Allscripts FHIR API responds. If the package is still in progress, the response includes:
  • Status: Accepted.
  • X-Progress: Percentage complete.
  • Retry-After: Suggested duration of time until the next status request. This is measured in minutes.
• If the package is complete, the response includes:
  • Status: OK
  • Expires: Time when the export package will expire and thus will no longer be available.
  • Content-Type: JSON or XML.

  In the body of the response, a series of URLs are listed for individual packages for download depending on the size of the request. These URLs are included in the file request.

• If the export request has resulted in an error, the response includes:
  • Status: Error
  • OperationOutcome resource which includes the severity, code, and description of the error.

Deleting an export request

The application can delete an export request if it was created in error or is no longer needed.

DELETE [Content Location URL]

Retrieving the export file packages

After the application receives a status update that indication the requested export files are complete, the application retrieves the files.

GET [Content Location URL from the body of the completed request response]

By default, the Allscripts FHIR API returns files in the JSON format. However, to return files in XML, send application/fhir+xml in the Accept header.