DFT - The specification is currently in ballot review and subject to change. It is not ready for limited roll-out or production level use. For a full list of available versions, see the Directory of published versions

Bulk Export

Overview

FHIR queries work well when requesting smaller amounts of data, like requesting information for a single location, or a small set of practitioner. These queries do not work well when there is a large amount of information to be exchanged, like when a new vendor or clinic is connecting to an existing server.

For larger datasets a bulk query works better as they are designed to support sharing a large amount of information in smaller segments to better mitigate possible problem points like shorter timeouts.

This section covers general information that applies to both the requesting system (client) and the responding system (server). For detailed information related specifically to each user type you can go to the following sections in the iGuide.

Client Type	Details
Client / Consumer	Information specific for how to request and retrieve information from a Service Directory Server
Server / Supplier	Information for the host of the service directory for how to respond to a bulk query request from a client.

Related Specifications

To help the vendors who are developing to the CA:CSD specs maintain compatibility with other projects they may be working with the following existing specifications were used as a basis for the Bulk Export functionality contained with the CA:CSD guide.

Project	Version	Link
Bulk Data Access	STU2	https://hl7.org/fhir/uv/bulkdata/STU2
nd-json	FHIR R4	https://www.hl7.org/fhir/R4/nd-json.html
Async	FHIR R4	https://hl7.org/fhir/R4/async.html
SMART App Launch	STU 2.2	https://hl7.org/fhir/smart-app-launch/STU2.2/

Use Cases

Use Case	Description
Use Cases	Use Case 3: Bulk Export - Nightly Updates	An application that is designed to use local data throughout the day performs a nightly update to capture any changes since the previous update.

Operation

See Operation $export for more information on the $operation

Bulk Export Request

GET /$export?[params] – Prefer: respond-async

Sample Response

HTTP/1.1 202 Accepted Content-Location: https://jurisdiction.ca:9001/$export-poll-status?_jobId=12937-21371-12312

Status

Status: 202 Accepted Note: Status Include “In-progress”, “Error”, or “Complete”) X-Progress: “50% complete” Retry-After: 120

Parameters

Parameter	Type	Cardinality	Description
_outputFormat	string	0..1	The format of how the query results will be returned.
_since	instant	0..1	The date and time that will be comparted againt the Resource.meta.lastUpdated to determin if the resource will be included in the response. For resources where the server does not maintain a last updated time, the server MAY include these resources in a response irrespective of the _since value supplied by a client.
_type	string of comma delimited FHIR resource type	0..1	The resource types that will be included in the response.

Note: One of either the _since or _type must be included. If only the _since is included then all resource types will be included. If only the _type is included then all resources of the selected type will be included regardless of the lastUpdated date.

Output Format

The recommended output format is nd-json. This can be represented as either:

• a MIME Type of "application/fhir+ndjson"
• including an operation parameter of "-outputFormat" with a value of either "application/fhir+ndjson", "application/ndjson" or "ndjson"

Note: If neither the MIME type nor -outputFormat parameter are included the servers will default to using "application/fhir+ndjson".

When using nd-json, each file generated will only contain one resource type.

Expected Interaction

When using nd-json the asynchronous pattern must be used.

More information on the polling flow once a request has been made can be found at Bulk Data Status Request

Resource Bulk Interactions

Location w/ Distance: The CA:CSD framework can enable services to assess and track the distance between devices and relevant locations, allowing for better resource allocation and service provisioning based on proximity. Implementers MAY support bulk export of location data with distance-based filtering, allowing large volumes of data to be grouped and exported based on proximity to specified locations.

Location Jurisdiction: CA:CSD MAY support and include the ability to filter data by location jurisdiction, ensuring that data exports adhere to local, state, or regional legal requirements for data handling and privacy.

Organization Jurisdiction: CA:CSD MAY support and include the ability to filter data by organization jurisdiction, ensuring that data exports adhere to organizational requirements for data handling and privacy.

Location Facility: The system MAY support bulk export of data tied to specific healthcare facility location.

Organization Facility: The system MAY support bulk export of data tied to specific healthcare organizational facilities (i.e., clinics and hospitals), facilitating large-scale data transfers and analysis by facility type or designation.

Security and Authorization

Although this guide does not require the use of any specific authentication or security protocols it does highly recommend the use of OAuth 2.0 access management as documented in:

System	Details
Backend Server	SMART App Lauch - Backend Services
Client	SMART App Launch - Client