- | targetId |
+ resourceId |
String |
1..1 |
@@ -232,11 +192,11 @@ The following request body could be used:
{
"resourceType": "Parameters",
"parameter": [ {
- "name": "personId",
- "valueString": "Person/123"
+ "name": "goldenResourceId",
+ "valueString": "Patient/123"
}, {
- "name": "targetId",
- "valueString": "Person/456"
+ "name": "resourceId",
+ "valueString": "Patient/456"
} ]
}
```
@@ -255,7 +215,7 @@ When the operation is successful, it returns the following `Parameters`:
## Update Link
-Use the `$empi-update-link` operation to change the `matchResult` update of an empi link. This operation takes the following parameters:
+Use the `$mdm-update-link` operation to change the `matchResult` update of an empi link. This operation takes the following parameters:
@@ -268,19 +228,19 @@ Use the `$empi-update-link` operation to change the `matchResult` update of an e
- | personId |
+ goldenResourceId |
String |
1..1 |
- The id of the Person resource.
+ The id of the Golden resource.
|
- | targetId |
+ resourceId |
String |
1..1 |
- The id of the Patient or Practitioner resource.
+ The id of the target resource.
|
@@ -310,10 +270,10 @@ The following request body could be used:
{
"resourceType": "Parameters",
"parameter": [ {
- "name": "personId",
- "valueString": "Person/123"
+ "name": "goldenResourceId",
+ "valueString": "Patient/123"
}, {
- "name": "targetId",
+ "name": "resourceId",
"valueString": "Patient/456"
}, {
"name": "matchResult",
@@ -322,13 +282,18 @@ The following request body could be used:
}
```
-The operation returns the updated `Person` resource. Note that this is the only way to modify EMPI-managed `Person` resources.
+The operation returns the updated `Patient` resource. Note that this is the only way to modify MDM-managed `Patient` resources.
## Merge Persons
-The `$empi-merge-persons` operation can be used to merge one Person resource with another. When doing this, you will need to decide which resource to merge from and which one to merge to. In most cases, fields will be merged (e.g. names, identifiers, and links will be the union of two). However when there is a conflict (e.g. birthday), fields in the toPerson will take precedence over fields in the fromPerson
+
+The `$mdm-merge-golden-resources` operation can be used to merge one Golden resource with another. When
+doing this, you will need to decide which resource to merge from and which one to merge to.
-After the merge is complete, `fromPerson.active` is set to `false`. Also, a new link with assurance level 4 (MANUAL MATCH) will be added pointing from the fromPerson to the toPerson.
+After the merge is complete, `fromGoldenResourceId` will be deactivated by assigning a metadata tag `REDIRECTED`.
This operation takes the following parameters:
@@ -343,19 +308,19 @@ This operation takes the following parameters:
- | fromPersonId |
+ fromGoldenResourceId |
String |
1..1 |
- The id of the Person resource to merge data from.
+ The id of the Golden Resource to merge data from.
|
- | toPersonId |
+ toGoldenResourceId |
String |
1..1 |
- The id of the Person to merge data into.
+ The id of the Golden Resource to merge data into.
|
@@ -366,7 +331,7 @@ This operation takes the following parameters:
Use an HTTP POST to the following URL to invoke this operation:
```url
-http://example.com/$empi-merge-persons
+http://example.com/$mdm-merge-golden-resources
```
The following request body could be used:
@@ -375,22 +340,24 @@ The following request body could be used:
{
"resourceType": "Parameters",
"parameter": [ {
- "name": "fromPersonId",
- "valueString": "Person/123"
+ "name": "fromGoldenResourceId",
+ "valueString": "Patient/123"
}, {
- "name": "toPersonId",
+ "name": "toGoldenResourceId",
"valueString": "Patient/128"
} ]
}
```
-This operation returns the merged Person resource.
+This operation returns the merged Patient resource.
-# Querying The EMPI
+# Querying The MDM
-When EMPI 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 resources that match it according to the matching rules.
+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.
For example, the following request may be submitted:
@@ -442,20 +409,28 @@ This might result in a response such as the following:
}
],
"birthDate": "2000-01-01"
+ },
+ "search": {
+ "extension": [{
+ "url": "http://hl7.org/fhir/StructureDefinition/match-grade",
+ "valueCode": "certain"
+ }],
+ "mode": "match",
+ "score": 0.9
}
}
]
}
```
-## Clearing EMPI Links
+## Clearing MDM Links
-The `$empi-clear` operation is used to batch-delete EMPI links and related persons from the database. This operation is meant to
-be used during the rules-tuning phase of the EMPI implementation so that you can quickly test your ruleset.
-It permits the user to reset the state of their EMPI system without manual deletion of all related links and Persons.
+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.
-After the operation is complete, all targeted EMPI links are removed from the system, and their related Person resources are deleted and expunged
-from the server.
+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.
This operation takes a single optional Parameter.
@@ -470,11 +445,11 @@ This operation takes a single optional Parameter.
- | resourceType |
+ targetType |
String |
0..1 |
- The target Resource type you would like to clear. Currently limited to Patient/Practitioner. If omitted, will operate over all links.
+ The target Resource type you would like to clear. If omitted, will operate over all links.
|
@@ -485,7 +460,7 @@ This operation takes a single optional Parameter.
Use an HTTP POST to the following URL to invoke this operation:
```url
-http://example.com/$empi-clear
+http://example.com/$mdm-clear
```
The following request body could be used:
@@ -494,13 +469,13 @@ The following request body could be used:
{
"resourceType": "Parameters",
"parameter": [ {
- "name": "resourceType",
+ "name": "targetType",
"valueString": "Patient"
} ]
}
```
-This operation returns the number of EMPI links that were cleared. The following is a sample response:
+This operation returns the number of MDM links that were cleared. The following is a sample response:
```json
{
@@ -512,13 +487,14 @@ This operation returns the number of EMPI links that were cleared. The following
}
```
-## Batch-creating EMPI Links
+## Batch-creating MDM Links
-Call the `$empi-submit` operation to submit patients and practitioners for EMPI processing. In the rules-tuning phase of your setup, you can use `$empi-submit` to apply EMPI rules across multiple Resources.
-An important thing to note is that this operation only submits the resources for processing. Actual EMPI processing is run asynchronously, and depending on the size
+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.
-After the operation is complete, all resources that matched the criteria will now have at least one empi 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.
This operation takes a single optional criteria parameter unless it is called on a specific instance.
@@ -549,9 +525,9 @@ This operation can be executed at the Server level, Resource level, or Instance
Use an HTTP POST to the following URL to invoke this operation with matching criteria:
```url
-http://example.com/$empi-submit
-http://example.com/Patient/$empi-submit
-http://example.com/Practitioner/$empi-submit
+http://example.com/$mdm-submit
+http://example.com/Patient/$mdm-submit
+http://example.com/Practitioner/$mdm-submit
```
The following request body could be used:
@@ -565,7 +541,7 @@ The following request body could be used:
} ]
}
```
-This operation returns the number of resources that were submitted for EMPI processing. The following is a sample response:
+This operation returns the number of resources that were submitted for MDM processing. The following is a sample response:
```json
{
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_empi/empi_rules.md b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_mdm/mdm_rules.md
similarity index 84%
rename from hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_empi/empi_rules.md
rename to hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_mdm/mdm_rules.md
index 823254f4b17..0106a332e66 100644
--- a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_empi/empi_rules.md
+++ b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_mdm/mdm_rules.md
@@ -1,10 +1,12 @@
# Rules
-HAPI EMPI 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` are `Patient`, `Practitioner`, and `*`. Use `*` if the criteria is identical across both resource types and you would like to apply it to both practitioners and patients.
+Note that in all the following configuration, valid options for `resourceType` include any supported resource, such as
+ `Patient`, `Practitioner`, and `*`. Use `*` if the
+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 EMPI rules json document:
+Here is an example of a full HAPI MDM rules json document:
```json
{
@@ -96,11 +98,20 @@ Here is an example of a full HAPI EMPI rules json document:
Here is a description of how each section of this document is configured.
### 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 "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 EMPI 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. 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.
+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).
+
+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.
```json
"candidateSearchParams": [ {
@@ -113,7 +124,9 @@ searches, first for all Patient resources that have the same given `AND` the sam
```
### candidateFilterSearchParams
-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.
+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.
+
```json
[ {
"resourceType" : "Patient",
@@ -386,7 +399,7 @@ The following algorithms are currently supported:
### matchResultMap
-These entries convert combinations of successful matchFields into an EMPI Match Result for overall matching of a given pair of resources. MATCH results are evaluated take precedence over POSSIBLE_MATCH results. If the incoming resource matches ALL of the named matchFields listed, then a new match link is created with the assigned matchResult (`MATCH` or `POSSIBLE_MATCH`).
+These entries convert combinations of successful matchFields into an MDM Match Result for overall matching of a given pair of resources. MATCH results are evaluated take precedence over POSSIBLE_MATCH results. If the incoming resource matches ALL of the named matchFields listed, then a new match link is created with the assigned matchResult (`MATCH` or `POSSIBLE_MATCH`).
```json
{
@@ -399,4 +412,4 @@ These entries convert combinations of successful matchFields into an EMPI Match
### eidSystem
-The external EID system that the HAPI EMPI system should expect to see on incoming Patient resources. Must be a valid URI. See [EMPI EID](/hapi-fhir/docs/server_jpa_empi/empi_eid.html) for details on how EIDs are managed by HAPI EMPI.
+The external EID system that the HAPI MDM system should expect to see on incoming Patient resources. Must be a valid URI. See [MDM EID](/hapi-fhir/docs/server_jpa_mdm/mdm_eid.html) for details on how EIDs are managed by HAPI MDM.
|
-
-
-
-
-
-
-
-
-
-## EMPI EID Update Scenarios
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_mdm/mdm.md b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_mdm/mdm.md
new file mode 100644
index 00000000000..ca68de66dc5
--- /dev/null
+++ b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_mdm/mdm.md
@@ -0,0 +1,52 @@
+# MDM Getting Started
+
+## Introduction
+
+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.
+
+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.
+
+## Working Example
+
+A complete working example of HAPI MDM can be found in the [JPA Server Starter](/hapi-fhir/docs/server_jpa/get_started.html) project. You may wish to browse its source to see how it is set up.
+
+## Overview
+
+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].
+
+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
+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
+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.
+
+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.
+
+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.
+
+## MDM Settings
+
+Follow these steps to enable MDM on the server:
+
+The [EmpiSettings](/hapi-fhir/apidocs/hapi-fhir-server-empi/ca/uhn/fhir/empi/rules/config/EmpiSettings.html) bean
+contains configuration settings related to MDM within the server. To enable MDM, the
+[setEnabled(boolean)](/hapi-fhir/apidocs/hapi-fhir-server-empi/ca/uhn/fhir/empi/rules/config/EmpiSettings.html#setEnabled(boolean))
+property should be enabled.
+
+See [MDM EID Settings](/hapi-fhir/docs/server_jpa_mdm/mdm_eid.html#empi-eid-settings) for a description of the EID-related settings.
diff --git a/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_mdm/mdm_details.md b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_mdm/mdm_details.md
new file mode 100644
index 00000000000..6d28d49a121
--- /dev/null
+++ b/hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_mdm/mdm_details.md
@@ -0,0 +1,115 @@
+# MDM Implementation Details
+
+This section describes details of how MDM functionality is implemented in HAPI FHIR.
+
+## Patient linking in FHIR
+
+Because HAPI MDM is implemented on the HAPI JPA Server, it uses the FHIR model to represent roles and links. The
+following illustration shows an example of how these links work.
+
+