Location EMPI Match
Location EMPI Match
Profiles & Operations > Location EMPI Match
Provider 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 eHealth Ontario 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 RESTful Client for information about Locations.The request is received by the FHIR Provider 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 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 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 EMPI Client and FHIR Provider EMPI Server. The Provider transactions will use the following pair of query and response:
- Request EMPI Provider Location Match / EMPI Provider Location Match Response
Actor: FHIR Provider 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 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 Locations 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
This FHIR spec is based on the HL7 STU3 Read operation. It makes use of the following resources:
Provider Location EMPI Match Request
Provider Location EMPI Match Response
Organization resource (Referenced in Location)
General
The PPR FHIR profiles are developed to constrain value sets and cardinality of data elements in the resources listed above. Since FHIR STU3 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 containing a single containing Location parameter | 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,500 |
EMPI Provider 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 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 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 | The FHIR Provider EMPI Server finds in its information source, at least one Location record with a sufficiently high probabilistic match on the criteria sent in the input record. HTTP 200 (OK) is returned as the HTTP status code. | A Provider Location Resource Bundle is returned representing the result set. The FHIR Provider EMPI Server populates the total property of the bundle with the total number of matching results. One entry is returned from the FHIR Provider EMPI Server for each Location Resource found and the 'score' element of the entry indicates how likely the match is. A score of 1 represents absolute certainty of a match. Entries are listed in descending order of score. |
| 2 | The FHIR Provider EMPI Server fails to find in its information source, any Location record matching the criteria in the source provider record. HTTP 200(OK) is returned as the HTTP status code. | A Resource Bundle is returned representing the zero result set. The FHIR Provider EMPI Server populates the total with a value of 0 indicating no results were found. No entry attributes are provided in the result. An OperationOutcome may be included giving guidance on how to increase the number of results. |
| 3 | The FHIR Provider EMPI Server does not recognize or finds validation issues on the data in the submitted "search" Location or Practitioner instance or finds other violations of operation rules. HTTP 400(Bad Request) is returned as the HTTP status code. | An OperationOutcome Resource is returned indicating an issue having the following attribute values:Severity: 'error',Code: e.g. 'code-invalid'Diagnostics: e.g. 'invalid birth date' |
| 4 | 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. Client should contact eHealth Ontario for trouble shooting. |
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
Address: at least 5 tokens out of: stline1, stline2, stline3, stline4, city, province, postal code must be provided
Name + City
Name + Postal Code
Name + first 3 digits of postal code
Name + LHIN code
Role + city
Role + LHIN
Role + postal code
Role + first 3 digits of postal code
Address
- Any Phone
Maximum Results
In PPR on a given response maximum result set of 100 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 eHealth Ontario Registries Product Management Team at iap@ehealthontario.on.ca.