National Healthcare Directory Exchange
1.0.0-ballot - ballot
US
National Healthcare Directory Exchange
1.0.0-ballot - ballot
US
This page is part of the National Healthcare Directory Exchange (v1.0.0-ballot: STU 1 Ballot 1) based on FHIR R4. . For a full list of available versions, see the Directory of published versions 
For the directory bulk data extraction, to request an entire copy of all content in the directory, the scope selection can be defined at the top level specifying that it would like to retrieve all content for the specified resource types from the base of the FHIR server.
GET [base]/$export?_type=Organization,Location,Practitioner,PractitionerRole,HealthcareService,VerificationResult, ...
A healthcare directory may curate such an extract on a nightly process, and simply return results without needing to scan the live system. In the result, the value returned in the transactionTime in the result should contain the timestamp at which the extract was generated (including timezone information) and should be used in a subsequent call to retrieve changes since this point in time.
Once a system has a complete set of data, it is usually more efficient to ask for changes from a specific point in time. In which case the request should use the value above (transactionTime) to update the local directory.
GET [base]/$export?_type=Organization,Location,Practitioner, ... &_since=[transactionTime]
This behaves the same as the initial request, with the exception of the content.
It is expected that this request is more likely to return current information, rather than a pre-generated snapshot, as the transactionTime could be anything.
Note: The current bulk data handling specification does not handle deleted items. The recommendation is that periodically a complete download should be performed to check for “gaps” to reconcile the deletions (which could be due to security changes). However, content should not usually be “deleted” it should be marked as inactive, or end dated.
Proposal: Include a deletions bundle(s) for each resource type to report the deletions (when using the _since parameter). As demonstrated in the status tracking output section below, these bundles would be included in the process output as a new property “deletions”. This bundle would have a type of “collection”, and each entry would be indicated as a deleted item in the history.
<entry>
<!-- no resource included for a delete -->
<request>
<method value="DELETE"/>
<url value="PractitionerRole/[id]"/>
</request>
<!-- response carries the instant the server processed the delete -->
<response>
<lastModified value="2014-08-20T11:05:34.174Z"/>
</response>
</entry>
The total in the bundle will be the count of deletions in the file, the total in the operation result will indicate the number of deletion bundles in the ndjson (same as the other types).
If the caller doesn’t want to use the deletions, they can ignore the files in the output, and not download those specific files.
The previous sections are all that is defined by the FHIR Bulk Data extract specification, however one may choose to implement an additional parameter to permit the selection to also filter resources that are included in a specified list resource. The approach is similar to the same capability defined by FHIR http://hl7.org/fhir/search.html#list
This operation could be used by client applications such as a Primary Care System that want to only periodically update using this technique, solely using resources they currently have loaded in their “local directory” - an internal black book, which caches resources from previous searches to the system.
GET [base]/$export?_type=Organization,Location,Practitioner,PractitionerRole,HealthcareService&_list=List/45
In this example the Primary Care System would be responsible for keeping List/45 up to date with what it is tracking. A national service may decide that permitting this List resource management is too much overhead, however local enterprise directories may support this type of functionality.
The current bulk data export operations use the Group resource to define the set of data related to a Patient. At present there is no definition for this to be done in the directory space, unless it is at the resource level. This is possible with search and subscriptions (which leverage search) by using search parameters on the resource types and setting the parameters of interest.
When defining a subset of data, consideration should be given to what happens when data is changed to the extent that it is no longer within the context of the conditions.
One possible method would be to use a bundle of searches where each type has its own search parameters. Another way is to use a GraphDefinition resource.
This functionality should be the subject of a connectathon to determine practical solutions.
One possibility could be to leverage the List functionality described above to maintain a state of what was included in previous content. However, this incurs additional overhead on the part of the server and for many systems, especially those at scale like a national system, this is likely not practical.
The bulk extract format is always an nd-json file (new-line delimited json). Each file can only contain 1 resource type in it, but can be spread across multiple files, with either a size limit or count limit imposed by the extracting system, not the requestor.
The list of these files will be returned in the Complete status output, as described in the standard Bulk Data documentation.
There are 2 options for starting the extract. The first option is a single operation specifying all the content, and the other option is for a specific type only. These were both covered above in the “selecting the scope section.
Here one will only document the use of the global export, as an initial request.
The initial request:
GET [base]/$export?_type=Organization,Location,Practitioner,PractitionerRole,HealthcareService
With headers:
Accept: application/fhir+json</code>
Authentication: Bearer [bearer token]</code>
Prefer: respond-async</code>
This will return either:
4XX or 5XX with an OperationOutcome resource body if the request fails, or a202 Accepted when successful. Which will include a Content-Location header with an absolute URI for subsequent status requests and optionally, an OperationOutcome in the resource bodyExample Content-Location: http://example.org/status-tracking/request-123 (note that this is not necessarily a FHIR endpoint, and is not a true FHIR resource)
After a bulk data request has been started, the client MAY poll the URI provided in the Content-Location header.
GET http://example.org/status-tracking/request-123
This will return one of the following codes:
HTTP status code of 202 Accepted when still in progress (and no body has been returned)
5XX when a fatal error occurs, with an OperationOutcome in json format for the body detailing of the error
(Note this is a fatal error in processing, not some error encountered while processing files - a complete extract can contain errors)200 OK when the processing is complete, and the result is a json object as noted in the specification (an example included below)Refer to the build data specification for details of the completion event:
https://github.com/smart-on-fhir/fhir-bulk-data-docs/blob/master/export.md#response—complete-status
{
"transactionTime": "[instant]",
"request": "[base]/$export?_type=Organization,Location,Practitioner,PractitionerRole,HealthcareService",
"requiresAccessToken": true,
"output": [
{
"type": "Practitioner",
"url": "http://serverpath2/practitioner_file_1.ndjson",
"count": 10000
},
{
"type": "Practitioner",
"url": "http://serverpath2/practitioner_file_2.ndjson",
"count": 3017
},
{
"type": "Location",
"url": "http://serverpath2/location_file_1.ndjson",
"count": 4182
}
],
// Note that this deletions property is a proposal, not part of the bulk data spec.
"deletions": [
{
"type": "PractitionerRole",
"url": "http://serverpath2/practitionerrole_deletions_1.ndjson", // the bundle will include the total number of deletions in the file
"count": 23 // this is the number of bundles in the file, not the number of resources deleted
}
],
"error": [
{
"type": "OperationOutcome",
"url": "http://serverpath2/err_file_1.ndjson",
"count": 439
}
]
}
Once the tracking of the extract returns a 200 OK completed status, the body of the result will include the list of prepared files that can be downloaded.
Then each of these URLs can be downloaded by a simple get, ensuring to pass the Bearer token if the result indicates requiresAccessToken = true
While downloading, it is also recommended to includeg the header Accept-Encoding: gzip to compress the content as it comes down.
GET http://serverpath2/location_file_1.ndjson
(Note: our implementation will probably always gzip encode the content - as we are likely to store the processing files gzip encoded to save space in the storage system)
Once all the needed files are downloaded, one should tell the server to cleanup, as detailed in the next section.
This is the simplest step in the process. In order to finish the extract, one will call DELETE on the status tracking URL.
DELETE http://example.org/status-tracking/request-123
Calling DELETE tells the server that we are all finished with the data, and it can be deleted/cleaned up. The server may also include some time based limits where it may only keep the data it for a set period of time before it automatically cleans it up.
A close relative to the bulk data extract is the subscriptions content. How these will work in the context of Bulk Directory exchanges needs further experimentation and connectathon experiences.
The subscription could be setup to monitor the directory for realtime changes to resources of interest defined via search parameters.
The “urgent notifications” channel is yet to be defined but should enable specific actions such as license suspensions/revocations.
...TODO edit this ...
The FHIR Subscription API allows directories to (push) data to multiple local directories based on a set of criteria in the form of a FHIR query, which are defined by the subscriber. For example:
Any newly created or updated resources that meet the criteria triggers the Server to notify the subscriber and “forward” the results of the search criteria (e.g., the updated Practitioner, PractitionerRole and Endpoint resource - to a specified target endpoint). An alternate workflow is for a Server notification to occur without a payload and then the subscriber would fetch the data through the REST API from a predetermined endpoint - typically a “middleman” server.
Below is an example of a subscription to push all new and updated Practitioners, PractiyionerRoles, and Endpoints from the ‘vhdir-demo’ server to the ‘local-dir’:
{
"resourceType":"Bundle",
"id":"VhDir-subscription-bundle",
"meta":{
"lastUpdated":"2017-01-24T01:43:30Z"
},
"type":"transaction",
"entry":[
{
"fullUrl":"urn:uuid:61ebe359-bfdc-4613-8bf2-c5e300945f0a",
"resource":{
"resourceType":"Subscription",
"id":"vhdir-connectathon-scenario-12p",
"status":"requested",
"contact":[
{
"system":"phone",
"value":"ext 4123"
}
],
"end":"2020-01-01T00:00:00Z",
"reason":"(push) healthcare directory data to multiple local directories",
"criteria":"Practitioner?address-postalcode:contains=02108, 02109, 02110, 02111, 02113, 02114, 02115, 02116, 02118, 02119, 02120, 02121, 02122, 02124, 02125, 02126, 02127, 02128, 02129, 02130, 02131, 02132, 02134, 02135, 02136, 02151, 02152, 02163, 02199, 02203, 02210, 02215, 02467",
"channel":{
"type":"rest-hook",
"endpoint":"https://local-dir/fhir",
"payload":"application/fhir+json",
"header":[
"Authorization: Bearer secret-token-abc-123"
]
}
},
"request":{
"method":"POST",
"url":"Subscription"
}
},
{
"fullUrl":"urn:uuid:61ebe359-bfdc-4613-8bf2-c5e300945f0a",
"resource":{
"resourceType":"Subscription",
"id":"vhdir-connectathon-scenario-12pr",
"status":"requested",
"contact":[
{
"system":"phone",
"value":"ext 4123"
}
],
"end":"2020-01-01T00:00:00Z",
"reason":"(push) healthcare directory data to multiple local directories",
"criteria":"PractitionerRole?practitioner.address-postalcode:contains=02108, 02109, 02110, 02111, 02113, 02114, 02115, 02116, 02118, 02119, 02120, 02121, 02122, 02124, 02125, 02126, 02127, 02128, 02129, 02130, 02131, 02132, 02134, 02135, 02136, 02151, 02152, 02163, 02199, 02203, 02210, 02215, 02467",
"channel":{
"type":"rest-hook",
"endpoint":"https://local-dir/fhir",
"payload":"application/fhir+json",
"header":[
"Authorization: Bearer secret-token-abc-123"
]
}
},
"request":{
"method":"POST",
"url":"Subscription"
}
},
{
"fullUrl":"urn:uuid:61ebe359-bfdc-4613-8bf2-c5e300945f0a",
"resource":{
"resourceType":"Subscription",
"id":"vhdir-connectathon-scenario-12pe",
"status":"requested",
"contact":[
{
"system":"phone",
"value":"ext 4123"
}
],
"end":"2020-01-01T00:00:00Z",
"reason":"(push) healthcare directory data to multiple local directories",
"criteria":"Endpoint?_has:PractitionerRole:endpoint:practitioner.address-postalcode:contains=02108, 02109, 02110, 02111, 02113, 02114, 02115, 02116, 02118, 02119, 02120, 02121, 02122, 02124, 02125, 02126, 02127, 02128, 02129, 02130, 02131, 02132, 02134, 02135, 02136, 02151, 02152, 02163, 02199, 02203, 02210, 02215, 02467",
"channel":{
"type":"rest-hook",
"endpoint":"https://local-dir/fhir",
"payload":"application/fhir+json",
"header":[
"Authorization: Bearer secret-token-abc-123"
]
}
},
"request":{
"method":"POST",
"url":"Subscription"
}
}
]
}
IG © 2021+ HL7 Patient Administration Working Group. Package hl7.fhir.us.directory-exchange#1.0.0-ballot based on FHIR 4.0.1. Generated 2022-08-09
Links: Table of Contents |
QA Report
| Version History |
|
Propose a change