Profiles & Operations > Location EMPI Match

Location EMPI Match

The Provider Location Match EMPI operation provides an alternative to the RESTful Location search. In RESTful search, a client specifies a list of search criteria and the server returns a list of Locations that match those criteria (depending on which endpoint the search is invoked). In an EMPI query, a set of criteria are provided, but rather than treating each criterion as a strict filter (results are returned only if they meet all of the criteria), the EMPI match operation performs a probabalistic match, such that results may not match all of the criteria - or even any of the criteria - exactly. Results are based on server-specific rules that allow for alternate spellings, typos, historical provider information and other factors, finds those Locations that have a high probability of being the sought provider record. Each record is accompanied by a score that indicates the server's evaluation of the likelihood that the specified record is the one being sought.

The PPR server will likely be extended to support traditional deterministic RESTful search at some point in the future.

In the Ontario Health Provider Location Match operation, parameters are submitted in a "query by example" form. I.e. The input to the operation is a single parameter - an Location resource that is populated with what information is known about the provider in an attempt to find the PPR's corresponding record. Constraints on Location are relaxed however - it is not necessary to specify a name or identifier or any other particular piece of information. However, the more information provided, the better the PPR will be able to find the appropriate practitioner and the greater the certainty with which it will be able to establish a match.



Scope

This transaction involves a request by a FHIR Provider Location RESTful Client for information about Locations.The request is received by the FHIR Provider Location EMPI server. The server immediately processes the request and returns a FHIR Bundle containing a list of potentially matching Locations.PPR requires that the Minimum Search Criteria be met in order to return provider location records.

Storyboard

Upon admission to hospital in Toronto, a patient indicates that their cardiologist is a Dr. Smith based in Windsor. In order to find the contact information for the patient's doctor, the hospital searches the PPR based on the information provided. The hospital's EHR uses the specified name, city and specialty to compose a Provider Location Match request and send it to the FHIR Provider Location EMPI Server (PPR). The response by PPR will include a list of Locations with their contact information, identifiers and demographic information as well as a score indicating the probability of the match. The user of the FHIR Provider Location RESTful Client will review the returned Locations and, in consultation with the patient, determine which one is their cardiologist and use the provided contact information to consult with the patient's doctor.



Interaction Diagrams

The following diagram illustrates the high level interaction between a FHIR Provider Location EMPI Client and FHIR Provider Location EMPI Server. The transactions will use the following pair of query and response:

  • Request EMPI Provider Location Match / EMPI Provider Location Match Response

The resource cannot be rendered.

Actor: FHIR Provider Location RESTful Client

Role: Requests a list of provider Locations with a probablistic match on the supplied set of demographics criteria (example: ID or Name) from the FHIR Provider Location EMPI Server. The FHIR Provider Location RESTful Client populates its local store with contact, licensing and demographic information received from the FHIR Provider LocationEMPI Server

Actor: FHIR Provider Location EMPI Server

Role: Returns contact, licensing and demographic information for all Locations matching the criteria provided by the FHIR Provider Location RESTful Client.

NOTE: In this implementation guide, Provincial Provider Registry is the FHIR Provider Location EMPI Server. All subsequent references of this actor should be interpreted as Provincial Provider Registry.



Specification

Operation Definition

Above link provides the definition of operation- Location EMPI Match.It returns a list of candidate Locations based on a probability matching algorithm for the set of data in a provided Location record.


This FHIR spec makes use of the following resource profiles:

Provider Location EMPI Match Request

The relationship between the resources used in EMPI request is below:

Command 'tree' could not render: Project was not found for provincialproviderre/location-png.



Provider Location EMPI Match Response

The resource cannot be rendered.

General

The PPR FHIR profiles are developed to constrain value sets and cardinality of data elements in the resources listed above. Since FHIR R4 does not support all the data elements required for this project, we have introduced a few extensions which can be found here.

Extensions

Summary of Supported Operations

The table below shows the allowed transactions for each profile and how they support FHIR endpoints, resources and their corresponding HTTP operations:

Resource Transaction HTTP Operations URL Request Body Resource Response Body Resource
Location Match operation POST [base]/Location/$match Parameters resource containing the following parameters: Location resource, and count integer(optional) A searchset Bundle containing Location entries

The interaction summary table below lists the HTTP status codes that may be returned for the query.

Interaction Content-Type Body Location Versioning Status Codes Comments
search R R: Bundle N/A N/A 200,400,404,422,500


EMPI Provider Location Match Operations

These represent an HTTP POST of a Parameters resource containing a single Location instance from the FHIR Provider RESTful Client to the FHIR Provider EMPI Server.

Trigger Event

When a FHIR Provider Location RESTful Client needs to select an Location based on identifier, contact and/or demographic information about Locations whose information has a probability match on a minimal set of known data, it invokes one of the EMPI Provider Matches.

The FHIR Provider Location EMPI Server found records with a probabilistic match to the identifier, contact, demographic and other data specified by the FHIR Provider Location RESTful Client when it invoked the Match operation.

Expected Behaviour

The FHIR Provider Location EMPI Server shall return records that have a probabilistic match to the search criteria provided by the FHIR Provider Location RESTful Client. The FHIR Provider Location EMPI Server shall respond with a Match Response synchronously (i.e. on the same connection as was used to initiate the request).

The FHIR Provider Location EMPI Server shall respond to the query request as described by the following cases and shall behave according to the cases listed below:

Case Scenario Description Response
1 PPR finds in its information source, at least one location record with a sufficiently high probabilistic match on the criteria sent in the input location record. HTTP 200 (OK) is returned as the HTTP status code.A Resource Bundle is returned representing the result set.Refer to Bundle definition here
2 PPR cannot find any location record matching the criteria in the source location record. HTTP 200 (OK) is returned as the HTTP status code. A Resource Bundle is returned representing the zero result set. Refer to Bundle definition here. The bundle may contain operationOutcome with further information.
3 PPR cannot validate the request as it does not conform to the specification. HTTP 400 (Bad Request) is returned as the HTTP status code. An OperationOutcome Resource is returned indicating an issue, where applicable. The client must fix the request and try again.
4 The requested resource is not supported or the endpoint is not a valid FHIR endpoint HTTP 404 (Not Found) is returned as the HTTP status code. The body contains an OperationOutcome with error details, where applicable.
5 PPR has validated the request, but cannot return valid response HTTP 422 (Unprocessable Entity) is returned as the HTTP status code. An OperationOutcome Resource is returned indicating an issue, where applicable. The client must fix the request to align with the specification and try again.
6 PPR cannot validate the request as it does not conform to the specification. HTTP 422 (Unprocessable Entity) is returned as the HTTP status code. An OperationOutcome Resource is returned indicating an issue, where applicable. Client should contact Ontario Health for troubleshooting.
7 PPR validates the request but cannot return valid response due to internal issue. HTTP 500 (Internal Server Error) is returned as the HTTP status code. An OperationOutcome Resource is returned indicating an issue, where applicable. Client should contact Ontario Health for trouble shooting.

See Response Handling for additional HTTP Response Codes


Examples

Location EMPI request :

Examples of a location match request can be found below

Location search response :

Examples of a location match response can be found below

Example of Operation Outcome

Appendix: Business Rules

The following sections describe the business rules specific to EMPI Match operation that may be helpful to implementers.

Minimum Search Criteria

In Provincial Provider registry ,there is a mandatory specific set of minimum criteria that must be met when querying the PPR. One of the following minimum criteria must be met:

Set of Minimum Query Criteria:

Role: Role can be either Regclass code or Role Code (e.g. Laboratories (LABS), Pharmacies (PHCY)) click here for the full list

Address: at least 5 tokens out of: stline1, stline2, stline3, stline4, city, province, postal code must be provided

  1. Name + City

  2. Name + Postal Code

  3. Name + first 3 digits of postal code

  4. Role + city

  5. Role + postal code

  6. Role + first 3 digits of postal code

  7. Address

  8. Any Phone

Maximum Results

In PPR on a given response maximum result set of 25 matched candidates will be returned

Scoring

PPR is currently configured to return providers matched on any positive score (i.e. greater than zero) across identifier, Name, Gender, Address, or Phone attributes. Any other attribute(s) included in the search are not considered.

Based on the minimum search criteria enforced, PPR translates to a positive score matched based on probabilistic search algorithm.

PPR currently returns matched candidates in descending order based on match score (highest scoring first, lowest scoring last). Note that more than one candidate may receive the same match score and will be ordered in the query response message accordingly. The match score returned for an individual candidate depends on the query criteria used to perform the search. The returned value for an individual candidate match score is based on the probabilistic search algorithm outlined in the Business Context section.

The expectation is that consumers will display PPR matched candidates in the order returned from the PPR without display of the corresponding match score per individual candidate. For further information on interpreting individual match scores, please contact the Ontario Health Registries Product Management Team at oh-ds_registries@ontariohealth.ca.