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

Docs - first pass

This commit is contained in:
Nick Goupinets 2020-11-17 17:22:06 -05:00
parent 805d5b1d6c
commit f470c343c5
5 changed files with 238 additions and 190 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_empi/empi.md
View File

@ -1,35 +1,52 @@
# EMPI Getting Started
# MDM Getting Started
## Introduction
An Enterprise Master Patient Index (EMPI) allows for links to be created and maintained between different Patient and/or Practitioner resources. These links are used to indicate the fact that different Patient/Practitioner resources are known or believed to refer to the same actual (real world) person.
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 are created and updated using different combinations of automatic linking and manual linking.
Note: This documentation describes EMPI for Patient resources. The same information applies for Practitioner resources. You can substitute "Practitioner" for "Patient" anywhere it appears in this documentation.
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 EMPI 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.
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 EMPI, 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)[#empi-settings].
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)[#empi-settings].
Once EMPI is enabled, the next thing you will want to do is configure your [EMPI Rules](/hapi-fhir/docs/server_jpa_empi/empi_rules.html)
Once MDM is enabled, the next thing you will want to do is configure your [MDM Rules](/hapi-fhir/docs/server_jpa_empi/empi_rules.html)
HAPI EMPI watches for incoming Patient resources and automatically links them to Person 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 person, then two different Patient resources with matching values for these attributes will automatically be linked to the same Person resource. If no existing resources match the incoming Patient, then a new Person resource will be created and linked to the incoming Patient.
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 EMPI Rules may link the Patient to the Person as a MATCH or a POSSIBLE_MATCH. In the case of a POSSIBLE_MATCH, a user will need to later use [EMPI Operations](/hapi-fhir/docs/server_jpa_empi/empi_operations.html) to either confirm the link as a MATCH, or mark the link as a NO_MATCH in which case HAPI EMPI will create a new Person for them.
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_empi/empi_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 EMPI can determine that two Person resources may be duplicates. In this case, it marks them as POSSIBLE_DUPLICATE and the user can use [EMPI Operations](/hapi-fhir/docs/server_jpa_empi/empi_operations.html) to either merge the two Persons or mark them as NO_MATCH in which case HAPI EMPI will know not to mark them as possible duplicates in the future.
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_empi/empi_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 EMPI 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 EMPI won't modify or remove it.
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.
## EMPI Settings
## MDM Settings
Follow these steps to enable EMPI on the server:
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 EMPI within the server. To enable EMPI, the [setEnabled(boolean)](/hapi-fhir/apidocs/hapi-fhir-server-empi/ca/uhn/fhir/empi/rules/config/EmpiSettings.html#setEnabled(boolean)) property should be enabled.
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 [EMPI EID Settings](/hapi-fhir/docs/server_jpa_empi/empi_eid.html#empi-eid-settings) for a description of the EID-related settings.
See [MDM EID Settings](/hapi-fhir/docs/server_jpa_empi/empi_eid.html#empi-eid-settings) for a description of the EID-related settings.

94
hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_empi/empi_details.md
View File

@ -1,81 +1,115 @@
# EMPI Implementation Details
# MDM Implementation Details
This section describes details of how EMPI functionality is implemented in HAPI FHIR.
This section describes details of how MDM functionality is implemented in HAPI FHIR.
## Person linking in FHIR
## Patient linking in FHIR
Because HAPI EMPI 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.
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.
<a href="/hapi-fhir/docs/images/empi-links.svg"><img src="/hapi-fhir/docs/images/empi-links.svg" alt="EMPI 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:
* Patient - Represents the record of a person who receives healthcare services
* Person - Represents a master record with links to one or more Patient and/or Practitioner resources that belong to the same person
* Golden Patient - Represents a master record with links to one or more Patient resources that belong to the same real-world patient
# Automatic Linking
With EMPI enabled, the default behavior of the EMPI is to create a new Person record for every Patient that is created such that there is a 1:1 relationship between them. Any relinking is then expected to be done manually via the [EMPI Operations](/hapi-fhir/docs/server_jpa_empi/empi_operations.html).
With MDM enabled, the default behavior of the MDM is to create a new Golden Patient record for every Patient 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_empi/empi_operations.html).
In a typical configuration it is often desirable to have links be 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 Person.
In a typical configuration it is often desirable to have links be 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.
This automatic linking is done via configurable matching rules that create links between Patients and Persons. Based on the strength of the match configured in these rules, the link will be set to either POSSIBLE_MATCH or MATCH.
This automatic linking is done via configurable matching rules that create links among Patients. Based on the strength
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 EMPI, it is first checked to ensure that it has at least one attribute that the EMPI system cares about, as defined in the `empi-rules.json` file. If the incoming resource has no such attributes, then EMPI processing does not occur on it. In this case, no Person is created for them. If in the future that Patient is updated to contain attributes the EMPI system does concern itself with, it will be processed at that time.
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 `empi-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
Below are some simplifying principles HAPI EMPI 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 EMPI is enabled on a HAPI FHIR server, any Person resource in the repository that has the "hapi-empi" tag is considered read-only by the FHIR endpoint. These Person resources are managed exclusively by HAPI EMPI. Users can only change them via [EMPI Operations](/hapi-fhir/docs/server_jpa_empi/empi_operations.html). In most cases, users will indirectly change them by creating and updating Patient and Practitioner ("Patient") resources. For the rest of this document, assume "Person" refers to a "hapi-empi" tagged Person resource.
1. When MDM is enabled on a HAPI FHIR server, any Patient resource in the repository that has the "hapi-empi" tag is
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_empi/empi_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-empi" tagged Patient resource.
1. Every Patient in the system has a MATCH link to at most one Person resource.
1. Every Patient in the system has a MATCH link to at most one Golden Patient resource.
1. The only Patient resources in the system that do not have a MATCH link are those that have the 'no-empi' tag or those that have POSSIBLE_MATCH links pending review.
1. The only Patient resources in the system that do not have a MATCH link are those that have the 'no-empi' tag or
those that have POSSIBLE_MATCH links pending review.
1. The HAPI EMPI rules define a single identifier system that holds the external enterprise id ("EID"). If a Patient has an external EID, then the Person 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 Person's EID.
1. The HAPI MDM rules define a single identifier system that holds the external enterprise id ("EID"). If a Patient has
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 Person can have both an internal EID(auto-created by HAPI), and an external EID (provided by an external system).
1. A Golden Patient record can have both an internal EID (auto-created by HAPI), and an external EID (provided by an
external system).
1. Two different Person resources cannot have the same EID.
1. Two different Golden Patient resources cannot have the same EID.
1. Patient resources are only ever compared to Person resources via this EID. For all other matches, Patient resources are only ever compared to Patient resources and Practitioner resources are only ever compared to Practitioner resources.
1. Patient resources are only ever compared to Golden Patient resources via this EID. For all other matches, Patient
resources are only ever compared to Patient resources.
## Links
1. HAPI EMPI manages empi-link records ("links") that link a Patient resource to a Person resource. When these are created/updated by matching rules, the links are marked as AUTO. When these links are changed manually, they are marked as MANUAL.
1. HAPI MDM manages mdm-link records ("links") that link a Patient resource to a Golden Patient resource. When these are
created/updated by matching rules, the links are marked as AUTO. When these links are changed manually, they are
marked as MANUAL.
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. The outcome of each of these comparisons is either NO_MATCH, POSSIBLE_MATCH or MATCH.
1. When a new Patient resource is created/updated it is then compared to all other Patient resources in the repository.
The outcome of each of these comparisons is either NO_MATCH, POSSIBLE_MATCH or MATCH.
1. Whenever a MATCH link is established between a Patient resource and a Person resource, that Patient is always added to that Person resource links. All MATCH links have corresponding Person resource links and all Person resource links have corresponding MATCH empi-link records. You can think of the fields of the empi-link records as extra meta-data associated with each Person.link.target.
1. HAPI MDM stores these extra link details in a table called `MPI_LINK`.
1. HAPI EMPI stores these extra link details in a table called `MPI_LINK`.
<!---
1. Whenever a MATCH link is established between a Patient resource and a Golden Patient resource, that Patient is always
added to that Golden Patient resource links. All MATCH links have corresponding Golden Patient resource links and all
Golden Patient resource links have corresponding MATCH empi-link records. You can think of the fields of the empi-link
records as extra meta-data associated with each Person.link.target.
1. Each record in the `MPI_LINK` table corresponds to a `link.target` entry on a Person resource unless it is a NO_MATCH record. HAPI EMPI uses the following convention for the Person.link.assurance level:
1. Each record in the `MPI_LINK` table corresponds to a `link.target` entry on a Person resource unless it is a NO_MATCH record. HAPI MDM uses the following convention for the Person.link.assurance level:
1. Level 1: POSSIBLE_MATCH
1. Level 2: AUTO MATCH
1. Level 3: MANUAL MATCH
1. Level 4: GOLDEN RECORD
-->
### 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:
* CASE 1: No MATCH and no POSSIBLE_MATCH outcomes -> a new Person resource is created and linked to that Patient as MATCH. All fields are copied from the Patient to the Person. If the incoming resource has an EID, it is copied to the Person. Otherwise a new UUID is generated and used as the internal EID.
<!---
All fields are copied from the Patient to the Golden Patient.
-->
* CASE 2: All of the MATCH Patient resources are already linked to the same Person -> a new Link is created between the new Patient and that Person and is set to MATCH.
* CASE 1: No MATCH and no POSSIBLE_MATCH outcomes -> a new Golden Patient resource is created and linked to that Patient as MATCH.
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 3: The MATCH Patient resources link to more than one Person -> Mark all links as POSSIBLE_MATCH. All other Person resources are marked as POSSIBLE_DUPLICATE of this first Person. 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 Person as both the source and target of the link.
* 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 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
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.
# HAPI EMPI Technical Details
# HAPI MDM Technical Details
When EMPI 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 creates two MESSAGE subscriptions, called 'empi-patient' and 'empi-practitioner' that match all incoming Patient and Practitioner resources and send them to an internal queue called "empi". The JPA Server listens to this queue and links incoming resources to Persons.
1. The [EMPI Operations](/hapi-fhir/docs/server_jpa_empi/empi_operations.html) are registered with the server.
1. It registers a new dao interceptor that restricts access to EMPI managed Person records.
1. The [MDM Operations](/hapi-fhir/docs/server_jpa_empi/empi_operations.html) are registered with the server.
1. It registers a new dao interceptor that restricts access to MDM managed Golden Patient records.

46
hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_empi/empi_eid.md
View File

@ -1,42 +1,50 @@
# EMPI Enterprise Identifiers
# MDM Enterprise Identifiers
An Enterprise Identifier(EID) is a unique identifier that can be attached to Patients or Practitioners. Each implementation is expected to use exactly one EID system for incoming resources, defined in the EMPI Rules file. If a Patient or Practitioner with a valid EID is submitted, that EID will be copied over to the Person that was matched. In the case that the incoming Patient or Practitioner had no EID assigned, an internal EID will be created for it. There are thus two classes of EID. Internal EIDs, created by HAPI-EMPI, and External EIDs, provided by the submitted resources.
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 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
* External EIDs, provided by the submitted resources.
## EMPI EID Settings
## MDM EID Settings
The [EmpiSettings](/hapi-fhir/apidocs/hapi-fhir-server-empi/ca/uhn/fhir/empi/rules/config/EmpiSettings.html) bean contains two EID related settings. Both are enabled by default.
The [EmpiSettings](/hapi-fhir/apidocs/hapi-fhir-server-empi/ca/uhn/fhir/empi/rules/config/EmpiSettings.html) bean
contains two EID related settings. Both are enabled by default.
* **Prevent EID Updates** ([JavaDoc](/hapi-fhir/apidocs/hapi-fhir-server-empi/ca/uhn/fhir/empi/rules/config/EmpiSettings.html#setPreventEidUpdates(boolean))): If this is enabled, then once an EID is set on a resource, it cannot be changed. If disabled, patients may have their EID updated.
* **Prevent multiple EIDs**: ([JavaDoc](/hapi-fhir/apidocs/hapi-fhir-server-empi/ca/uhn/fhir/empi/rules/config/EmpiSettings.html#setPreventMultipleEids(boolean))): If this is enabled, then a resource cannot have more than one EID, and incoming resources that break this rule will be rejected.
## EMPI EID Scenarios
## MDM EID Scenarios
EMPI EID management follows a complex set of rules to link related Patient records via their Enterprise Id. The following diagrams outline how EIDs are replicated from Patient resources to their linked Person resources under various scenarios according to the values of the EID Settings.
MDM EID management follows a complex set of rules to link related Patient 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.
## EMPI EID Create Scenarios
## MDM EID Create Scenarios
<a href="/hapi-fhir/docs/images/empi-create-1.svg"><img src="/hapi-fhir/docs/images/empi-create-1.svg" alt="EMPI Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
<a href="/hapi-fhir/docs/images/empi-create-1.svg"><img src="/hapi-fhir/docs/images/empi-create-1.svg" alt="MDM Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
<a href="/hapi-fhir/docs/images/empi-create-2.svg"><img src="/hapi-fhir/docs/images/empi-create-2.svg" alt="EMPI Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
<a href="/hapi-fhir/docs/images/empi-create-2.svg"><img src="/hapi-fhir/docs/images/empi-create-2.svg" alt="MDM Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
<a href="/hapi-fhir/docs/images/empi-create-3.svg"><img src="/hapi-fhir/docs/images/empi-create-3.svg" alt="EMPI Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
<a href="/hapi-fhir/docs/images/empi-create-3.svg"><img src="/hapi-fhir/docs/images/empi-create-3.svg" alt="MDM Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
<a href="/hapi-fhir/docs/images/empi-create-4.svg"><img src="/hapi-fhir/docs/images/empi-create-4.svg" alt="EMPI Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
<a href="/hapi-fhir/docs/images/empi-create-4.svg"><img src="/hapi-fhir/docs/images/empi-create-4.svg" alt="MDM Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
<a href="/hapi-fhir/docs/images/empi-create-5.svg"><img src="/hapi-fhir/docs/images/empi-create-5.svg" alt="EMPI Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
<a href="/hapi-fhir/docs/images/empi-create-5.svg"><img src="/hapi-fhir/docs/images/empi-create-5.svg" alt="MDM Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
## EMPI EID Update Scenarios
## MDM EID Update Scenarios
<a href="/hapi-fhir/docs/images/empi-update-1.svg"><img src="/hapi-fhir/docs/images/empi-update-1.svg" alt="EMPI Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
<a href="/hapi-fhir/docs/images/empi-update-1.svg"><img src="/hapi-fhir/docs/images/empi-update-1.svg" alt="MDM Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
<a href="/hapi-fhir/docs/images/empi-update-2.svg"><img src="/hapi-fhir/docs/images/empi-update-2.svg" alt="EMPI Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
<a href="/hapi-fhir/docs/images/empi-update-2.svg"><img src="/hapi-fhir/docs/images/empi-update-2.svg" alt="MDM Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
<a href="/hapi-fhir/docs/images/empi-update-3.svg"><img src="/hapi-fhir/docs/images/empi-update-3.svg" alt="EMPI Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
<a href="/hapi-fhir/docs/images/empi-update-3.svg"><img src="/hapi-fhir/docs/images/empi-update-3.svg" alt="MDM Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
<a href="/hapi-fhir/docs/images/empi-update-4.svg"><img src="/hapi-fhir/docs/images/empi-update-4.svg" alt="EMPI Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
<a href="/hapi-fhir/docs/images/empi-update-4.svg"><img src="/hapi-fhir/docs/images/empi-update-4.svg" alt="MDM Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
<a href="/hapi-fhir/docs/images/empi-update-5.svg"><img src="/hapi-fhir/docs/images/empi-update-5.svg" alt="EMPI Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
<a href="/hapi-fhir/docs/images/empi-update-5.svg"><img src="/hapi-fhir/docs/images/empi-update-5.svg" alt="MDM Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
<a href="/hapi-fhir/docs/images/empi-update-6.svg"><img src="/hapi-fhir/docs/images/empi-update-6.svg" alt="EMPI Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>
<a href="/hapi-fhir/docs/images/empi-update-6.svg"><img src="/hapi-fhir/docs/images/empi-update-6.svg" alt="MDM Create 1" style="margin-left: 15px; margin-bottom: 15px;" /></a>

198
hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_empi/empi_operations.md
View File

@ -1,12 +1,12 @@
# EMPI Operations
# MDM Operations
EMPI links are managed by EMPI Operations. These operations are supplied by a [plain provider](/docs/server_plain/resource_providers.html#plain-providers) called [EmpiProvider](/hapi-fhir/apidocs/hapi-fhir-server-empi/ca/uhn/fhir/empi/provider/EmpiProviderR4.html).
MDM links are managed by MDM Operations. These operations are supplied by a [plain provider](/docs/server_plain/resource_providers.html#plain-providers) called [EmpiProvider](/hapi-fhir/apidocs/hapi-fhir-server-empi/ca/uhn/fhir/empi/provider/EmpiProviderR4.html).
In cases where the operation changes data, if a resource id parameter contains a version (e.g. `Person/123/_history/1`), then the operation will fail with a 409 CONFLICT if that is not the latest version of that resource. This feature can be used to prevent update conflicts in an environment where multiple users are working on the same set of empi links.
In cases where the operation changes data, if a resource id parameter contains a version (e.g. `Patient/123/_history/1`), then the operation will fail with a 409 CONFLICT if that is not the latest version of that resource. This feature can be used to prevent update conflicts in an environment where multiple users are working on the same set of empi links.
## Query links
Ue the `$empi-query-links` operation to view empi links. The results returned are based on the parameters provided. All parameters are optional. This operation takes the following parameters:
Use the `$mdm-query-links` operation to view MDM links. The results returned are based on the parameters provided. All parameters are optional. This operation takes the following parameters:
<table class="table table-striped table-condensed">
<thead>
@ -19,19 +19,19 @@ Ue the `$empi-query-links` operation to view empi links. The results returned a
</thead>
<tbody>
<tr>
<td>personId</td>
<td>goldenResourceId</td>
<td>String</td>
<td>0..1</td>
<td>
The id of the Person resource.
The id of the Golden Resource (e.g. Golden Patient Resource).
</td>
</tr>
<tr>
<td>targetId</td>
<td>resourceId</td>
<td>String</td>
<td>0..1</td>
<td>
The id of the Patient or Practitioner resource.
The id of the target resource (e.g. Patient resource).
</td>
</tr>
<tr>
@ -55,10 +55,10 @@ Ue the `$empi-query-links` operation to view empi links. The results returned a
### Example
Use an HTTP GET like `http://example.com/$empi-query-links?matchResult=POSSIBLE_MATCH` or an HTTP POST to the following URL to invoke this operation:
Use an HTTP GET like `http://example.com/$mdm-query-links?matchResult=POSSIBLE_MATCH` or an HTTP POST to the following URL to invoke this operation:
```url
http://example.com/$empi-query-links
http://example.com/$mdm-query-links
```
The following request body could be used to find all POSSIBLE_MATCH links in the system:
@ -81,10 +81,10 @@ This operation returns a `Parameters` resource that looks like the following:
"parameter": [ {
"name": "link",
"part": [ {
"name": "personId",
"name": "goldenResourceId",
"valueString": "Person/123"
}, {
"name": "targetId",
"name": "resourceId",
"valueString": "Patient/456"
}, {
"name": "matchResult",
@ -106,61 +106,20 @@ This operation returns a `Parameters` resource that looks like the following:
}
```
## Querying links via the Person resource
## Query Duplicate Golden Resources
Alternatively, you can query Empi links by querying Person resources directly. Empi represents links in Person resources using the following mapping:
<table class="table table-striped table-condensed">
<thead>
<tr>
<th>EMPI matchResult</th>
<th>EMPI linkSource</th>
<th>Person link.assurance</th>
</tr>
</thead>
<tbody>
<tr>
<td>NO_MATCH</td>
<td>MANUAL</td>
<td>No link present</td>
</tr>
<tr>
<td>POSSIBLE_MATCH</td>
<td>AUTO</td>
<td>level2</td>
</tr>
<tr>
<td>MATCH</td>
<td>AUTO</td>
<td>level3</td>
</tr>
<tr>
<td>MATCH</td>
<td>MANUAL</td>
<td>level4</td>
</tr>
</tbody>
</table>
For example, you can use the following HTTP GET to find all Person resources that have POSSIBLE_MATCH links:
```
http://example.com/Person?assurance=level2
```
## Query Duplicate Persons
Use the `$empi-duplicate-persons` operation to request a list of duplicate persons. This operation takes no parameters
Use the `$empi-duplicate-golden-resources` operation to request a list of duplicate golden resources.
This operation takes no parameters.
### Example
Use an HTTP GET to the following URL to invoke this operation:
```url
http://example.com/$empi-duplicate-persons
http://example.com/$empi-duplicate-golden-resources
```
This operation returns `Parameters` similar to `$empi-query-links`:
This operation returns `Parameters` similar to `$mdm-query-links`:
```json
@ -169,10 +128,10 @@ This operation returns `Parameters` similar to `$empi-query-links`:
"parameter": [ {
"name": "link",
"part": [ {
"name": "personId",
"name": "goldenResourceId",
"valueString": "Person/123"
}, {
"name": "targetId",
"name": "resourceId",
"valueString": "Person/456"
}, {
"name": "matchResult",
@ -185,9 +144,10 @@ This operation returns `Parameters` similar to `$empi-query-links`:
}
```
## Unduplicate Persons
## Unduplicate Golden Resources
Use the `$empi-not-duplicate` operation to mark duplicate persons as not duplicates. This operation takes the following parameters:
Use the `$empi-not-duplicate` operation to mark duplicate golden resources as not duplicates.
This operation takes the following parameters:
<table class="table table-striped table-condensed">
<thead>
@ -200,15 +160,15 @@ Use the `$empi-not-duplicate` operation to mark duplicate persons as not duplica
</thead>
<tbody>
<tr>
<td>personId</td>
<td>goldenResourceId</td>
<td>String</td>
<td>1..1</td>
<td>
The id of the Person resource.
The id of the Golden resource.
</td>
</tr>
<tr>
<td>targetId</td>
<td>resourceId</td>
<td>String</td>
<td>1..1</td>
<td>
@ -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:
<table class="table table-striped table-condensed">
<thead>
@ -268,19 +228,19 @@ Use the `$empi-update-link` operation to change the `matchResult` update of an e
</thead>
<tbody>
<tr>
<td>personId</td>
<td>goldenResourceId</td>
<td>String</td>
<td>1..1</td>
<td>
The id of the Person resource.
The id of the Golden resource.
</td>
</tr>
<tr>
<td>targetId</td>
<td>resourceId</td>
<td>String</td>
<td>1..1</td>
<td>
The id of the Patient or Practitioner resource.
The id of the target resource.
</td>
</tr>
<tr>
@ -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
<!---
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:
</thead>
<tbody>
<tr>
<td>fromPersonId</td>
<td>fromGoldenResourceId</td>
<td>String</td>
<td>1..1</td>
<td>
The id of the Person resource to merge data from.
The id of the Golden Resource to merge data from.
</td>
</tr>
<tr>
<td>toPersonId</td>
<td>toGoldenResourceId</td>
<td>String</td>
<td>1..1</td>
<td>
The id of the Person to merge data into.
The id of the Golden Resource to merge data into.
</td>
</tr>
</tbody>
@ -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 will include search score that is calculated by averaging the
number of matched rules against total rules checked for the Patient resource, and assigning appropriate match grade extension.
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.
</thead>
<tbody>
<tr>
<td>resourceType</td>
<td>targetType</td>
<td>String</td>
<td>0..1</td>
<td>
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.
</td>
</tr>
</tbody>
@ -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
{

33
hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_jpa_empi/empi_rules.md
View File

@ -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_empi/empi_eid.html) for details on how EIDs are managed by HAPI MDM.