Shared Health Specification and Guide Version 2.0 Revision F

1.1 Overview

Shared Services defines 3 query capabilities:

• The generic polling message retrieval mechanism - which involves querying the Bundle endpoint
• A provider registry query for Practitioners
• A provider registry query for Organizations

1.2 Polling for Messages

The retrieval of messages is handled via a 'polling' mechanism. At regular intervals, EMRs, PMSs and aggregators will query Health Exchange to see if there are any messages waiting for them. The query is performed by invoking an HTTP 'GET' command on the URL that will be provided to vendors in a separate document. (Example: https://EnvironmentSpecificHost/EnvironmentSpecificPathInbox/Bundle). No filters are specified as messages will automatically be filtered based on the access permissions of the requesting service location or aggregator - only those messages intended for the recipient system will be returned.

The response to the GET will usually be a "200 OK" result along with a FHIR searchset bundle containing 0 or more FHIR message bundles - messages intended for the querying recipient. If there is a problem with the query, then the server may return a 4xx or 5xx series error status along with an OperationOutcome explaining the issue.

If there are many messages waiting, the server may only pass back a limited number to avoid instances that are too large to process. The existence of additional messages is indicated by the presence of a "next" link in the query response. The querying system can perform a GET on the "next" link to retrieve additional messages, or they can clear the queue of the messages already retrieved (see below) and then query again.

Once a system has taken custody of the queried messages (i.e. committed them to persistent store such that a shutdown or other event won't result in data loss), it needs to clear the retrieved messages from Health Exchange queue. It does this by POSTing a Batch to the root Health Exchange end point. The Batch contains "Delete" requests for each of the messages it has taken custody of. Health Exchange then responds with a batch response bundle indicating the success of the deletion requests. (Matching responses with the original deletion requests is positional - each deletion request entry in the batch request will have a corresponding response entry in the batch-response.)

The following details each step in the polling process and the associated HTTP action. The actual URL’s will be provided to vendors in a separate document.

1.3 Provider Registry Queries

Queries to the Provider Registry are supported to return data on Practitioner or Organizations that have been registered. These queries provide a standard FHIR RESTful interface supporting both read and search capabilities. It is also recommended that users become familiar with the base FHIR specification for the READ and Search Operations.

The READ or SEARCH that is executed MUST be context specific. This means that the vendor MUST be able to identify the context in which the query is being executed. This will either be a "PrescribeIT" based query or a "MedDialog" based query. This is a mandatory requirement as the READ or SEARCH results will be based upon the context in which the query was executed.

The endpoint URL will be used to distinguish between queries and these will be published separately, prior to vendor testing. The endpoint will also be environment specific (e.g. Test or Production). As such, the endpoint URLs are identified within this specification as "EnvironmentSpecificHost/EnvironmentSpecific". Vendors should ensure that the endpoint URL's are configurable by context and environment within their applications.

A READ is used if a specific resource (e.g. CPR ID) is known to the user. By example, the user may wish to return a specific Practitioner or Organization record using a CPR identifier that is already stored within the sending system. This may be useful if the provider is known but the user wishes to know what services a given provider is enrolled for or if they wish to update their local record. This type of query is structured as follows: GET https://EnvironmentSpecificHost/EnvironmentAndContextSpecificPathRegistry/Organization/[Organization id]

The SEARCH uses a set of parameters that will return a list of practitioners or organizations that meet the criteria. From a business perspective, a user will search for a candidate list based on criteria such as name, licence number, city or postal code or a combination thereof. This query is structured as follows: GET https://EnvironmentSpecificHost/EnvironmentAndContextSpecificPathRegistry/Organization?[Organization search parameters]

The full details included the supported parameters and response profies can be found in the Provider Registry Conformance Statement. It is also recommended that users become familiar with the base FHIR specification for the READ and Search Operations.

1.4 Provider Registry Query Responses

Link to Shared Health Organization – Provider Registry

Link to Shared Health Practitioner – Provider Registry

The structure of the Organization Query Response

The structure of the Practitioner Query Response

Based on the type of search executed either a single resource is returned, or multiples will be returned as a searchset bundle. The responses only return records for practitioners or organizations that have an active contract or had previously been active with a registration profile. For those practitioners or organizations that are active in a service, the ‘Entity Service’ segment will be included in the response and will indicate what type of service the practitioner or organization is registered and active for. The consuming system must look at the ‘entity service” which can be specified at 1) organization level 2) practitioner level 3) practitioner role level. The business rules that are specific to PrescribeIT and Clinican Communications use the Servce Entity at the Practitioner and Organization level. The Service Entity at the Practitioner Role level is not used for PrescribeIT. Other Shared services such as MedDialog will use the Service Entity at the Practitioner Role level.

A provider or organization record may be returned because they were once active in one or more services. If there is no “service entity”, this indicates that there are no active services for a given practitioner or organization at the time of query.

Following is an example of how the consumer of the responses must follow the business rules (requirements) in order to accurately determine if the registration is active or inactive. For example: Business Rule - For PrescribeIT Clinician Communication, a Practitioner must be actively registered for the service ‘and’ the Organization must be actively registered for the service. Also, at the Practitioner level, there is an option to ‘opt’ out of the service.

Practitioner has a current active registration for Clinician Communication: (Entity Service for type Clinician Communication is present in the response for both Organization and Practitioner).

Practitioner does NOT have an active registration for Clinician Communication: (Entity Service for type Clinician Communication, is absent from the Practitioner response)