Overview

interopiO supports version 1.0 of of the bulk export spec as described here FHIR Bulk Data Access (Flat FHIR)  .

 

 

Authorization:

Bulk Export requires SMART Backend Services Authorization. interopiO supports an out of band registration of the bulk client app with our authorization server. 

Registration of an app requires a client ID, a JWKS URL for the public key, scopes and the token signature signing algorithm (either RS384 ). After an app is registered, the app can make a call against the authorization server with a signed JWT and it gets a token which can then be used to kick off the bulk export process.

Bulk Export Process:

We have currently implemented bulk export for a Group resource that contains a list of Patients.

The export process is started by issuing an HTTP GET request for /Group/{Group Id}/$export against a gateway. An HTTP status of 202 Accepted is returned along with a Content-Location header that contains a polling location URL.

The bulk export process is started as a background process and begins with retrieving the Group resource that contains a list of Patients. Each Patient in the Group is retrieved along with its associated USCDI resources and saved into NDJSON files. Each resource type will be in a separate NDJSON file and the number of resources in a file is limited to 100. So there could be multiple files for a single resource type.

A polling location URL can be sent an HTTP GET request to query the status of the bulk export process. A 202 Accepted status will be returned while the bulk export is still running. The polling location URL will return an X-Progress header containing a count of the Patient resources being processed. When the export is finished, a 200 OK status will be returned along with an array containing the resource type and URL from which the exported file can be downloaded in NDJSON format.

Bulk Export API:

Pre-Register with interopiO Authorization server

This is an offline process where the bulk export client is pre-registered with the auth server. The public key for the client and scope (a string containing allowed operations) are given to the auth server as part of pre-registration and a client id is generated.  

Group Bulk Export Authorization Request

General Information

Method: HTTP POST

Endpoint: https://interopio.com/av2/oauth2/token

Parameters: these are to be sent as a string in the request body

client_assertion: a JWT signed using the client's private key and containing the following payload

{
"iss": "<client id assigned to bulk export client as part of pre-registration>",
"sub": "<client id assigned to bulk export client as part of pre-registration>",
"aud": "https://interopio.com/av2/oauth2/token",
"exp": <expiration time>,
"jti": "<jwt id as a random string>"
}

client_assertion_type: The following static value

urn:ietf:params:oauth:client-assertion-type:jwt-bearer

grant_type: The following static value

client_credentials

scope: The scope agreed with the auth server as part of pre-registration

Here is a sample parameter string with line breaks added for clarity

client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzM4NCIsImtpZCI6ImI0MTUyOGI2ZjM3YTk1MDBlZGI4YTkwNWE1OTViZGQ3In0.eyJpc3MiOiI5NjQxN2M1ZS01NjVjLTQ2MGUtYmZiYy0yM2JhZTIwMDY0ODkiLCJzdWIiOiI5NjQxN2M1ZS01NjVjLTQ2MGUtYmZiYy0yM2JhZTIwMDY0ODkiLCJhdWQiOiJodHRwczovL2ludGVyb3Bpby1kZXYuY29tL2F2Mi9vYXV0aDIvdG9rZW4iLCJleHAiOjE2NjYxMDk4OTYsImp0aSI6IjM1NmMyZWI4NjEzMzI0NmZhZTc2NDViZmZjNTZjNGIwNGIwN2UyODZjZmRiMTdiM2Q4NzNkMmM3ZjU0ZDM0MDcifQ.fiZQl2RrLWzjH5rSFvDnAYSJX1dNFbBk4oGWSmvGU-eXSjnsVTw7J0f2MWMetZeuWRTsH0OHrRF99tzSehq3eH3Z7S3AHCLO4f9r6HDVrKelfpIpf9hbVYgEOhP77DiCWeikL_-UPB9q_6JVZK9_mHNfGbJXvqn-opgzOnDerLifHTc9Ef8-3tx_qaX4pfx7UGDH4zuKFWVm4KyzriNADlnQ8UG9TV8wmPyp153-FRX83_900ONIEwI4pl9mPnrt3GcIZejE88_cJ35jM-Ckczb_zSJkI2LpPqtpACbsuRksUF06QleL0cMBkPTFSg3LeEKzIxNDxWUBOeZxRVyByA
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&grant_type=client_credentials
&scope=system%2F%2A.read

Supported Web Service Type: REST

Authorization: client_assertion parameter

Description

The bulk export client will call the token endpoint and obtain a JWT token that will be used in the kick-off process. 

Request

Request Headers

content-type: application/x-www-form-urlencoded

accept: application/json

Authorization: signed JWT sent as a parameter in HTTP POST request body

Response

Response Status

HTTP status code 200 OK if the request is valid

Response Body

A sample response is shown below

{

  "access_token": "<jwt access token>",
  "scope": "system/*.read",
  "token_type": "Bearer",
  "expires_in": 599
}

Group Bulk Export Kickoff

General Information

Method: HTTP GET

Endpoint: <FHIR Server URL>/Group/{GroupId}/$export

Supported Web Service Type: REST

Authorization: jwt (signed jwt from the authorization request)

Description

The bulk export kickoff requests starts the group bulk export process and returns a polling location URL that can be used for tracking the status of the bulk export process while it is running and for getting the URLs for the resources that can be downloaded, after the process is complete.

Request

Request Headers

Prefer: respond-async

Accept: application/fhir+json 

Authorization: Bearer JWT

Response

Response Status

HTTP status code 202 Accepted if the request is accepted

HTTP status code 500 Internal Server Error if a bulk export other than a group export is specified

Response Headers

content-location: <FHIR Server URL>/$export-poll-status?_jobId=<jobId>

Response Body

A response body is returned if there is a kickoff error or when an unsupported bulk export is attempted to be kicked off. 

{
"timestamp": "2022-10-14T22:47:58.691+0000",
"status": 500,
"error": "Internal Server Error",
"message": "Only group export is currently supported using /Group/{GroupId}/$export",
"path": "/gateway/fhir/test/ontada/ikm21stcenturycure/$export"
}

Bulk Export Status

General Information

Method: HTTP GET

Endpoint: contained in the content-location header in the Bulk Export Kickoff response

Supported Web Service Type: REST

Authorization: jwt (signed jwt from the authorization request)

Description

The bulk export status endpoint can be called for checking the status of the bulk export process.

Request

Request Headers

Accept: application/json 

Authorization: Bearer JWT

Response

Response Status

HTTP status code 202 Accepted for a bulk export process that is in progress

HTTP status code 200 OK for a bulk export process that has completed

HTTP status code 404 Not Found if the _jobId parameter in the request is not found. This can happen if the content-location URL is old or if the request has already been cancelled

HTTP status code 500 Internal Server Error for a bulk export process that failed to process

Response Headers

The x-progress and retry-after headers are only returned in the case of a request that is still in progress. The former tells you how many patient ids have been included for processing and the latter tells you how many seconds to wait before sending another status request.

x-progress: <n> ids have started processing

retry-after: <n>

The content-type header is sent for a bulk export process that has finished.

content-type: application/json;charset=UTF-8 

Response Body

No response body is sent when the HTTP response status is 202. When the HTTP status is 200, the response body has the following format.

{
  "transactionTime": "2022-10-14 16:02:52:532 +0000",
  "request": "https://interopio-dev.com/gateway/fhir/test/ontada/ikm21stcenturycure/Group/testgroup1014/$export",
  "requiresAccessToken": true,
  "output": [
    {
      "type": "Patient",
      "url": "https://interopio-dev.com/gateway/fhir/test/ontada/ikm21stcenturycure/bulk/Group/c5082a22-0e03-4218-92c3-330bdd690e50"
    },
    {
      "type": "Condition",
      "url": "https://interopio-dev.com/gateway/fhir/test/ontada/ikm21stcenturycure/bulk/Condition/da46d4f6-0e3c-46a7-8954-2dffea5b6155"
    },
    {
      "type": "DiagnosticReport",
      "url": "https://interopio-dev.com/gateway/fhir/test/ontada/ikm21stcenturycure/bulk/DiagnosticReport/8e84f9de-0fa9-4bca-bec7-ae50d0d41175"
    },
    {
      "type": "Location",
      "url": "https://interopio-dev.com/gateway/fhir/test/ontada/ikm21stcenturycure/bulk/Location/bfea2b97-0cad-49e2-9b83-529ea95a7d88"
    },
    {
      "type": "Observation",
      "url": "https://interopio-dev.com/gateway/fhir/test/ontada/ikm21stcenturycure/bulk/Observation/92f6482c-52a3-40e2-bd45-f49d262a085f"
    },
    {
      "type": "Provenance",
      "url": "https://interopio-dev.com/gateway/fhir/test/ontada/ikm21stcenturycure/bulk/Provenance/e96db5a5-a443-4712-bb14-7011f9e731fe"
    }
  ],
  "error": [
    {
      "type": "OperationOutcome",
      "url": "https://interopio-dev.com/gateway/fhir/test/ontada/ikm21stcenturycure/bulk/OperationOutcome/fa621fad-0126-4f78-93fc-3cf20fb11a66"
    }
  ]
}