honeymoose
/
hapi-fhir
mirror of https://github.com/hapifhir/hapi-fhir.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Reviewed docs and added change entry

This commit is contained in:
Nick 2020-12-03 15:53:06 -05:00
parent 4352e0a61f
commit 499a68a093
6 changed files with 110 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/changelog/5_3_0/2177-remove-Person-references-to-support-MDM.yaml Normal file
View File

@ -0,0 +1,19 @@
---
type: add
issue: 2177
title: "Refactoring of the Enterprise Master Patient Index solution to a Master Data Management solution. The new MDM solution supports other FHIR resources where EMPI only allowed Person resource to be used. For example, if MDM is occurring on a patient, we will create a new Patient, and tag that patient as a Golden Record. This means that several things have changed:
<ul>
<li>Provider methods that pointed to type of Person are now server-level operations in which you specify a resource type.</li>
<li>Link updating and querying no longer rely on Person IDs, but instead on arbitrary resource ids, depending on the resource type you are referring to in MDM.</li>
<li>Change to the EMPI config to require a list of mdmTypes.</li>
</ul>
<br/>
Code-level changes include the following changes:
<ul>
<li>hapi-fhir-server-empi and hapi-fhir-jpaserver-empi Maven projects were renamed to hapi-fhir-server-mdm and hapi-fhir-jpaserver-mdm</li>
<li>All classes were refactored to use correct terms, e.g. Golden Resource in place of Person</li>
<li>Message channel was renamed from `empi` to `mdm`</li>
<li>Subscriptions were renamed to `mdm-RESOURCE_TYPE`, where RESOURCE_TYPE is an MDM type configured in mdmTypes section of the configuration file</li>
<li>Configuration file was renamed from empi-rules.json to mdm-rules.json</li>
<li>Log file was changed from empi-troubleshooting.log to mdm-troubleshooting.log</li>
</ul>"

33
hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_mdm/mdm.md
View File

@ -2,13 +2,9 @@
## Introduction ## Introduction
A Master Data Management (MDM) module allows for links to be created and maintained among FHIR resources. A Master Data Management (MDM) module allows for links to be created and maintained among FHIR resources. These links indicate the fact that different FHIR resources are known or believed to refer to the same actual (real world) resource. The links are created and updated using different combinations of automatic and manual linking.
These links indicate the fact that different FHIR resources are known or believed to refer to the same
actual (real world) resource. The links are created and updated using different combinations of automatic and
manual linking.
The real-world resource is referred to as the Golden Resource in this context. The resource believed to be a duplicate The real-world resource is referred to as the Golden Resource in this context. The resource believed to be a duplicate is said to be a target resource.
is said to be a target resource.
## Working Example ## Working Example
@ -16,37 +12,24 @@ A complete working example of HAPI MDM can be found in the [JPA Server Starter](
## Overview ## Overview
To get up and running with HAPI MDM, either enable it using the `hapi.properties` file in the JPA Server Starter, or To get up and running with HAPI MDM, either enable it using the `hapi.properties` file in the JPA Server Starter, or follow the instructions below to (enable it in HAPI FHIR directly)[#mdm-settings].
follow the instructions below to (enable it in HAPI FHIR directly)[#mdm-settings].
Once MDM is enabled, the next thing you will want to do is configure your [MDM Rules](/hapi-fhir/docs/server_jpa_mdm/mdm_rules.html) Once MDM is enabled, the next thing you will want to do is configure your [MDM Rules](/hapi-fhir/docs/server_jpa_mdm/mdm_rules.html)
HAPI MDM watches for incoming target resources and automatically links them to the appropriate Golden resources based HAPI MDM watches for incoming target resources and automatically links them to the appropriate Golden resources based on these rules. For example, if the rules indicate that any two patients with the same SSN, birthdate and first and last name are the same patients, then two different Patient resources with matching values for these attributes will automatically be linked to the same Golden Patient resource. If no existing resources match the incoming Patient, then a new Golden Patient resource will be created and linked to the incoming Patient.
on these rules. For example, if the rules indicate that any two patients with the same SSN, birthdate and first and
last name are the same patients, then two different Patient resources with matching values for these attributes will
automatically be linked to the same Golden Patient resource. If no existing resources match the incoming Patient, then
a new Golden Patient resource will be created and linked to the incoming Patient.
Based on how well two patients match, the MDM Rules may link the Patient to the Golden Patient as a MATCH or a Based on how well two patients match, the MDM Rules may link the Patient to the Golden Patient as a MATCH or a
POSSIBLE_MATCH. In the case of a POSSIBLE_MATCH, a user will need to later use POSSIBLE_MATCH. In the case of a POSSIBLE_MATCH, a user will need to later use [MDM Operations](/hapi-fhir/docs/server_jpa_mdm/mdm_operations.html) to either confirm the link as a MATCH, or mark the link as a NO_MATCH in which case HAPI MDM will create a new Person for them.
[MDM Operations](/hapi-fhir/docs/server_jpa_mdm/mdm_operations.html) to either confirm the link as a MATCH, or mark
the link as a NO_MATCH in which case HAPI MDM will create a new Person for them.
Another thing that can happen in the linking process is HAPI MDM can determine that two Patients resources may be Another thing that can happen in the linking process is HAPI MDM can determine that two Patients resources may be duplicates. In this case, it marks them as POSSIBLE_DUPLICATE and the user can use [MDM Operations](/hapi-fhir/docs/server_jpa_mdm/mdm_operations.html) to either merge the two Patients or mark them as NO_MATCH in which case HAPI MDM will know not to mark them as possible duplicates in the future.
duplicates. In this case, it marks them as POSSIBLE_DUPLICATE and the user can use
[MDM Operations](/hapi-fhir/docs/server_jpa_mdm/mdm_operations.html) to either merge the two Patients or mark them as
NO_MATCH in which case HAPI MDM will know not to mark them as possible duplicates in the future.
HAPI MDM keeps track of which links were automatically established vs manually verified. Manual links always take HAPI MDM keeps track of which links were automatically established vs manually verified. Manual links always take precedence over automatic links. Once a link for a patient has been manually verified, HAPI MDM won't modify or remove it.
precedence over automatic links. Once a link for a patient has been manually verified, HAPI MDM won't modify or remove it.
## MDM Settings ## MDM Settings
Follow these steps to enable MDM on the server: Follow these steps to enable MDM on the server:
The [MdmSettings](/hapi-fhir/apidocs/hapi-fhir-server-mdm/ca/uhn/fhir/mdm/rules/config/MdmSettings.html) bean The [MdmSettings](/hapi-fhir/apidocs/hapi-fhir-server-mdm/ca/uhn/fhir/mdm/rules/config/MdmSettings.html) bean
contains configuration settings related to MDM within the server. To enable MDM, the contains configuration settings related to MDM within the server. To enable MDM, the [setEnabled(boolean)](/hapi-fhir/apidocs/hapi-fhir-server-mdm/ca/uhn/fhir/mdm/rules/config/MdmSettings.html#setEnabled(boolean)) property should be enabled.
[setEnabled(boolean)](/hapi-fhir/apidocs/hapi-fhir-server-mdm/ca/uhn/fhir/mdm/rules/config/MdmSettings.html#setEnabled(boolean))
property should be enabled.
See [MDM EID Settings](/hapi-fhir/docs/server_jpa_mdm/mdm_eid.html#mdm-eid-settings) for a description of the EID-related settings. See [MDM EID Settings](/hapi-fhir/docs/server_jpa_mdm/mdm_eid.html#mdm-eid-settings) for a description of the EID-related settings.

71
hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_mdm/mdm_details.md
View File

@ -2,74 +2,54 @@
This section describes details of how MDM functionality is implemented in HAPI FHIR. This section describes details of how MDM functionality is implemented in HAPI FHIR.
## Patient linking in FHIR ## Resource linking in FHIR
Because HAPI MDM is implemented on the HAPI JPA Server, it uses the FHIR model to represent roles and links. The Because HAPI MDM is implemented on the HAPI JPA Server, it uses the FHIR model to represent links. The following illustration shows an example of how these links work.
following illustration shows an example of how these links work.
<a href="/hapi-fhir/docs/images/empi-links.svg"><img src="/hapi-fhir/docs/images/empi-links.svg" alt="MDM links" style="margin-left: 15px; margin-bottom: 15px; width: 500px;" /></a> <a href="/hapi-fhir/docs/images/empi-links.svg"><img src="/hapi-fhir/docs/images/empi-links.svg" alt="MDM links" style="margin-left: 15px; margin-bottom: 15px; width: 500px;" /></a>
There are several resources that are used: There are several resources that are used:
* Patient - Represents the record of a person who receives healthcare services * Target resource - Represents the record in being matched. For example, it can be a Patient resource who receives healthcare services and that should be mapped to a master record.
* Golden Patient - Represents a master record with links to one or more Patient resources that belong to the same real-world patient * Golden resource - Represents a master record that the target record should point to. For example, it can be a real-world patient Patient resource that multiple duplicate Patient resources point to.
# Automatic Linking # Automatic Linking
With MDM enabled, the default behavior of the MDM is to create a new Golden Patient record for every Patient that is With MDM enabled, the default behavior of the MDM is to create a new Golden record for every target record that is created such that there is a 1:1 relationship between them. Any relinking is then expected to be done manually via the [MDM Operations](/hapi-fhir/docs/server_jpa_mdm/mdm_operations.html).
created such that there is a 1:1 relationship between them. Any relinking is then expected to be done manually via the
[MDM Operations](/hapi-fhir/docs/server_jpa_mdm/mdm_operations.html).
In a typical configuration it is often desirable to have links be created automatically using matching rules. For example, In a typical configuration it is often desirable to have links created automatically using matching rules. For example, you might decide that if a Patient shares the same name, gender, and date of birth as another Patient, you have at least a little confidence that they are the same Patient.
you might decide that if a Patient shares the same name, gender, and date of birth as another Patient, you have at
least a little confidence that they are the same Patient.
This automatic linking is done via configurable matching rules that create links among Patients. Based on the strength This automatic linking is done via configurable matching rules that create links between Target record and Golden Record. Based on the strength of the match configured in these rules, the link will be set to either POSSIBLE_MATCH or MATCH.
of the match configured in these rules, the link will be set to either POSSIBLE_MATCH or MATCH.
It is important to note that before a resource is processed by MDM, it is first checked to ensure that it has at least It is important to note that before a resource is processed by MDM, it is first checked to ensure that it has at least one attribute that the MDM system cares about, as defined in the `mdm-rules.json` file. If the incoming resource has no such attributes, then MDM processing does not occur on it. In this case, no Golden Resource is created for this target resource. If in the future the target resource is updated to contain attributes the MDM system does concern itself with, it will be processed at that time.
one attribute that the MDM system cares about, as defined in the `mdm-rules.json` file. If the incoming resource has
no such attributes, then MDM processing does not occur on it. In this case, no Golden Resource Patient is created for
them. If in the future that Patient is updated to contain attributes the MDM system does concern itself with, it will
be processed at that time.
## Design ## Design
Below are some simplifying principles HAPI MDM follows to reduce complexity and ensure data integrity. Below are some simplifying principles HAPI MDM follows to reduce complexity and ensure data integrity.
1. When MDM is enabled on a HAPI FHIR server, any Patient resource in the repository that has the "hapi-mdm" tag is 1. When MDM is enabled on a HAPI FHIR server, any Golden Resource in the repository that has the "hapi-mdm" tag is considered read-only by the FHIR endpoint. These Golden Resources are managed exclusively by HAPI MDM. Users can only change them via [MDM Operations](/hapi-fhir/docs/server_jpa_mdm/mdm_operations.html). In most cases, users will indirectly change them by creating and updating the corresponding target resources.
considered read-only by the FHIR endpoint. These Golden Patient resources are managed exclusively by HAPI MDM. Users
can only change them via [MDM Operations](/hapi-fhir/docs/server_jpa_mdm/mdm_operations.html). In most cases, users
will indirectly change them by creating and updating target Patient resources. For the rest of this document, assume
"Golden Patient" refers to a "HAPI-MDM" tagged Patient resource.
1. Every Patient in the system has a MATCH link to at most one Golden Patient resource. 1. Every target resource in the system has a MATCH link to at most one Golden resource.
1. The only Patient resources in the system that do not have a MATCH link are those that have the 'NO-MDM' tag or 1. The only target resources in the system that do not have a MATCH link are those that have the 'NO-MDM' tag or those that have POSSIBLE_MATCH links pending review.
those that have POSSIBLE_MATCH links pending review.
1. The HAPI MDM rules define a single identifier system that holds the external enterprise id ("EID"). If a Patient has 1. The HAPI MDM rules define a single identifier system that holds the external enterprise id ("EID"). If a target resource has an external EID, then the Golden resource it links to always has the same EID. If a target resource has no EID when it arrives, a unique UUID will be assigned as that target resource's EID.
an external EID, then the Golden Patient it links to always has the same EID. If a patient has no EID when it arrives,
a unique UUID will be assigned as that Patient's EID.
1. A Golden Patient record can have both an internal EID (auto-created by HAPI), and an external EID (provided by an 1. A Golden Resource can have both an internal EID (auto-created by HAPI), and an external EID (provided by an
external system). external system).
1. Two different Golden Patient resources cannot have the same EID. 1. Two different Golden resources cannot have the same EID.
1. Patient resources are only ever compared to Golden Patient resources via this EID. For all other matches, Patient 1. Target resources are only ever compared to Golden resources via this EID.
resources are only ever compared to Patient resources.
## Links ## Links
1. HAPI MDM manages mdm-link records ("links") that link a Patient resource to a Golden Patient resource. When these are 1. HAPI MDM manages mdm-link records ("links") that link a target resource to a Golden resource. When these are
created/updated by matching rules, the links are marked as AUTO. When these links are changed manually, they are created/updated by matching rules, the links are marked as AUTO. When these links are changed manually, they are marked as MANUAL.
marked as MANUAL.
1. Once a link has been manually assigned as NO_MATCH or MATCH, the system will not change it. 1. Once a link has been manually assigned as NO_MATCH or MATCH, the system will not change it.
1. When a new Patient resource is created/updated it is then compared to all other Patient resources in the repository. 1. When a new target resource is created/updated it is then compared to all other target resources of the same type in the repository. The outcome of each of these comparisons is either NO_MATCH, POSSIBLE_MATCH or MATCH.
The outcome of each of these comparisons is either NO_MATCH, POSSIBLE_MATCH or MATCH.
1. HAPI MDM stores these extra link details in a table called `MPI_LINK`. 1. HAPI MDM stores these extra link details in a table called `MPI_LINK`.
@ -88,20 +68,17 @@ The outcome of each of these comparisons is either NO_MATCH, POSSIBLE_MATCH or M
### Possible rule match outcomes: ### Possible rule match outcomes:
When a new Patient resource is compared with all other resources of that type in the repository, there are four possible outcomes: When a new target resource is compared with all other resources of the same type in the repository, there are four possible outcomes:
<!--- <!---
All fields are copied from the Patient to the Golden Patient. All fields are copied from the Patient to the Golden Patient.
--> -->
* CASE 1: No MATCH and no POSSIBLE_MATCH outcomes -> a new Golden Patient resource is created and linked to that Patient as MATCH. * CASE 1: No MATCH and no POSSIBLE_MATCH outcomes -> a new Golden resource is created and linked to that target resource as MATCH. If the incoming resource has an EID, it is copied to the Golden resource. Otherwise a new UUID is generated and used as the internal EID.
If the incoming resource has an EID, it is copied to the Golden Patient. Otherwise a new UUID is generated and used as the internal EID.
* CASE 2: All of the MATCH Patient resources are already linked to the same Golden Patient -> a new Link is created between the new Patient and that Golden Patient and is set to MATCH. * CASE 2: All of the MATCH target resources are already linked to the same Golden Resource -> a new Link is created between the new target resource and that Golden Resource and is set to MATCH.
* CASE 3: The MATCH Patient resources link to more than one Golden Patient -> Mark all links as POSSIBLE_MATCH. All other Golden Patient resources are marked * CASE 3: The MATCH target resources link to more than one Golden resource -> Mark all links as POSSIBLE_MATCH. All other Golden resources are marked as POSSIBLE_DUPLICATE of this first Golden Resource. These duplicates are manually reviewed later and either merged or marked as NO_MATCH and the system will no longer consider them as a POSSIBLE_DUPLICATE going forward. POSSIBLE_DUPLICATE is the only link type that can have a Golden Resource as both the source and target of the link.
as POSSIBLE_DUPLICATE of this first Golden Patient. These duplicates are manually reviewed later and either merged or marked as NO_MATCH and the system will
no longer consider them as a POSSIBLE_DUPLICATE going forward. POSSIBLE_DUPLICATE is the only link type that can have a Golden Patient as both the source and target of the link.
* CASE 4: Only POSSIBLE_MATCH outcomes -> In this case, new POSSIBLE_MATCH links are created and await manual reassignment to either NO_MATCH or MATCH. * CASE 4: Only POSSIBLE_MATCH outcomes -> In this case, new POSSIBLE_MATCH links are created and await manual reassignment to either NO_MATCH or MATCH.
@ -110,6 +87,6 @@ no longer consider them as a POSSIBLE_DUPLICATE going forward. POSSIBLE_DUPLICAT
When MDM is enabled, the HAPI FHIR JPA Server does the following things on startup: When MDM is enabled, the HAPI FHIR JPA Server does the following things on startup:
1. It enables the MESSAGE subscription type and starts up the internal subscription engine. 1. It enables the MESSAGE subscription type and starts up the internal subscription engine.
1. It creates two MESSAGE subscriptions, called 'mdm-patient' and 'mdm-practitioner' that match all incoming MDM managed resources and send them to an internal queue called "mdm". The JPA Server listens to this queue and links incoming resources to the appropriate golden resources. 1. It creates MESSAGE subscriptions for each resource type prefixed with 'mdm-'. For example, if MDM supports Patient and Practitioner resource, two subscriptions, called 'mdm-patient' and 'mdm-practitioner' that match all incoming MDM managed resources and send them to an internal queue called "mdm". The JPA Server listens to this queue and links incoming resources to the appropriate golden resources.
1. The [MDM Operations](/hapi-fhir/docs/server_jpa_mdm/mdm_operations.html) are registered with the server. 1. The [MDM Operations](/hapi-fhir/docs/server_jpa_mdm/mdm_operations.html) are registered with the server.
1. It registers a new dao interceptor that restricts access to MDM managed Golden Patient records. 1. It registers a new dao interceptor that restricts access to MDM managed Golden Resource records.

9
hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_mdm/mdm_eid.md
View File

@ -1,9 +1,6 @@
# MDM Enterprise Identifiers # MDM Enterprise Identifiers
An Enterprise Identifier (EID) is a unique identifier that can be attached to target resources. Each implementation is An Enterprise Identifier (EID) is a unique identifier that can be attached to target resources. Each implementation is expected to use exactly one EID system for incoming resources, defined in the MDM Rules file. If a target resource with a valid EID is submitted, that EID will be copied over to the Golden resource that was matched. In the case that the incoming target resource had no EID assigned, an internal EID will be created for it. There are thus two classes of EID:
expected to use exactly one EID system for incoming resources, defined in the MDM Rules file. If a Patient with a valid
EID is submitted, that EID will be copied over to the Golden Patient resource that was matched. In the case that the
incoming Patient had no EID assigned, an internal EID will be created for it. There are thus two classes of EID:
* Internal EIDs, created by HAPI-MDM, and * Internal EIDs, created by HAPI-MDM, and
* External EIDs, provided by the submitted resources. * External EIDs, provided by the submitted resources.
@ -18,9 +15,7 @@ contains two EID related settings. Both are enabled by default.
## MDM EID Scenarios ## MDM EID Scenarios
MDM EID management follows a complex set of rules to link related Patient records via their Enterprise Id. The following MDM EID management follows a complex set of rules to link related target records via their Enterprise Id. The following diagrams outline how EIDs are replicated from Patient resources to their linked Golden Patient resources under various scenarios according to the values of the EID Settings.
diagrams outline how EIDs are replicated from Patient resources to their linked Golden Patient resources under various
scenarios according to the values of the EID Settings.
## MDM EID Create Scenarios ## MDM EID Create Scenarios

61
hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_mdm/mdm_operations.md
View File

@ -84,7 +84,7 @@ This operation returns a `Parameters` resource that looks like the following:
"name": "goldenResourceId", "name": "goldenResourceId",
"valueString": "Person/123" "valueString": "Person/123"
}, { }, {
"name": "resourceId", "name": "targetResourceId",
"valueString": "Patient/456" "valueString": "Patient/456"
}, { }, {
"name": "matchResult", "name": "matchResult",
@ -96,7 +96,7 @@ This operation returns a `Parameters` resource that looks like the following:
"name": "eidMatch", "name": "eidMatch",
"valueBoolean": false "valueBoolean": false
}, { }, {
"name": "newPerson", "name": "hadToCreateNewResource",
"valueBoolean": false "valueBoolean": false
}, { }, {
"name": "score", "name": "score",
@ -131,7 +131,7 @@ This operation returns `Parameters` similar to `$mdm-query-links`:
"name": "goldenResourceId", "name": "goldenResourceId",
"valueString": "Person/123" "valueString": "Person/123"
}, { }, {
"name": "resourceId", "name": "targetResourceId",
"valueString": "Person/456" "valueString": "Person/456"
}, { }, {
"name": "matchResult", "name": "matchResult",
@ -254,7 +254,7 @@ Use the `$mdm-update-link` operation to change the `matchResult` update of an md
</tbody> </tbody>
</table> </table>
Mdm links updated in this way will automatically have their `linkSource` set to `MANUAL`. MDM links updated in this way will automatically have their `linkSource` set to `MANUAL`.
### Example ### Example
@ -264,7 +264,7 @@ Use an HTTP POST to the following URL to invoke this operation:
http://example.com/$mdm-update-link http://example.com/$mdm-update-link
``` ```
The following request body could be used: Any supported MDM type can be used. The following request body shows how to update link on the Patient resource type:
```json ```json
{ {
@ -282,7 +282,7 @@ The following request body could be used:
} }
``` ```
The operation returns the updated `Patient` resource. Note that this is the only way to modify MDM-managed `Patient` resources. The operation returns the updated Golden Resource. For the query above `Patient` resource will be returned. Note that this is the only way to modify MDM-managed Golden Resources.
## Merge Persons ## Merge Persons
@ -349,15 +349,15 @@ The following request body could be used:
} }
``` ```
This operation returns the merged Patient resource. This operation returns the merged Golden Resource (`toGoldenResourceId`).
# Querying The MDM # Querying The MDM
## Querying the Patient Resource
When MDM is enabled, the [$match operation](http://hl7.org/fhir/patient-operation-match.html) will be enabled on the JPA Server. When MDM is enabled, the [$match operation](http://hl7.org/fhir/patient-operation-match.html) will be enabled on the JPA Server.
This operation allows a Patient resource to be submitted to the endpoint, and the system will attempt to find and return any Patient This operation allows a Patient resource to be submitted to the endpoint, and the system will attempt to find and return any Patient resources that match it according to the matching rules. The response includes a search score field that is calculated by averaging the number of matched rules against total rules checked for the Patient resource. Appropriate match grade extension is also included.
resources that match it according to the matching rules. The response includes a search score field that is calculated by averaging the
number of matched rules against total rules checked for the Patient resource. Appropriate match grade extension is also included.
For example, the following request may be submitted: For example, the following request may be submitted:
@ -423,14 +423,37 @@ This might result in a response such as the following:
} }
``` ```
## Querying the Other Supported MDM Resources via `/$mdm-match`
Query operations on any other supported MDM type is also allowed. This operation will Patient resources that match it according to the matching rules. The response includes a search score field that is calculated by averaging the number of matched rules against total rules checked for the Patient resource. Appropriate match grade extension is also included.
The request below may be submitted to search for `Orgaization` in case it defined as a supported MDM type:
```http
POST /Organization/$mdm-match
Content-Type: application/fhir+json; charset=UTF-8
{
"resourceType":"Parameters",
"parameter": [
{
"name":"resource",
"resource": {
"resourceType":"Orgaization",
"name": "McMaster Family Practice"
}
}
]
}
```
MDM will respond with the appropriate resource bundle.
## Clearing MDM Links ## Clearing MDM Links
The `$mdm-clear` operation is used to batch-delete MDM links and related persons from the database. This operation is meant to The `$mdm-clear` operation is used to batch-delete MDM links and related persons from the database. This operation is meant to be used during the rules-tuning phase of the MDM implementation so that you can quickly test your ruleset. It permits the user to reset the state of their MDM system without manual deletion of all related links and golden resources.
be used during the rules-tuning phase of the MDM implementation so that you can quickly test your ruleset.
It permits the user to reset the state of their MDM system without manual deletion of all related links and golden resources.
After the operation is complete, all targeted MDM links are removed from the system, and their related Golden Resources are After the operation is complete, all targeted MDM links are removed from the system, and their related Golden Resources are deleted and expunged from the server.
deleted and expunged from the server.
This operation takes a single optional Parameter. This operation takes a single optional Parameter.
@ -489,10 +512,7 @@ This operation returns the number of MDM links that were cleared. The following
## Batch-creating MDM Links ## Batch-creating MDM Links
Call the `$mdm-submit` operation to submit patients and practitioners for MDM processing. In the rules-tuning phase of your setup, you can Call the `$mdm-submit` operation to submit patients and practitioners for MDM processing. In the rules-tuning phase of your setup, you can use `$mdm-submit` to apply MDM rules across multiple Resources. An important thing to note is that this operation only submits the resources for processing. Actual MDM processing is run asynchronously, and depending on the size of the affected bundle of resources, may take some time to complete.
use `$mdm-submit` to apply MDM rules across multiple Resources. An important thing to note is that this operation only submits the
resources for processing. Actual MDM processing is run asynchronously, and depending on the size
of the affected bundle of resources, may take some time to complete.
After the operation is complete, all resources that matched the criteria will now have at least one MDM link attached to them. After the operation is complete, all resources that matched the criteria will now have at least one MDM link attached to them.
@ -553,8 +573,7 @@ This operation returns the number of resources that were submitted for MDM proce
} }
``` ```
This operation can also be done at the Instance level. When this is the case, the operations accepts no parameters. This operation can also be done at the Instance level. When this is the case, the operations accepts no parameters. The following are examples of Instance level POSTs, which require no parameters.
The following are examples of Instance level POSTs, which require no parameters.
```url ```url
http://example.com/Patient/123/$mdm-submit http://example.com/Patient/123/$mdm-submit

35
hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_mdm/mdm_rules.md
View File

@ -2,8 +2,7 @@
HAPI MDM rules are defined in a single json document. HAPI MDM rules are defined in a single json document.
Note that in all the following configuration, valid options for `resourceType` include any supported resource, such as Note that in all the following configuration, valid options for `resourceType` include any supported resource, such as `Organization`, `Patient`, `Practitioner`, and `*`. Use `*` if the
`Patient`, `Practitioner`, and `*`. Use `*` if the
criteria is identical across both resource types and you would like to apply it to all resources. criteria is identical across both resource types and you would like to apply it to all resources.
Here is an example of a full HAPI MDM rules json document: Here is an example of a full HAPI MDM rules json document:
@ -11,7 +10,7 @@ Here is an example of a full HAPI MDM rules json document:
```json ```json
{ {
"version": "1", "version": "1",
"mdmTypes" : ["Patient", "Practitioner"], "mdmTypes" : ["Organization", "Patient", "Practitioner"],
"candidateSearchParams": [ "candidateSearchParams": [
{ {
"resourceType": "Patient", "resourceType": "Patient",
@ -83,7 +82,15 @@ Here is an example of a full HAPI MDM rules json document:
"algorithm": "JARO_WINKLER", "algorithm": "JARO_WINKLER",
"matchThreshold": 0.80 "matchThreshold": 0.80
} }
},
{
"name": "org-name",
"resourceType": "Organization",
"resourcePath": "name",
"matcher": {
"algorithm": "STRING"
} }
},
], ],
"matchResultMap": { "matchResultMap": {
"firstname-meta,lastname-meta,birthday": "MATCH", "firstname-meta,lastname-meta,birthday": "MATCH",
@ -91,7 +98,8 @@ Here is an example of a full HAPI MDM rules json document:
"firstname-jaro,lastname-jaro,birthday": "POSSIBLE_MATCH", "firstname-jaro,lastname-jaro,birthday": "POSSIBLE_MATCH",
"firstname-jaro,lastname-jaro,phone": "POSSIBLE_MATCH", "firstname-jaro,lastname-jaro,phone": "POSSIBLE_MATCH",
"lastname-jaro,phone,birthday": "POSSIBLE_MATCH", "lastname-jaro,phone,birthday": "POSSIBLE_MATCH",
"firstname-jaro,phone,birthday": "POSSIBLE_MATCH" "firstname-jaro,phone,birthday": "POSSIBLE_MATCH",
"org-name": "MATCH"
} }
} }
``` ```
@ -100,19 +108,9 @@ Here is a description of how each section of this document is configured.
### candidateSearchParams ### candidateSearchParams
These define fields which must have at least one exact match before two resources are considered for matching. This is like a list of These define fields which must have at least one exact match before two resources are considered for matching. This is like a list of "pre-searches" that find potential candidates for matches, to avoid the expensive operation of running a match score calculation on all resources in the system. E.g. you may only wish to consider matching two Patients if they either share at least one identifier in common or have the same birthday or the same phone number. The HAPI FHIR server executes each of these searches separately and then takes the union of the results, so you can think of these as `OR` criteria that cast a wide net for potential candidates. In some MDM systems, these "pre-searches" are called "blocking" searches (since they identify "blocks" of candidates that will be searched for matches).
"pre-searches" that find potential candidates for matches, to avoid the expensive operation of running a match score calculation on all
resources in the system. E.g. you may only wish to consider matching two Patients if they either share at least one identifier in common
or have the same birthday or the same phone number. The HAPI FHIR server executes each of these searches separately and then takes the
union of the results, so you can think of these as `OR` criteria that cast a wide net for potential candidates. In some MDM systems,
these "pre-searches" are called "blocking" searches (since they identify "blocks" of candidates that will be searched for matches).
If a list of searchParams is specified in a given candidateSearchParams item, then these search parameters are treated as `AND` parameters. If a list of searchParams is specified in a given candidateSearchParams item, then these search parameters are treated as `AND` parameters. In the following candidateSearchParams definition, hapi-fhir will extract given name, family name and identifiers from the incoming Patient and perform two separate searches, first for all Patient resources that have the same given `AND` the same family name as the incoming Patient, and second for all Patient resources that share at least one identifier as the incoming Patient. Note that if the incoming Patient was missing any of these searchParam values, then that search would be skipped. E.g. if the incoming Patient had a given name but no family name, then only a search for matching identifiers would be performed.
In the following candidateSearchParams definition, hapi-fhir will extract given name, family name and identifiers from the incoming Patient
and perform two separate searches, first for all Patient resources that have the same given `AND` the same family name as the incoming
Patient, and second for all Patient resources that share at least one identifier as the incoming Patient. Note that if the incoming Patient
was missing any of these searchParam values, then that search would be skipped. E.g. if the incoming Patient had a given name but no
family name, then only a search for matching identifiers would be performed.
```json ```json
"candidateSearchParams": [ { "candidateSearchParams": [ {
@ -125,8 +123,7 @@ Patient, and second for all Patient resources that share at least one identifier
``` ```
### candidateFilterSearchParams ### candidateFilterSearchParams
When searching for match candidates, only resources that match this filter are considered. E.g. you may wish to only search for Patients When searching for match candidates, only resources that match this filter are considered. E.g. you may wish to only search for Patients for which active=true.
for which active=true.
```json ```json
[ { [ {
@ -406,7 +403,7 @@ These entries convert combinations of successful matchFields into an MDM Match R
{ {
"matchResultMap": { "matchResultMap": {
"firstname-meta,lastname-meta,birthday": "MATCH", "firstname-meta,lastname-meta,birthday": "MATCH",
"firstname-jaro,lastname-jaro,birthday": "POSSIBLE_MATCH", "firstname-jaro,lastname-jaro,birthday": "POSSIBLE_MATCH"
} }
} }
``` ```