Provincial Health and Service Directory (PHSD) HL7 FHIR® Implementation Guide

Operation: Bulk Export

FHIR Resources from the Provincial Health and Services Directory (PHSD) can be accessed through three separate channels: direct API, subscriptions and bulk export. The PHSD Bulk Export API will follow guidance defined in the HL7 FHIR Bulk Data Implementation Guide -- specifically, the FHIR Bulk Data System Level Export API.

Bulk Export allows implementers to retrieve all resource instances of a given type from the Ontario PHSD, using date-based and content-based filters and criteria -- for example, "retrieve all HealthcareService resources that have been updated since 2024-01-07, from the Healthline Service catalogue, under service category of Indigenous Communities".

The Ontario PHSD Bulk Export currently supports retrieval of the following resources:

HealthcareService
Organization
Location
Practitioner
PractitionerRole
Questionnaire

Response Format

The response to the Ontario PHSD Bulk Export will be an HTTP response of Status Code 202 Accepted, with Content-Location header with the URL of an endpoint to poll for status updates while the request is processed asynchronously.

After a Bulk Data request has been started, the client MAY poll the status URL provided in the Content-Location header.

The response from the status endpoint will be either HTTP 202 (in-progress), HTTP 500 (error), or HTTP 200 (complete).

The response body of a Complete status will follow the structure below:

 {
   "transactionTime": "2021-01-01T00:00:00Z",
   "request" : "[base]/$export?_type=HealthcareService&_typeFilter=HealthcareService%3Fprogram%3DTHLN,HealthcareService%3Fservice-category%3DM13",
   "requiresAccessToken" : true,
   "output" : [{
     "type" : "HealthcareService",
     "url" : "https://example.com/output/healthcareservice_file_1.ndjson"
   },{
     "type" : "HealthcareService",
     "url" : "https://example.com/output/healthcareservice_file_2.ndjson"
   },{
     "type" : "Location",
     "url" : "https://example.com/output/location_file_1.ndjson"
   },{
     "type" : "Organization",
     "url" : "https://example.com/output/organization_file_1.ndjson"
   },{
     "type" : "Questionnaire",
     "url" : "https://example.com/output/questionnaire_file_1.ndjson"
   }
   ],
   "deleted": [{
     "type" : "Bundle",
     "url" : "https://example.com/output/del_file_1.ndjson"      
   }],
   "error" : [{
     "type" : "OperationOutcome",
     "url" : "https://example.com/output/err_file_1.ndjson"
   }]

}

Each of the file locations from the output, deleted, and error sections of the response can be retrieved from the server. There will be a separate file (or files) for each resource type. The server will determine number of records available per file (paging), in order for the files to be of a manageable file size.

Additional details regarding the structure and elements of the response body can be found in the HL7 FHIR Server Bulk Export API, section 2.5.5.4

NDJSON is a streamlined version of fhir/json output, where all whitespace characters have been removed, but otherwise follow FHIR rules for encoding using json. References to other FHIR resources will be based on the resource.id, and will require cross-referencing with other files in the bulk export, e.g. a HealthcareService.coverage may reference a Location resource, which would be found in the Location export file.

Example NDJSON output file:

 {"resourceType":"HealthcareService","id":"0381147f-0788-4cb0-83cf-042f80c7b1cf","providedBy":{"display":"HS Org Name 1"},"category":[{"coding":[{"system":"http://fhir-servicesubtype.otn.ca","code":"direct"}]}],"specialty":[{"coding":[{"system":"http://snomed.info/sct","code":"394578005","display":"Audiological medicine"}]}],"name":"econsult ford r smith","telecom":[{"system":"phone","value":"416-555-1234","use":"home","rank":1}],"coverageArea":[{"reference":"d8222b06-e2cf-4300-aa83-80b285ea98f8","type":"Location"}],"program":[{"coding":[{"system":"http://fhir-servicetype.otn.ca","code":"econsult","display":"econsult"}]}],"referralMethod":[{"coding":[{"system":"http://terminology.hl7.org/CodeSystem/service-reerral-method","code":"elec"}]}],"availableTime":[{"allDay":false,"availableStartTime":"07:00:00","availableEndTime":"17:00:00"}],"endpoint":[{"reference":"Endpoint/endpoint1","type":"Endpoint1"}]}
 {"resourceType":"HealthcareService","id":"b33efb57-4a34-430f-99a4-a23d4dbf0324","providedBy":{"display":"HS Org Name 2"},"category":[{"coding":[{"system":"http://fhir-servicesubtype.otn.ca","code":"direct"}]}],"specialty":[{"coding":[{"system":"http://snomed.info/sct","code":"394578005","display":"Audiological medicine"}]}],"name":"econsult ford r smith","telecom":[{"system":"phone","value":"416-555-1234","use":"home","rank":1}],"coverageArea":[{"reference":"449ae253-0db8-489a-910c-22dc15a871c8","type":"Location"}],"program":[{"coding":[{"system":"http://fhir-servicetype.otn.ca","code":"econsult","display":"econsult"}]}],"referralMethod":[{"coding":[{"system":"http://terminology.hl7.org/CodeSystem/service-reerral-method","code":"elec"}]}],"availableTime":[{"allDay":false,"availableStartTime":"07:00:00","availableEndTime":"17:00:00"}],"endpoint":[{"reference":"Endpoint/endpoint2","type":"Endpoint2"}]}

Associated/Referenced Resources

The HL7 FHIR Bulk Data System Level export has a parameter called "includeAssociatedData". When this feature is enabled, a retrieval request for a requested resource will also be accompanied by its associated resources. As an example, a HealthcareService resource may reference a Location resource through the element HealthcareService.location -- with the includeAssociatedData feature, an Ontario PHSD Bulk Export request for HealthcareService resources would retrieve the HealthcareService resources matching the query parameters, as well as all the Location resources referenced by those HealthcareService resources.

This "includeAssociatedData" option will be enabled automatically for all queries, and will not need to be passed as a query parameter. This feature cannot be disabled for this release, in order to maintain data integrity and completeness.

URL: [base]/$export

Parameters

Use	Name	Cardinality	Type	Binding	Description
IN	_outputFormat	0..1	string	application/fhir+ndjson	The format for the requested Bulk Data files to be generated. The only format currently supported is Newline Delimited JSON
IN	_since	0..1	instant	Format: YYYY-MM-DDThh:mm:ss.sss+zz:zz	Resources will be included in the response if Resource.meta.lastUpdated is later than the supplied _since time. The time shall be specified at least to the second and shall include a timezone offset
IN	_type	1..1	string	HealthcareService, Organization, Location and Practitioner	A string of comma-delimited FHIR resource types. For the initial release, PHSD Bulk Export will only allow one resource type for this parameter to reduce unnecessary complexity (compared to HL7 Bulk Export's 0.. for this parameter)* Note: (1) If "_type" is set to Practitioner, four types of files will be generated: Practitioner, PractitionerRole, PractitionerRole Location ans Questionnaire (2) If "_type" is set to HealthcareService, four types of files will be generated: HealthcareService, Organization, Location, and Questionnaire.
IN	_typeFilter	0..*	string		A string of comma-delimited FHIR REST search queries. For the available values for _typeFilter, please see the Query Search Parameters table in the respective Operation: Search "ResourceName" page in this implementation guide.

HealthcareService Bulk Export

HealthcareService Search query paramaters can be found on the Operation: Search HealthcareService Page.

Sample export query:

HTTP GET using in-line parameters

[baseURL]/$export?  
  _since=    
    2024-01-15T03%3A00%3A00-05%3A00&
  _type=    
    HealthcareService&    
  _typeFilter=    
    HealthcareService%3Fprogram%3DTHLN,    
    HealthcareService%3Fservice-category%3DM13

HTTP POST using FHIR Paramaters resource:

POST [baseURL]/$export

{"resourceType" : "Parameters",  
  "parameter" : [{  
    "name" : "_since",
    "valueInstant" : "2024-01-15T03:00:00-05:00"
  },{  
    "name" : "_type",
    "valueString" : "HealthcareService"  
  },{  
    "name" : "_typeFilter",  
    "valueString" : "HealthcareService?program=THLN,HealthcareService?service-category=M13"  
  }
  ]  
}

Location Bulk Export

HTTP GET using in-line parameters

[baseURL]/$export?  
  _since=    
    2024-01-15T03%3A00%3A00-05%3A00&
  _type=    
    Location&    
_typeFilter=
    Location%3Ftype%3DTHLNhttp%3A%2F%2Fehealthontario.ca%2Ffhir%2FCodeSystem%2Fppr-provider-organization-role-type%7CCHC

HTTP POST using FHIR Paramaters resource:

POST [baseURL]/$export

{"resourceType" : "Parameters",  
  "parameter" : [{  
    "name" : "_since",
    "valueInstant" : "2024-01-15T03:00:00-05:00"
  },{  
    "name" : "_type",
    "valueString" : "Location"  
  },{  
    "name" : "_typeFilter",  
    "valueString" : "Location?type=http://ehealthontario.ca/fhir/CodeSystem/ppr-provider-organization-role-type|CHC"  
  }]  
}

Organization Bulk Export

HTTP GET using in-line parameters

[baseURL]/$export?  
  _since=    
    2024-01-15T03%3A00%3A00-05%3A00&
  _type=    
    Organization&    
  _typeFilter=Organization%3Ftype%3DTHLNhttp%3A%2F%2Fehealthontario.ca%2Ffhir%2FCodeSystem%2Fppr-provider-organization-role-type%7CPCP

HTTP POST using FHIR Paramaters resource:

POST [baseURL]/$export

{"resourceType" : "Parameters",  
  "parameter" : [{  
    "name" : "_since",
    "valueInstant" : "2024-01-15T03:00:00-05:00"
  },{  
    "name" : "_type",
    "valueString" : "Organization"  
  },{  
    "name" : "_typeFilter",  
    "valueString" : "Organization?type=http://ehealthontario.ca/fhir/CodeSystem/ppr-provider-organization-role-type|PCP"  
  }]  
}

Practitioner Bulk Export

HTTP GET using in-line parameters

[baseURL]/$export?  
  _since=    
    2024-01-15T03%3A00%3A00-05%3A00&
  _type=    
    Practitioner&    
  _typeFilter=Practitioner%3Fcommunication%3Durn%3Aietf%3Abcp%3A47%7Cfr

HTTP POST using FHIR Paramaters resource:

POST [baseURL]/$export

{"resourceType" : "Parameters",  
  "parameter" : [{  
    "name" : "_since",
    "valueInstant" : "2024-01-15T03:00:00-05:00"
  },{  
    "name" : "_type",
    "valueString" : "Practitioner"  
  },{  
    "name" : "_typeFilter",  
    "valueString" : "Practitioner?communication=urn:ietf:bcp:47|fr"  
  }]  
}