Profiles & Operations > Practitioner EMPI Match

Practitioner EMPI Match

The EMPI Match operations provides an alternative to the RESTful practitioner search. In RESTful search, a client specifies a list of search criteria and the server returns a list of practitioners that match those criteria (depending on which endpoint the search is invoked on). 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 practitioners 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 Provider Person Match operation, parameters are submitted in a "query by example" form i.e. the input to the operation is a single parameter resouce which contains - a Practitioner resource that is populated with known information about the provider in an attempt to find corresponding record from PPR. Constraints on Practitioner 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.

Note that Provider Person and Practitioner are used interchangeably in this document, as Practitioner is the name of the FHIR resource used to represent a Provider Person. When used in the context of FHIR, Practitioner will be used in place of Provider Person.

Scope

This transaction involves a request by a FHIR Provider RESTful Client for information about practitioners whose identification, licensing and/or demographic data match data provided in the FHIR operation. The request is received by the FHIR Provider EMPI server. The server processes the request and returns a FHIR Bundle containing a list of potentially matching practitioners.PPR requires that the Minimum Search Criteria be met in order to return provider 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 Person Match request and send it to the FHIR Provider EMPI Server (PPR). The response by PPR will include a list of practitioners 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 RESTful Client will review the returned practitioners 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 EMPI Client and FHIR Provider EMPI Server. The Provider transactions will use the following pair of query and response:

  • Request Provider Person EMPI Match / Provider Person EMPI Match Response

The resource cannot be rendered.

Actor: FHIR Provider RESTful Client

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

Actor: FHIR Provider EMPI Server

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

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


Specification

Operation Definition

Above link provides the definition of operations- Practitioner EMPI Match. It returns a list of candidate Practitioners (along with linked PractitionerRole and Location FHIR resources)based on a probability matching algorithm for the set of data in a provided practitioner record.


This FHIR spec makes use of the following resource profiles:

Practitioner 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/practitioner-png.



Note: Please note that Practitioner response is referenced in PractitionerRole response

Practitioner EMPI Match Response

The resource cannot be rendered.

Search.Mode

The base FHIR specification states that while EMPI Match and Search must return the requested resource type, Practitioner, the server may also choose to return additional relevant resources. In the case of PPR, the server will also return the PractitonerRole and Location resources that are associated to the Practitioner search results.

The element Bundle.entry[x].search.mode will be used to distinguish between which resources are being returned as a direct result of the search (value="match") vs inclusion for relevance (value="include"). Similarly, this may also be used to indicate OperationOutcome resources that were included (value="outcome").

Extensions

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 are used in the practitioner profiles.


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
Practitioner and PractitionerRole Match operation POST [base]/Practitioner/$match Parameters resource containing the following parameters: Practitioner resource, PractitionerRole resource(optional), count integer (optional) Bundle containing Practitioner, PractitionerRole, Location resources

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
$match R R: Bundle N/A N/A 200,400,404,422,500


EMPI Provider Match Operations

These represent an HTTP POST of a Parameters resource containing a single Practitioner instance (depending on the endpoint POSTed to) from the FHIR Provider RESTful Client to the FHIR Provider EMPI Server.

Trigger Event

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

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

Expected Behaviour

The FHIR Provider EMPI Server shall return records that have a probabilistic match to the search criteria provided by the FHIR Provider RESTful Client. The FHIR Provider 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 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 practitioner record with a sufficiently high probabilistic match on the criteria sent in the input Practitioner 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 practitioner record matching the criteria in the source practitioner 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.
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

Examples of a provider person match request can be found below:

Examples of a provider person 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:

Name: Name can be either first name,middle name or last name

Profession: Profession can be either Regulated Health profession Code or Unregulated Health profession code

  1. Name

  2. Name + City

  3. Name + Postal code

  4. Name + first 3 digits of postal code

  5. Profession + City

  6. Profession + Postal code

  7. Profession + first 3 digits of postal code

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.