Integrating an External Entity Resolution Service
An entity resolution service determines when two records refer to the same real-world entity and assigns them a shared identifier. The MDM module provides a powerful and flexible interface for performing entity resolution within the repository, but it is not required if an external entity resolution service is available. External services are often very mature, with matching rules that have been extensively tested against live data feeds over years of operation. This page shows how the system can be integrated with such an external service.
The most common entity resolution service in healthcare is the Enterprise Master Patient Index (EMPI), which resolves patient records, so the following examples use Patient. The same principles apply to other resource types if a suitable external service exists.
Data Ingestion
Calls to an external entity resolution service can be integrated into the workflow by providing a custom interceptor that listens for the STORAGE_PRESTORAGE_RESOURCE_CREATED pointcut. This pointcut allows changes to be made to an incoming resource before it is stored in the repository. The same approach can be applied to updates of resources already in the repository by adding a hook for the STORAGE_PRESTORAGE_RESOURCE_UPDATED pointcut, if the EMPI identifier could be changed or removed during an update.
Step 1: Implement an interceptor
An interceptor class for calling an external entity resolution service will have the following structure.
package com.example;
@Service
public class EntityResolutionInterceptor {
private static final String EID_URI = "http://my-organization.org/namespaces/patient-eid";
@Hook(Pointcut.STORAGE_PRESTORAGE_RESOURCE_CREATED)
public void resolveEntity(IBaseResource theBaseResource) {
// We only need to process resource types that the external system is capable of handling
if (theBaseResource instanceof Patient patient) {
// If the resource already has an identifier with the EID system, there's no need for further processing
if (patient.getIdentifier().stream()
.map(Identifier::getSystem)
.noneMatch(EID_URI::equals)) {
// Make an appropriate call against the API of the external system
Identifier eidIdentifier = callEntityResolutionService();
// Update the incoming resource with the new identifier
patient.addIdentifier(eidIdentifier);
}
}
}
}
The details of calling the external service will vary. The administrator of that service should provide documentation of its API. In general, this integration involves the following steps.
- Marshall key demographic details into a custom data structure.
- Invoke the external service through an appropriate transport layer.
- Extract data from the response and update the FHIR resource.
- This update will always involve adding an instance of the EID to the resource.
- It may also involve updating other fields (e.g., ensuring current demographic information if the source system is out of date).
Step 2: Compile and deploy the interceptor
Place the JAR containing the custom interceptor in the customerlib directory to make it available on the module's classpath.
Step 3: Configure persistence module
Set the interceptor_bean_types property on the persistence module to the class name of the interceptor:
module.persistence.config.interceptor_bean_types=com.example.EntityResolutionInterceptor
Restart the persistence module for the new configuration to take effect.
The interceptor will now apply entity resolution to every incoming resource of the types it handles (Patient, in this example).
Minimizing calls to the external service
Calling the external entity resolution service may incur a cost from network latency or the service's processing speed, so avoid making the call unnecessarily. If the incoming resource already has an EID assigned, or is not of a resource type that the service can handle, the interceptor should return immediately without modifying the resource.
Data retrieval
Once the EID is in place, linked records can be retrieved in two ways: the built-in EID-based MDM expansion, which expands queries automatically but requires the MDM module, or manual EID queries, which work without the MDM module but put the linking burden on the caller.
EID-based MDM expansion in MATCH_ONLY mode
When MDM Rules include property eidSystems and MDM is configured in MATCH_ONLY mode, EID-based MDM expansion is supported by the operations that allow MDM expansion. These include search queries with MDM expansion parameters,
the Group bulk export operation, and the $everything operation.
In this configuration, MDM expansion is performed exclusively based on matching EIDs. Other MDM matching rules are not evaluated during MDM expansion in this configuration.
Configuration Requirements
To enable EID-based MDM expansion in MATCH_ONLY mode, you must:
- Set MDM Mode to
MATCH_ONLY - Define property
eidSystemsin your MDM Rules Definition - Enable MDM Search Expansion (
mdm.search_expansion.enabled)
For example, in your MDM Rules:
{
"version": "1",
"mdmTypes": ["Patient"],
"eidSystems": {
"Patient": "http://example.org/eid-system"
}
}
A resource type may also be given an array of EID systems, in which case a resource is expanded on any of them. See Using several EID systems for one resource type.
How EID-based Expansion Works
When a resource has an identifier with a system matching one of the configured eidSystems, MDM expansion operations will:
- Find all other resources of the same type that have an identifier with the same system and value
- Expand the operation to include those matched resources
Resources without the configured EID, or with non-matching EID values, are not expanded.
Expansion is a single step, not a chain. Where a resource type has several configured EID systems, records may carry different subsets of them, and expansion reaches only those sharing an EID with the record you start from.
Take three records for one person: one carrying only an MRN, one carrying only an NPI, and one carrying both. Expanding from the MRN-only record reaches the record carrying both, but not the NPI-only record - the starting record has no NPI to match on. Expanding from the record carrying both reaches all three.
Expansion is therefore complete only where every record for an entity carries the same EID system. Where that does not hold, expand from the most completely identified record, or query the EID values directly. Records are only ever missing from an expansion, never wrongly included: the search is qualified by EID system as well as value, so a value shared by two different systems does not pull in an unrelated record.
Important: In MATCH_ONLY mode with EID-based expansion:
- No Golden Resources or MDM Links are created
- Expansion is based solely on matching EID identifier values
- Other MDM matching rules (name matching, date of birth, etc.) are not evaluated
- Expansion follows one hop, so records sharing no EID with the starting record are not reached
- The MDM infrastructure (subscriptions, broker topics, consumers) is not used
Supported Operations
Search with :mdm Parameter
Use the :mdm search parameter modifier to expand reference searches based on EID matching.
Example:
GET [base]/Observation?patient:mdm=Patient/123
If Patient/123 has an EID value of "12345" with system http://example.org/eid-system, this search will return:
- All Observations for
Patient/123 - All Observations for any other Patient resources with EID
http://example.org/eid-system|12345
Without EID: If Patient/123 does not have the configured EID, only Observations for that specific patient are returned.
Non-matching EID: If Patient/123 has a different EID value than other patients, only Observations for that specific patient are returned.
Patient $everything Operation with _mdm Parameter
The $everything operation can be expanded to include resources for all patients with matching EIDs.
Example:
GET [base]/Patient/123/$everything?_mdm=true
If Patient/123 has an EID that matches other patients, the response will include:
- All matched Patient resources (including
Patient/123and all patients with matching EIDs) - All resources in the Patient compartment for each matched patient
Note: The _mdm parameter must be set to true to enable expansion.
Group Bulk Export with _mdm Parameter
Group export operations support EID-based expansion to include resources for all patients with matching EIDs.
Example:
POST [base]/Group/456/$export
Content-Type: application/fhir+json
{
"resourceType": "Parameters",
"parameter": [
{
"name": "_outputFormat",
"valueString": "application/fhir+ndjson"
},
{
"name": "_mdm",
"valueBoolean": true
},
{
"name": "_type",
"valueString": "Patient,Observation"
}
]
}
If Group/456 contains patients with EIDs, the export will include:
- All Patient resources in the group, plus all patients with matching EIDs
- All Observation resources (and other requested types) for all matched patients
Behavior:
- Each patient in the group is independently expanded based on their EID
- If a patient in the group has no EID, only that patient's resources are included
- If multiple patients in the group share the same EID, the expansion includes all patients with that EID (no duplicates)
Use Cases
EID-based MDM expansion in MATCH_ONLY mode is useful when:
- Your organization maintains a consistent enterprise identifier across systems
- You want to query across multiple patient records representing the same person
- You do not need full MDM Golden Record management
- You want to avoid the overhead of maintaining MDM Links and Golden Resources
- You need a lightweight solution for identity resolution based on enterprise identifiers
Performance Considerations
EID-based expansion in MATCH_ONLY mode is more efficient than full MATCH_AND_LINK mode because:
- No background processing is required for MDM Link creation
- No Message Broker infrastructure is needed
- No Subscription processing occurs
- Expansion queries directly search for matching EID values at query time
Manual EID queries
If the MDM module is not available, callers can perform the linking themselves by including the EID as a search parameter in every query.
GET http://my-server.com/Patient?identifier=http://my-organization.org/namespaces/patient-eid|1234
GET http://my-server.com/Observation?patient.identifier=http://my-organization.org/namespaces/patient-eid|1234
If the caller does not know the EID, it can be discovered by first querying for Patient by name or other demographic fields. Note that the search result bundle for this query may include unrelated patients who coincidentally share the queried demographic fields, and may omit relevant patient resources that share the EID but differ in their demographic details. For this reason, once the EID is discovered, the caller should make another call to obtain all relevant patient records. This can be done using the Patient query shown above, or by adding the parameter _include=Observation:patient to the query for Observations (or equivalently for any other resource type).
Once the data has been retrieved, it is the caller's responsibility to perform any merge or collate operations that are necessary to prepare the data for display or further processing.