$export
FHIR Bulk Data Export
The FHIR Bulk Data Export feature allows to export FHIR resources in ndjson format.
Aidbox supports patient-level and group-level export. When the export request is submitted the server returns URL to check the export status. When export is finished, status endpoint returns URLs to download resources.
Only one export process can be run at the same time. If you try to submit an export request while there is active export, you get 429 Too Many Requests error.

Setup storage

Aidbox can export data to GCP or AWS cloud. Export results will be in <datetime>_<uuid> folder on the bucket.

GCP

​Create bucket and service account that has read and write access to the bucket.
​Create GcpServiceAccount resource in Aidbox. Example:
1
private-key: |
2
-----BEGIN PRIVATE KEY-----
3
your-key-here
4
-----END PRIVATE KEY-----
5
service-account-email: service-[email protected]
6
id: gcp-service-account
7
resourceType: GcpServiceAccount
Copied!
Set the following environment variables:
  • box_bulk__storage_backend=gcp β€” backend for export
  • box_bulk__storage_gcp_service__account β€” id of the GcpServiceAccount resource
  • box_bulk__storage_gcp_bucket β€” bucket name

AWS

Create S3 bucket and IAM user that has read and write access to the bucket.
​Create AwsAccount resource in Aidbox. Example:
1
region: us-east-1
2
access-key-id: your-key-id
3
secret-access-key: key
4
id: aws-account
5
resourceType: AwsAccount
Copied!
Set the following environment variables:
  • box_bulk__storage_backend=aws β€” backend for export
  • box_bulk__storage_aws_account β€” id of the AwsAccount resource
  • box_bulk__storage_aws_bucket β€” bucket name

Parameters

Parameter
Description
_outputFormat
Specifies format in which the server generates files. Only application/fhir+ndjson is supported.
_type
Includes only the specified types. This list is comma-separated.
_since
Includes only resources changed after the specified time.
patient
Export data that belongs only to listed patient. Format: comma-separated list of patient ids. Available only for patient-level export.

Patient-level export

Patient-level export exports all Patient resources and resources associated with them. This association is defined by FHIR Compartments.
To start export make a request to /fhir/Patient/$export:
Request
Response

Rest console

1
GET /fhir/Patient/$export
2
Accept: application/fhir+json
3
Prefer: respond-async
Copied!

Status

202 Accepted

Headers

  • Content-Location β€” Link to check export status (e.g. /fhir/$export-status/<id>)
Make a request to the export status endpoint to check the status:
Request
Response (completed)

Rest console

1
GET /fhir/$export-status/<id>
Copied!

Status

200 OK

Body

1
{
2
"status": "completed",
3
"transactionTime": "2021-12-08T08:28:06.489Z",
4
"requiresAccessToken": false,
5
"output": [
6
{
7
"type": "Patient",
8
"url": "https://storage/some-url",
9
"count": 2
10
},
11
{
12
"type": "Person",
13
"url": "https://storage/some-other-url",
14
"count": 1
15
}
16
]
17
}
Copied!
Delete request on the export status endpoint cancels export.
Request
Response

Rest console

1
DELETE /fhir/$export-status/<id>
Copied!

Status

202 Accepted

Group-level export

Group-level export exports all Patient resources that belong to the specified group and resources associated with them. Characteristics of the group are not exported. This association is defined by FHIR Compartments.
To start export make a request to /fhir/Group/<group-id>/$export:
Request
Response

Rest console

1
GET /fhir/Group/<group-id>/$export
2
Accept: application/fhir+json
3
Prefer: respond-async
Copied!

Status

202 Accepted

Headers

  • Content-Location β€” Link to check export status (e.g. /fhir/$export-status/<id>)
Make a request to the export status endpoint to check the status:
Request
Response (completed)

Rest console

1
GET /fhir/$export-status/<id>
Copied!

Status

200 OK

Body

1
{
2
"status": "completed",
3
"transactionTime": "2021-12-08T08:28:06.489Z",
4
"requiresAccessToken": false,
5
"output": [
6
{
7
"type": "Patient",
8
"url": "https://storage/some-url",
9
"count": 2
10
},
11
{
12
"type": "Person",
13
"url": "https://storage/some-other-url",
14
"count": 1
15
}
16
]
17
}
Copied!
Delete request on the export status endpoint cancels export.
Request
Response

Rest console

1
DELETE /fhir/$export-status/<id>
Copied!

Status

202 Accepted

System-level export

Export data from a FHIR server, whether or not it is associated with a patient. This supports use cases like backing up a server, or exporting terminology data by restricting the resources returned using the _type parameter.
Request
Response(completed)
1
GET /fhir/$export
2
Accept: application/fhir+json
3
Prefer: respond-async
Copied!

Status

200 OK

Body

1
{
2
"status": "completed",
3
"transactionTime": "2021-12-08T08:28:06.489Z",
4
"requiresAccessToken": false,
5
"output": [
6
{
7
"type": "Patient",
8
"url": "https://storage/some-url",
9
"count": 2
10
},
11
{
12
"type": "Person",
13
"url": "https://storage/some-other-url",
14
"count": 1
15
}
16
]
17
}
Copied!
Delete request on the export status endpoint cancels export.
Request
Response

Rest console

1
DELETE /fhir/$export-status/<id>
Copied!

Status

202 Accepted
Last modified 2mo ago