Using EIDs in MDM Rule Definition
You can add the optional eidSystems field 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 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 takes 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.
For 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.
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 field 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."
}
]
}
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 Multithreaded Performance Considerations section in the main MDM documentation to learn how to enable it.