Group Export REST Endpoints
Description
The Bulk Data Application Programming Interface (API) in Health Level Seven (HL7) Fast Healthcare Interoperability Resources (FHIR) provides a compatible FHIR system application access to potentially large volumes of information on a group of patients.
The traditional, interactive FHIR API is excellent for retrieving small amounts of data in near real time. The use cases mentioned above may require many thousands of such queries to be satisfied, which is not practical. The FHIR Bulk Data Access API was designed to address these scenarios.
Summary
Client applications that interact with the Soarian Clinicals Bulk Data API operate under the system persona, implying that no human is assumed to be directly interacting with it. The API secures the client application using Transport Layer Security (TLS) 1.2 and OAuth 2.
The client application must be registered with Cerner and enabled for the healthcare organization, as well as capable of maintaining a client secret to ensure its authenticity. For more information, see the Authorization Framework Developer's Guide.
The client application requests bulk data from Soarian Clinicals by issuing an HTTP GET request, specifying the $export operation, to one of two endpoints:
GET [fhir base]/Patient/$export: Retrieve bulk data for all patients in the system.GET [fhir base]/Group/[id]/$export: Retrieve bulk data for a predefined group of patients.
In response, Soarian Clinicals acknowledges the request in near real time. The acknowledgment of a successful request includes a Content-Location header that contains the absolute URL of an endpoint for status requests.
After the export request has been accepted, Soarian Clinicals begins to generate one or more files in NDJSON format that contain the bulk data matching the request. The time that this process takes ranges from very short to very long, depending upon the amount of data that qualifies for inclusion based on the request.
Once it has received the initial acknowledgement, the client application may poll Soarian Clinicals for the status of the file build using the polling location URL provided in the Content-Location header:
GET [polling content location]to retrieve the status of the bulk data request
Soarian Clinicals then returns one of the following responses:
202 Accepted: The export operation is in progress.200 OK: The export operation is complete.
The body of the 200 OK status response contains links to the NDJSON formatted files that contain the requested bulk data. The client application can download these files.
At any time after the initial bulk data request has been acknowledged, the client application can request that it be deleted:
DELETE [polling content location]: Delete content generated by the request.
If the above DELETE request is sent before the bulk request has completed, the in-flight request is canceled, and any associated content is marked for deletion from the server.
Oracle Cerner recommends that client applications always explicitly delete requests after they have finished downloading bulk data. Healthcare organizations have the option of configuring their systems to reject what seem to be duplicate requests. Deleting a request ensures that a subsequent request with the same parameters is not rejected as a duplicate.
Registering Client Applications
Before a client application can interact with the Soarian Clinicals Bulk API, it must obtain an asymmetric key pair and register its public key set with Cerner. Once a client application is registered, the Soarian Clinicals Bulk API treats it as preauthorized. This enables the client application to obtain access tokens at runtime after authenticating itself. See Authorization for details on registering client applications and obtaining access tokens.
Note:
The examples provided here are nonnormative, and replaying them in the public sandbox is not guaranteed to yield the results shown on the site.- Delete bulk data
- Method: getPath:
/Export/DeleteRequest - Get a list of output files
- Method: getPath:
/Export/FileRequest - Get bulk data for patients
- Method: getPath:
/Export/KickoffRequest - Get bulk data request status
- Method: getPath:
/Export/StatusRequest