☰
The Veradigm and Altera FHIR API is used to work with clinical data for a single patient or small group of patients. However, it is not technically feasible to use the usual Veradigm and Altera FHIR API requests to pass bulk data because of the number of requests and system resources involved. To support these cases, bulk data requests are available.
There are a variety of reasons why external systems would request bulk data from a Veradigm or Altera product. A few examples include:
Only FHIR applications of the type System can send bulk data requests. Patient and User application types cannot send bulk data requests.
Note: For more information from HL7 on the FHIR specification for bulk data exports, see HL7's Bulk Data content.
When the developer creates their FHIR application in the Veradigm Connect Portal, the following must be true in order for the application to request bulk data:
The Veradigm and Altera FHIR Bulk Data API can extract bulk data from the following FHIR resources:
Unlike other Veradigm and Altera FHIR API requests, requesting bulk data is an asynchronous process; the Veradigm or Altera product does not immediately return information. The application makes the initial request and then waits for the Veradigm or Altera product to prepare the data.
For a detailed diagram, see here.
Before an application can request bulk data, they must know the ID of the Group resource they are requesting. Group resources are created by organizations in the individual Veradigm and Altera EHRs, and each EHR has a different method for creating Group resources. For example, Altera TouchWorks EHR uses the Patient List function to create Group resources, and Veradigm EHR uses segments in the Reporting module to create Group resources. For more information, see the individual EHR documentation. To obtain a specific Group resource ID, you can query the Group resource.
The process of requesting and receiving bulk data flows as follows:
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 Veradigm and Altera FHIR API responds with the Content Location URL.
Note: The requesting application must be authorized to access the data requested.
The application requests a status of the export package progress.
GET [Content Location URL]
The Veradigm and Altera FHIR API responds. If the package is still in progress, the response includes:
If the package is complete, the response includes:
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:
An export request can complete successfully when some of the data was successfully outputted but some was not. For example:
{
“transactionTime”: “[instant]”,
“request” : “[base]/Patient/$export?_type=Patient,Observation,Provenance”,
“requiresAccessToken” : true,
“output” : [{
“type” : “Patient”,
“url” : http://serverpath2/patient_file_1.ndjson
},{
“type” : “Patient”,
“url” : http://serverpath2/patient_file_2.ndjson
},{
“type” : “Observation”,
“url” : http://serverpath2/observation_file_1.ndjson
}],{
“type” : “Provenance”,
“url” : http://serverpath2/provenance_file_1.ndjson
}],{
“type” : “Provenance”,
“url” : http://serverpath2/provenance_file_2.ndjson
}],
“error” : [{
“type” : “OperationOutcome”,
“url” : http://serverpath2/err_file_1.ndjson
}],
“extension”:{}
}
The application can delete an export request if it was created in error or is no longer needed.
DELETE [Content Location URL]
After the application receives a status update that indicates the requested export files are complete, the application retrieves the files.
GET [Content Location URL from the body of the completed request response]
You can download the file packages as many times as necessary, but once they expire, they are no longer available.
To test bulk data requests, refer to the Testing section of the Process Overview page.
The bulk data request supports the Provenance resource. The response file includes provenance data under the following conditions:
[FHIR path]/Group/ABC/$exportFor more information on the Provenance resource, see the Searching page.
