Bulk Data Export | MedicaSoft Technical Documentation

Overview

The Bulk Data Export is intended to provide an external system with means to export large amounts of clinical data from the NXT FHIR API. Due to the large volume of data expected, the interface is asynchronous. The NXT API Bulkk Data Export implements the STU 1.0.1 specifications.

Warning: It is important to take into account the performance implications of exporting a very large dataset, so please try to restrain the exported data to the minimum necessary to fulfill the use-case.

Pre-requisites

The external client application has to be authorized in advance to use the bulk data export API and to obtain an access token having the system/*.read scope set.

Workflow

The NXT API supports only the Group export operation at this time.

The Bulk export workflow is as follows:

Client initiates a bulk export request for a group of patients:

GET /Group/:id/$export

Headers

The Accept header is required and should be valued to application/fhir+json

Parameters

Name	Cardinality	type	Description
_outputFormat	0..1	string	only `application/fhir+ndjson` is supported
_since	0..1	instant	Resources updated after this period will be included in the response.
_type	0..1	string	A string of comma-delimited FHIR resource types.

Response

If the operation is successful the server responds with the following headers set:

HTTP status code = 202 Accepted
Content-Location set to the absolute URL of the request status endpoint

Errors

Code	Description
400	Invalid parameters
401	Missing or invalid Authorization header
403	Invalid credentials
404	Group resource not found

Example

Request

GET https://r4cert.medicasoft.us/api/fhir/Group/453/$export

Response

202 Accepted

Content-Type: application/fhir+json
Content-Location: https://r4cert.medicasoft.us/api/fhir/Export/52c794e7-b198-4fc6-93f7-3ea04aef4a5f

Client polls the request status endpoint

The client application should check the status by polling the URL previously returned in the Content-Location header

GET /<content_location_url>

Response

Response Type	Description
In-Progress	The HTTP status code is set to `202 Accepted`
Error	The HTTP status code is set to `500 internal server error` and the body contains an OperationOutcome
Complete	The HTTP status code is set to `200 OK` and the body is set as described below

Complete Response Payload

Field Name	type	Cardiinality	Description
transactionTime	instant	1..1	Set to the time when the export has completed
request	uri	1..1	Original request URL
output		0..*	Array of resource `type` / file location `url` pairs
output.type	string	1..1	Resource type
output.url	uri	1..1	ndjson file location URL
error		0..*	Array of errors occured during export
error.type	string	1..1	Always `OperationOutcome`
error.url	uri	1..1	ndjson file location URL

Example

{
    "transactionTime": "2022-10-14T18:35:05.676Z",
    "request": "https://r4cert.medicasoft.us/fhir/Group/453/$export",
    "requiresAccessToken": true,
    "output": [
    {
        "type": "Patient",
        "url": "https://r4cert.medicasoft.us/api/fhir/Binary/export/52c794e7-b198-4fc6-93f7-3ea04aef4a5f/Patient-123.ndjson"
    },
    {
        "type": "Encounter",
        "url": "https://r4cert.medicasoft.us/api/fhir/Binary/export/52c794e7-b198-4fc6-93f7-3ea04aef4a5f/Encounter-123.ndjson"
    },
    {
        "type": "Procedure",
        "url": "https://r4cert.medicasoft.us/api/fhir/Binary/export/52c794e7-b198-4fc6-93f7-3ea04aef4a5f/Procedure-123.ndjson"
    },
    {
        "type": "CarePlan",
        "url": "https://r4cert.medicasoft.us/api/fhir/Binary/export/52c794e7-b198-4fc6-93f7-3ea04aef4a5f/CarePlan-123.ndjson"
    },
    {
        "type": "Immunization",
        "url": "https://r4cert.medicasoft.us/api/fhir/Binary/export/52c794e7-b198-4fc6-93f7-3ea04aef4a5f/Immunization-123.ndjson"
    },
    {
        "type": "Goal",
        "url": "https://r4cert.medicasoft.us/api/fhir/Binary/export/52c794e7-b198-4fc6-93f7-3ea04aef4a5f/Goal-123.ndjson"
    },
    {
        "type": "Observation",
        "url": "https://r4cert.medicasoft.us/api/fhir/Binary/export/52c794e7-b198-4fc6-93f7-3ea04aef4a5f/Observation-123.ndjson"
    },
    {
        "type": "DocumentReference",
        "url": "https://r4cert.medicasoft.us/api/fhir/Binary/export/52c794e7-b198-4fc6-93f7-3ea04aef4a5f/DocumentReference-123.ndjson"
    },
    {
        "type": "DiagnosticReport",
        "url": "https://r4cert.medicasoft.us/api/fhir/Binary/export/52c794e7-b198-4fc6-93f7-3ea04aef4a5f/DiagnosticReport-123.ndjson"
    },
    {
        "type": "Condition",
        "url": "https://r4cert.medicasoft.us/api/fhir/Binary/export/52c794e7-b198-4fc6-93f7-3ea04aef4a5f/Condition-123.ndjson"
    },
    {
        "type": "MedicationRequest",
        "url": "https://r4cert.medicasoft.us/api/fhir/Binary/export/52c794e7-b198-4fc6-93f7-3ea04aef4a5f/MedicationRequest-123.ndjson"
    },
    {
        "type": "AllergyIntolerance",
        "url": "https://r4cert.medicasoft.us/api/fhir/Binary/export/52c794e7-b198-4fc6-93f7-3ea04aef4a5f/AllergyIntolerance-123.ndjson"
    },
    {
        "type": "CareTeam",
        "url": "https://r4cert.medicasoft.us/api/fhir/Binary/export/52c794e7-b198-4fc6-93f7-3ea04aef4a5f/CareTeam-123.ndjson"
    },
    {
        "type": "Device",
        "url": "https://r4cert.medicasoft.us/api/fhir/Binary/export/52c794e7-b198-4fc6-93f7-3ea04aef4a5f/Device-123.ndjson"
    },
    {
        "type": "Provenance",
        "url": "https://r4cert.medicasoft.us/api/fhir/Binary/export/52c794e7-b198-4fc6-93f7-3ea04aef4a5f/Provenance-123.ndjson"
    },
    {
        "type": "Practitioner",
        "url": "https://r4cert.medicasoft.us/api/fhir/Binary/export/52c794e7-b198-4fc6-93f7-3ea04aef4a5f/Practitioner-123.ndjson"
    },
    {
        "type": "Organization",
        "url": "https://r4cert.medicasoft.us/api/fhir/Binary/export/52c794e7-b198-4fc6-93f7-3ea04aef4a5f/Organization-123.ndjson"
    },
    {
        "type": "Location",
        "url": "https://r4cert.medicasoft.us/api/fhir/Binary/export/52c794e7-b198-4fc6-93f7-3ea04aef4a5f/Location-123.ndjson"
    }],
    "error": []
}

Client retrieves the exported data

The client application ca retrieve the exported data by following the URL links returned in the output field

Example
```
GET https://r4cert.medicasoft.us/api/fhir/Binary/export/52c794e7-b198-4fc6-93f7-3ea04aef4a5f/Organization-123.ndjson
```
Client removes the bulk data export request

The client application may remove the request at any time by performing a DELETE on the URL returned on step 1 in the Content-Location header.

Example

Request
```
DELETE https://r4cert.medicasoft.us/api/fhir/Export/d7b38380-4de7-4322-979d-c679edc4bdee
```
Response
```
202 Accepted
```