Organization EMPI Match
Profiles & Operations > Organization EMPI Match
Provider Organization EMPI Match
The Provider Organization Match EMPI operation provides an alternative to the RESTful organization search. In RESTful search, a client specifies a list of search criteria and the server returns a list of organizations 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 organizations 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 Organization Match operation, parameters are submitted in a "query by example" form. I.e. The input to the operation is a single parameter - an Organization resource that is populated with what information is known about the provider in an attempt to find the PPR's corresponding record. Constraints on Organization 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 organizations.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 organizations.
For example, 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 Organization Match request and send it to the FHIR Provider EMPI Server (PPR). The response by PPR will include a list of organizations 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 organizations 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 Organization Match / EMPI Provider Organization Match Response
Actor: FHIR Provider RESTful Client
Role: Requests a list of provider organizations 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 organizations 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 makes use of the following resource profiles:
Provider Organization EMPI Match Request
Provider Organization EMPI Match Response
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 are used out in the organization profile.
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 |
|---|---|---|---|---|---|
| Organization | Match operation | POST | [base]/Organization/$match | Parameters containing a single containing Organization parameter | A searchset Bundle containing Organization 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 Organization 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 organization based on identifier, contact and/or demographic information about organizations 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 organization 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 Organization 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 Organization 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 organization 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" Organization 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
Examples of a organization match request can be found below
Examples of a organization match response can be found below