You can add the optional eidSystems property in your MDM Rule Definiton configuration to tell the MDM module which identifiers can be expected and used as unique identifier on incoming resources,
by providing the identifier system, or systems, to be used on each resource type.
This causes the MDM module to process newly created or updated incoming resources in a different way, as described below.
The generated Golden Records could be created or updated in a different way too, as it makes the MDM module take into account these properties from the MDM Configuration:
Prevent modification of External EIDsPrevent multiple EIDs from existing simultaneously on a target resourceWhen enabled, these properties can act as safeguards on the FHIR resources, including on the Golden Records created. By default, both properties are enabled.
Tips: a Golden Record is a uniquely identified FHIR resource that generally keeps the aggregated values of its linked source resources. They are created with a
meta.tagentry composed ofhttp://hapifhir.io/fhir/NamingSystem/mdm-record-statussystem andGOLDEN_RECORDcode to make them easier to find and manage. They cannot be added, updated or deleted using the usual operations. Aside from that, they are generally treated like any other resources.
eidSystems definitionFor example, in this extract of a sample MDM Rule Definition:
{
"eidSystems": {
"Practitioner": "http://hl7.org/fhir/sid/us-npi",
"Patient": "http://hl7.org/fhir/sid/us-ssn"
}
}
The MDM module would then look for these identifiers in the incoming resources:
http://hl7.org/fhir/sid/us-npi system in the identifier list of Practitioner resources,http://hl7.org/fhir/sid/us-ssn system in the identifier list of Patient resources.The targeted identifier value would then be used to uniquely identify incoming resources during MDM process.
A resource type may have more than one identifier that is unique and reliable enough to serve as an EID. A hospital network may recognise both a Medical Record Number and a National Provider Identifier, for instance. To use several, give an array of systems instead of a single one:
{
"eidSystems": {
"Patient": [
"http://example.org/fhir/sid/mrn",
"http://example.org/fhir/sid/npi"
],
"Practitioner": "http://hl7.org/fhir/sid/us-npi"
}
}
Both forms may be mixed in one definition.
An incoming resource is linked to a Golden Record if any of its EIDs match, so configuring several systems widens the set of records that can be resolved directly rather than through the matching phase.
The order of the systems matters. The first one listed for a resource type is its primary system, and is the one used wherever a single EID has to be chosen for a resource.
Because records arrive in whatever order the source systems send them, an MRN and an NPI belonging to the same real-world person may each have produced their own Golden Record before any resource arrived carrying both.
When a resource does arrive carrying both, the MDM module does not guess which Golden Record is correct.
It creates a POSSIBLE_MATCH link to each of them, and a POSSIBLE_DUPLICATE link between the two Golden Records, so that a data steward can review them and merge them if appropriate. See deduplication for how possible duplicates are resolved.
Prevent multiple EIDs from existing simultaneously on a target resource is applied per EID system. A resource may carry one EID from each configured system - one MRN and one NPI, say - but may not carry two EIDs issued by the same system. A resource type with a single configured system therefore allows at most one EID in total.
A Golden Record accumulates the EIDs of the source resources linked to it, and gains them as those resources arrive. A Golden Record created from a resource carrying only an MRN acquires the NPI as soon as a resource carrying both is matched to it, and from that point a later resource carrying only the NPI resolves to the same Golden Record. This applies on create and on update alike.
Important note: declaring eidSystems doesn't make it mandatory for the EID to be present in the incoming resource identifier list. No resource will be rejected if the EID is not present. The MDM module will still process these resources, but it will simply use the usual process for them.
Tips: if the EID should be made mandatory in some resources, custom Validation could be used to achieve that.
Firstly, having eidSystems property in the MDM Rule Definition changes the searches done during the first phase of MDM processing, when finding candidate resources for the matching phase.
Instead of trying to find candidate resources immediately, the MDM module will first try to find an existing Golden Record having the targeted unique identifier.
It means that with the above sample eidSystems value, for an incoming Practitioner resource like:
{
"resourceType": "Practitioner",
"identifier": [
{
"system": "http://hl7.org/fhir/sid/us-npi",
"value": "0123456789"
}
]
}
It would first do the equivalent search, using _tag and identifier SearchParameter:
http://localhost:8000/Practitioner
and look at the result, which might affect the usual MDM processing done in a couple of ways.
For newly created incoming resources, if a Golden Record is found then the MDM module will create a MATCH link between the Golden Record found and the incoming resource. The MDM processing of the incoming resource will then stop as nothing else needs to be done afterward, no further candidate searches and no matching phase. It makes the MDM processing faster.
In other scenarios, the MDM module will follow a complex set of rules to determine how the incoming resource will be linked and how the linked Golden Record will be modified, taking into account the Prevent modification of External EIDs and Prevent multiple EIDs from existing simultaneously on a target resource enabled properties in the MDM Configuration.
See EID management configuration options for additional details about these scenarios.
Important note: if the MDM processing of an incoming resource is rejected due to Prevent modification of External EIDs and Prevent multiple EIDs from existing simultaneously on a target resource enabled properties because it would put a Golden Record into an invalid state, the incoming resource would still be saved in the FHIR repository and only the MDM processing would be stopped. No link would be created and no Golden Record would be added or modified for the incoming resource.
However, if a create or update resource operation is called and directly fails to comply with one of these enabled properties, by doing either
identifier listfor example, then the incoming resource would not be saved in the FHIR repository nor would be further analyzed by the MDM module.
In these cases, an explicit 403 Forbidden error would also be returned for the call:
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "processing",
"diagnostics": "HAPI-0763: While running with EID updates disabled, EIDs may not be updated on source resources"
}
]
}
or
{
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "error",
"code": "processing",
"diagnostics": "HAPI-0766: While running with multiple EIDs disabled, source resources may have at most one EID per system, but 2 were found for system http://hl7.org/fhir/sid/us-ssn."
}
]
}
It is easier to understand how the MDM processes are affected by EIDs when the MDM Troubleshooting Log is enabled. So we recommend to enable it temporarily when testing MDM, as the log entries may provide useful insights.
Using EIDs may also permit to enable multithreading with MDM in some configurations.
See the Multithreaded Performance Considerations section in the Golden Record MDM documentation to learn how to enable it.
You are about to leave the Smile Digital Health documentation and navigate to the Open Source HAPI-FHIR Documentation.