...

USE-CASE DIAGRAM FOR THE REGISTRATION MODULE

Master Patient Index Developer Notes

The following section will explain what lives where in the code and how everything works.

• The list of global property variable names (that the rest of the code references) that maps to the names of the global properties (in the global properties table, and that is displayed through the UI)
  • openmrs-module-registrationcore/api/src/main/java/org/openmrs/module/registrationcore/RegistrationCoreConstants.java
• Global properties definitions,  descriptions and default values are set:
  • openmrs-module-registrationcore/omod/src/main/resources/config.xml
  • Note that these values will only be applied if the global property does not already exist. if it already exists, this config.xml file will not write over the current value.
• To configure dependancies on other modules there are 4 main files to be changed
  • openmrs-module-registrationcore/pom.xml
  • openmrs-module-registrationcore/api/pom.xml
  • openmrs-module-registrationcore/omod/pom.xml
  • openmrs-module-registrationcore/omod/src/main/resources/config.xml

PIX/PDQ Implementation

The fields that are sent to and from the MPI via PIX/PDQ are hardcoded in openmrs-module-registrationcore/api/src/main/java/org/openmrs/module/registrationcore/api/mpi/pixpdq/PixPdqMessageUtil.java

The hl7 message that is sent from MPI → OpenMRS is parsed by interpretPIDSegments. The patient demographic fields that it extracts are hardcoded in this method.

The hl7 message that is sent from OpenMRS → MPI is constructed by createAdmit which calls updateMSH to construct the Message Header and updatePID to construct the Patient Identification segment.

Patient Demographics Query (PDQ)

See section 3.21.4.1 Patient Demographics Query in the following document: http://www.ihe.net/uploadedFiles/Documents/ITI/IHE_ITI_TF_Vol2a.pdf for specifications and explanations of terms such as MSH, QPD, PID

An alternative reference for Patient Identification (PID) Segments is: http://www.hl7.eu/refactored/segPID.html

To manually send PDQ or PIX messages or just better understand how the messages are composed, download the HAPI Test Panel https://github.com/hapifhir/hapi-hl7v2/releases

Image Added

configuring a sending connection to a local OpenEMPI instance over MLLP running default settings

Image Added

OpenEMPI

Testing messages with your local OpenEMPI instance

The MLLP port for PDQ is set in the following file: ~path-to-openempi~/openempi-entity-3.5.0c/conf/PdSupplierConnections.xml

Errors 

Patient Identifier Collision

...

Situation: 

1. You have an OpenMRS server set up, it is configured to connect to an MPI through OpenHIM acting as the Interoperability Layer
2. Using the registration app
   Image Added

1. You create a patient
   Image Added
2. It gives no errors and redirects you to the patient page
   Image Added
   1. Note that the patientId in the URL is actually the uuid of the person which can be found in the person table.
   2. The Patient ID in the dashboard is in this case the OpenMRS ID which is autogenerated by OpenMRS.
3. However, you cannot find the patient you created in the MPI when you search by name
   Image Added
4. But if you search by OpenMRS ID, you find a different patient, this patient has the same MPI Global Identifier Domain ID (In this case Open EMPI ID) as the patient you just created
   Image Added
5. This can be checked by looking at the patient_identifier table
   
   Image Added
6. Looking at the OpenHIM transaction logs, we can see that no error that could have been picked up by the PixPdqMessageUtil in exportPatient (org/openmrs/module/registrationcore/api/mpi/pixpdq/PixPatientExporter.java:39) is recorded
   Image Added

Explanation

The OpenMRS generated ID already exists in the MPI under a different patient, and the . The local OpenMRS generates generated the same OpenMRS ID for a new patient it is registering and submits it, the following will happensubmitted it. This will happen for example if you create two reference application distributions, connect both of them to the same MPI and start creating patients in both of them. There will be no errors. The local patient will be saved locally but with the MPI patient's Global Identifier Domain ID (E.g. ECID for ISantePlus or OpenEMPI ID for default OpenEMPI setup). The local patient will not be saved in the MPI. 

Solution

In order to ensure that your multiple OpenMRS servers do not generate IDs that collide you could do one or more of the following:

1. Legacy Admin UI → Manage Patient Identifier Sources → Configure
   Image Added
2. Add different prefixes and or suffixes
   Image Added
3. This can also be done directly on the database table:
   Image Added
   
   1. Additionally you could change the next_sequence_value for the different servers.