Registration Module

Resources

*Registration Module (this page)

Background

Registration is one of the primary modules in any data management system. A patient's medical record management starts with registering a patient with the system. OpenMRS being a customizable and scalable solution to medical record management also requires a customizable patient registration system. Since every implementation of OpenMRS may be different on the type of information that it may require, it is extremely important to keep the registration module generalized in a way where it can be configured to take registration information about a patient according to the needs of the implementer.

Goal

Create a module which will allow the user from within OpenMRS to easily search for a patient and, if the patient is not found, create a new patient record. Allow use of barcode cards to identify patients. Will allow adding patients to the database, even if disconnected from a central OpenMRS server.

Targets

The Registration module will be similar to the RwandaRegistration Module which was built specific to the requirement at Rwanda by PIH. The following are the steps to be followed in achieving the goal of the module:

*Look-And-Feel + Re-factoring + Patient Search:

    • The look-and-feel of registration should be similar to OpenMRS web application.
    • The RwandaRegistration Module will be re-factored to make it generic to the data (like patient identifier) of OpenMRS
    • The module will first display a page to find a patient using patient identifier or patient name

*Search Patient Using Bar-Code Scanning:

    • Bar-Code scanner will be able to read bar-code and return the code to the OpenMRS web application
    • Match database for bar-code and retrieve patient identifier
    • Open the Patient Dashboard directly when successful match found

*Search Patient Using Fingerprint:

    • Patient registers own fingerprint on first visit
    • On revisit, the patient puts finger on reader and fingerprint is matched with all in database. The patient summary is printed and given to the patient

*Create New Patient:

    • If the patient is not found, open registration page with the search name as input to Name field
    • Similar form to current OpenMRS registration is displayed
    • Create patient generates a new bar-code representing the patient identifier
    • Allow printing id-cards / barcode for the patients

*Save Patient Image

    • Patient while registering stands in front of the camera.
    • A flex widget will capture the patient image and save it as a file with the identifier

Release Notes

1.3.1

  • Removed implementation specific concepts
  • Fixed bugs

1.3

  • Fixed bugs
  • Created registration encounter and OPD visits

1.2

  • Bug fixes
  • Works with OpenMRS 1.7
  • Patient attributes and first encounter with observations can be saved
  • Uploaded identifiers can be used by multiple data entry operators simulataneously. Added locking of identifiers

1.1

  • Patients can be found using fingerprints
  • Patient attributes can be saved

1.0.3

  • Stable release available in OpenMRS repository
  • Base30 Identifiers can be generated
  • Uploaded list of identifiers

0.8

  • Registration Module is used to register patients or find/revisit patients

0.7

  • Identifiers are automatically alloted if MRN ids file is uploaded

Biometric Working

UML Model Diagrams

ACTIVITY DIAGRAM FOR THE REGISTRATION MODULE

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

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

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
  1. You create a patient
  2. It gives no errors and redirects you to the patient page
    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
  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
  5. This can be checked by looking at the patient_identifier table

  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

Explanation

The OpenMRS generated ID already exists in the MPI under a different patient. The local OpenMRS generated the same OpenMRS ID for a new patient and submitted 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
  2. Add different prefixes and or suffixes
  3. This can also be done directly on the database table:

    1. Additionally you could change the next_sequence_value for the different servers.