Performing a Bulk FHIR Export from a REST Client
When the Bulk FHIR Coordinator requests a set of FHIR resources from a FHIR endpoint on behalf of a client it is called an export.
This section describes how to:
In some cases—for example, if a proxy server is employed—the public-facing URL to which a REST client directs its Bulk FHIR requests may differ from the URL at which the BFC is hosted.
In such cases, the BFC’s rest handler determines the client-visible base URL from the content of a request object’s FORWARDED or X-FORWARDED HTTP headers. This logic is implemented by the GetBaseURL()Opens in a new tab class method of the HS.FHIRServer.Util.BaseURLOpens in a new tab class. The BFC constructs download links for exports using the GetURLforLink()Opens in a new tab class method of the HS.BulkFHIR.Util.BaseURLOpens in a new tab class. This method assumes that download links can use the same client-visible base URL as the URL at which status and $export requests are received.
If you must construct client-visible URLs according to different logic in either of these contexts, define a custom GetBaseURL() or GetURLforLink() class method in the HS.Local.BulkFHIR.Util.BaseURLOpens in a new tab class. Methods defined in this class will override the originals.
Initiating an Export Request from a REST Client
To initiate a bulk FHIR export from a REST client, send a GET or POST request to your BFC endpoint indicating the desired operation, for example:
-
System — [GET|POST] https://bfcEndpoint/$export
-
Patient — [GET|POST] https://bfcEndpoint/Patient/$export
-
Group — [GET|POST] https://bfcEndpoint/Group/groupID/$export
Typically, you would use GET for simpler requests, where it is reasonable to include all desired parameters in the query URL.
For more complex queries in which the parameters would be too cumbersome or impossible to enter in the URL, you can use POST and include some or all of the parameters in the JSON body. Parameters in the URL will supersede conflicting parameters in the json body.
If you include an Accept header, set it to application/fhir+json. If you do not include this header, the default is application/fhir+json.
If this BFC configuration uses the OAuth Auth Adapter, obtain an access token by specifying:
-
The OAuth server’s access token endpoint:
issuerEndpoint/tokenand audience if required:
?aud=https://bfcEndpoint -
The client id and client secret for one of the OAuth Clients listed on the Bulk FHIR Coordinator OAuth Configuration tile in your BFC configuration.
-
A grant type that is supported by the OAuth client. (In InterSystems IRIS, this would be one of the Required Grant Types selected on the General tab of your OAuth client configuration.)
-
A scope, where the minimum required scope is system/Patient.read. A scope of system/*.read allows everything.
An example patient export using OAuth is shown below:
The following optional parameters are supported with $export:
The BFC exports Newline Delimited JSON (ndjson) files.
The value application/fhir+ndjson and the abbreviated values application/ndjson and ndjson are accepted.
Resources will be included in the response if their state has changed after the indicated time in “FHIR Instant” format:
YYYY-MM-DDThh:mm:ss.sss+zz:zz
Comma-delimited list of FHIR resource types to include in the export. Defaults to all resource types supported by the fetch adapter as configured in your BFC configuration.
Checking the Status of an Export from a REST Client
The response header to your initial GET request will include a CONTENT-LOCATION key that indicates a URL of the form:
bfcEndpoint/status/sessionNumber
Periodically send GET requests to the CONTENT-LOCATION URL to obtain the status of your bulk FHIR export session.
The following status responses may be returned:
-
The BFC is processing the export.
-
The response header will include an X-PROGESS key with the value in-progress.
-
The export is complete, and files are ready for download.
-
The response header will include an EXPIRES key indicating how long the ndjson files will be kept on the BFC file server.
-
The response body will contain file URLs for ndjson files stored on the BFC file server. For each resource type returned, there will be one or more files:
-
The export you are trying to work with does not exist in the server. This could happen, for example, if you try to delete an export that has already been deleted.
-
An error occurred on the BFC.
Downloading the ndjson for a Completed Export
Once you receive a Status: 200 OK in the response header, your files are ready to download from the BFC file server. To retrieve the files, send a GET request to each file URL.
When using the FHIR Repository storage adapter, users do not need to manually download the ndjson exports. All successfully exported resources will be stored within the chosen FHIR server. If integrity checking is in use, resources that failed direct ingestion to the FHIR repository are stored in the directory configured in the Failed Files Directory field. Users can download the failed exports from that directory.
If this BFC configuration uses the OAuth Auth Adapter, obtain a new access token by specifying:
-
The Grant Type identified on the Fetch tab of your BFC configuration.
-
The OAuth server’s access token endpoint:
issuerEndpoint/tokenand audience if required:
?aud=https://bfcFileEndpoint -
The client id and client secret for one of the OAuth Clients listed on the Bulk FHIR Coordinator OAuth Configuration tile in your BFC configuration.
-
A scope, typically user/*.read for file download.
An example is shown below:
Cancelling an Export
To cancel an export that is in progress, send a DELETE request to the CONTENT-LOCATION URL. The BFC will return an HTTP status code of “202 Accepted” if the delete is successful. Other status codes indicate an error.
You can also delete a completed export. Doing so cleans up stored ndjson files and marks the export as deleted.
In both cases, the export is still noted in the log, as is its cancellation. If you make a status inquiry about the export, the response will indicate that it existed but was deleted or canceled.
Attempting to delete an export that has already been deleted will result in a 404 error, and the OperationOutcome resource in the content body will indicate deletion.
