Shared Health Specification and Guide Version 5.0

1.1 Overview

1.1 Encoded URLs

In URLs provided in the VIG, various characters (e.g. the vertical pipe) must be replaced by the URL-encoded value (e.g. %7C) when representing a string character to avoid interpretation as a URL syntax character. Also, known as "percent-encoding", it is a mechanism for encoding information in a Uniform Resource Identifier (URI). Please see the table below for a sample of URL-encoded values used in the VIG.

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

   Guidance: While continual polling is acceptable, consider polling up to 10 pages, and if each page retrieves 20 messages, then the clear queue request would contain 200 entries. If there are greater than 200 entries in the clear queue request there is a risk of the client experiencing a timeout issue and not receiving a confirmation that the request was successful.

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

   Guidance: It is recommended to leverage option 2 for larger organizations that manage multiple sites as there could be a higher number of messages to poll and acknowledge.

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 profiles can be found in the Organization Bundle Query and Practitioner Bundle Query profiles. 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

1.4.1 Provider Registry Response Filtering

Based on the type of search executed either a single resource is returned, or multiples will be returned as a searchset bundle. As of v5.2 the HTTP Request header is mandatory allowing for the CPRId of the requestor to be identified. Based on the requestors registered jurisdiction, responses may be filtered based on rules enforced by that jurisdiction. For example: In Quebec, electronic prescribing is only allowed within the jurisdiction, therefore queries where the requester is in Quebec, will only receive profiles registered in Quebec. All requests originating outside of Quebec, will not receive any Quebec profiles. They will be filtered out. The provider registry query responses will not indicate when records have been filtered and will return only the applicable results where there are no restrictions or will return a response with 0 results if there are no applicable matches. The only exception to this is when using the CPRID identifier search where a synchronous error message will be returned indicating a jurisdictional restriction prevented the result from being returned.

1.4.2 Practitioner or Organization Service Status

The query 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. The business rules that are specific to PrescribeIT® and Clinican Communications use the Servce Entity at the Practitioner and Organization 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)