Shared Health Specification and Guide Version 5.0

1.1 Overview

Shared Services defines 3 query capabilities:

• The generic polling message retrieval mechanism - which involves querying the Bundle endpoint
• Provider Registry Organization Query
• Provider Registry Practitioner Query

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. 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.

• Multi-message poll response is a response that has a "Bundle of Bundles". It is basically a response that includes multiple messages from the inbox, up to a maximum number determined by configuration, which is set to 20 by default and there are no other messages in the inbox
• Multi-page poll response occurs in cases where the number of bundles in the inbox exceeds the maximum number that can be included in a single multi-message poll response. This response includes an extra <link> element with relation set to "next" which will include a sequence number in its URL which identifies the next inbox table row to be retrieved (i.e. the 21st bundle).
• The URLs for the links will be something like the following and will vary by environment
  https://api.telus.com/rest/v1/THP/mailbox_vs0/Bundle
  for the "self" link (the host name will vary based on environment) and
  https://api.telus.com/rest/v1/THP/mailbox_vs0/Bundle?start=123456
  for the "next" link (host name again will depend on environment) where "12345" is the sequence number for the next inbox table row to be retrieved.

There are 2 Options for managing the polling of the your inbox

1. Option 1 Poll and keep polling until you get everything then clear
   1. The next link can be used by to get the next set of messages and once the inbox is empty and all messages have been retrieved you send the Clear Message Queue Request to delete each of the retrieved bundles
   2. Poll at next regular interval
2. Option 2 Poll and Clear and Continue polling and clearing until inbox is empty
   1. You can just acknowledge the first 20 that are returned (by using the deleting function within the Clear Message Queue Request and then poll again to get the next set, you must continue to poll and clear until the inbox is empty
   2. Poll at next regular interval

Inbox polling returns messages from the Inbox regardless of their FHIR specification, i.e. it will mix 101/201 and 305 Interaction messages. All messages are delivered as separate bundles within the parent “Bundle of Bundles” (e.g. separate 305 communications will remain in separate bundles). Health Exchange does not mix task objects from different parent messages.

The response to the HTTP 'GET' command 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.

The following details each step in the polling process and the associated HTTP action. The actual URLs 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 (pharmacy search versus practitioner search) in which the query is being 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 URLs are configurable by context and environment within their applications.

A READ is used if a specific resource (e.g. CPRID) is known to the user. By example, the user may wish to return a specific Practitioner or Organization record using a CPRIDentifier 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://api.sharedhealth.exchange/rest/v1/preconf/THP/TPR_vs1/Organization/[CPRID]

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://api.sharedhealth.exchange/rest/v1/preconf/THP/TPR_vs1/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.

The BULK SEARCH uses a set of parameters in the body of the request that will return a list of organizations that meet the criteria. From a business perspective, the sending system will synchronize their local records with the Registry using CPR identifiers or a list of fax numbers from their local system as parameters. As per FHIR, (http://build.fhir.org/search.html#Introduction), this is a POST using the standard, application/x-www-form-urlencoded whereby the parameters are specified in the body. POST https://EnvironmentSpecificHost/EnvironmentAndContextSpecificPathRegistry/Organization

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)