isanteplus/openmrs-module-mpi-client

MPI Client Modules for OpenMRS

SanteDB Community SanteMPI Client OpenMRS Module

---

This module allows any version of OpenMRS 1.9.8 or above to communicate with a PIX/PDQv2 compatible Master Patient Index such as SanteMPI or the MEDIC CR. This module implements the following profiles:

• IHE PIX v2 (ITI-8)
• IHE PIX Query v2 (ITI-9)
• IHE PDQ v2 (ITI-21)
• IHE ATNA (ITI-20)

API Documentation

Javadocs for this API can be found on the SanteSuite Community Server.

Maven

---

You can reference this API from MAVEN with the following Maven repos:

<repositories>
  <repository>
    <id>marc-te</id>
    <name>MEDIC TECH EXCHANGE</name>
    <url>http://te.marc-hi.ca/mvn</url>
  </repository>
  <repository>
    <id>santesute-main</id>
    <url>http://santesuite.org/mvn</url>
    <name>SanteSuite</name>
  </repository>
</repositories>

To reference the API:

<dependency>
	<groupId>org.openmrs.module</groupId>
	<artifactId>santedb-mpiclient-api</artifactId>
	<version>0.9.5</version>
</dependency>

Configuration of MPI Client

Once installed into OpenMRS, the MPI client needs to be configured. The parameters are created as global settings when you install the module, below is a "quick" guide on which settings to populate:

1. mpi-client.endpoint.pdq.addr : The endpoint of the PDQ supplier (ip-address or hostname)
2. mpi-client.endpoint.pdq.port : The port of the PDQ supplier
3. mpi-client.endpoint.pix.addr : The endpoint of the PIX Manager (ip-address or hostname)
4. mpi-client.endpoint.pix.port : The port of the PIX Manager
5. mpi-client.endpoint.ar.addr : The endpoint of the Audit Repository (ip-address or hostname)
6. mpi-client.endpoint.ar.transport : The transport protocol to use for audits one of : audit-udp, audit-tcp, audit-tls
7. mpi-client.endpoint.ar.port : The port of the audit repository
8. mpi-client.security.authtoken : The security token (MSH-8) to place in all outbound v2 traffic
9. mpi-client.msg.sendingApplication : The MSH-3 value representing the sending application name (example: OPENMRS)
10. mpi-client.msg.sendingFacility : The MSH-4 value representing the registered facility name (example: FACILITY_1)
11. mpi-client.msg.remoteApplication : The MSH-5 value representing the destination application (example: MEDIC_CR)
12. mpi-client.msg.remoteFacility : The MSH-6 value representing the destination facility (example: NATIONAL_MPI)
13. mpi-client.ext.extendedAttributes : If your copy of OpenMRS stores data as extensions rather than first class objects, this is used to map between your extensions and where in the v2 message that data goes.
14. mpi-client.ext.storeNK1AsRelationships : If your copy of OpenMRS uses relationships on patients to store mother/father/etc. relationships then set to true
15. mpi-client.pid.exportIdentifierType : Maps the named identifier types to IHE identity domains (example: Patient ID=LOCAL_ID,National ID=NAT_HEALTH_ID)
16. mpi-client.pid.nameRewriteRegex : If you are storing names in your OpenMRS in a special format, here is where you can specify a regex to rewrite the names prior to sending
17. mpi-client.pid.defaultCountry : The default country code to attach to addresses
18. mpi-client.pid.enterprise : The Namespace ID or Universal ID (OID) of the enterprise patient identifier generated by your MPI
19. mpi-client.pid.local : The Namespace ID or Universal ID (OID) of the patient.getId() generated by OpenMRS to send to the MPI
20. mpi-client.pid.nhid : The Namespace ID or Universal ID (OID) of the preferred remote identity domain (example: National Health ID), can be the same as enterprise id.
21. mpi-client.pid.updateIdTypes : When true tells the module to update local Patient Identifier types with OIDs when they are incorrect.

Mapping PersonAttributes to the v2 Fields

Many OpenMRS deployments will use person attributes to record telephone, email, mother/father's name. These are important attributes to map in the MPI, as such the mpi-client.ext.extendedAttributes setting can be used to map these. The format is quite simple, and needs to be rewritten (community help accepted) if you wanted to map an extension Mother's Name to PID-6-2 (Mother's Maiden Name / Given Name) you would use:

Mother's Name:PID-6-2

You can map multiple attributes as well, for example:

Mother's Name:PID-6-2,Mother's ID:PID-21-1

If you want to place a guard condition use a ?. For example, Father's Name needs to go into an NK1 segment with relationship type FTH.

Father's Name:NK1-2-2?NK1-3-1=FTH

Rewriting Names

In many OpenMRS deployments given names are used only, hover to reduce duplicates it may be useful to split the name apart getting rid of MR/MRS/DR/etc. This is done with the mpi-client.pid.nameRewriteRegex . The regex is executed against a string concatenation of Prefix Given Middle Family Suffix. This in the format of a JavaScript regex. For example, to strip away Mr or Ms or Mrs from a name:

/^(?:(mrs?|ms)\s)?([A-Za-z\s]*?)(?:\s\(NULL\))?$/^$2^^^$1^^^A/i

Building from Source

You will need to have Java 1.6+ and Maven 2.x+ installed. Use the command 'mvn package' to compile and package the module. The .omod file will be in the omod/target folder.

Alternatively you can add the snippet provided in the Creating Modules page to your omod/pom.xml and use the mvn command:

mvn package -P deploy-web -D deploy.path="../../openmrs-1.8.x/webapp/src/main/webapp"

It will allow you to deploy any changes to your web resources such as jsp or js files without re-installing the module. The deploy path says where OpenMRS is deployed.

Installation

1. Build the module to produce the .omod file.
2. Use the OpenMRS Administration > Manage Modules screen to upload and install the .omod file.

If uploads are not allowed from the web (changable via a runtime property), you can drop the omod into the ~/.OpenMRS/modules folder. (Where ~/.OpenMRS is assumed to be the Application Data Directory that the running openmrs is currently using.) After putting the file in there simply restart OpenMRS/tomcat and the module will be loaded and started.

openmrs-module-mpi-client's Issues

Clean up and simplify MPI module global properties / configuration

Display Client Registry results in a table format with the location specified if the patient was been in multiple locations

Display Client Registry results in a table format with the location specified if the patient was been in multiple locations

Patient search seems to only use given name field and not full name/ last name

To reproduce:

Go to patient search page, and start typing the last name of a patient that is in the client registry.

mpi search issue

1. search a patient in the patient search that is only in the mpi
2. try to select the patient in the mpi results
3. outcome: ajax error and new patient created in opencr

Set system field for Biometric Identifier

The biometric ID needs to easily be queried using a FHIRpath expression, and it would be easiest to select the correct Identifier by the system field.

For now, we can use the following for the system field: http://sedish-haiti.org/biometricid

@ccwhite333 @stansL Let me know what you think.

Display changes on Client Registry search result

we should the following information display:
Name - Gender-Age- Birthday-Address-Mother's Name-Phone-Site/Location-Emergency Contact Name

Phone number import seems to cause duplicate numbers / other issues with phone number field

To replicate:

1. Create patient in instance 1 with phone number

2. import patient in instance 2 through search

3. Examine patient resources natively or through OpenCR

• Test if occurs in registration

configure decision rules to include demographics and give biometrics priority

Display additional patient data on registration MPI match

• mother's maiden name
• phone number
• contact name
• source
• Last visit date?

find patient issue - ajax internal server error

Client Registry Workflow Issues

• When importing a patient on server 2, an extra patient record is created in OpenCR. The 2nd server is likely sending two consecutive requests, and OpenCR is not updating the previous one because it doesn't exist. This needs to be investigated.
• The decision rules do not always seem to correctly result in automatic vs. potential matches, and need to be built out and tested. All scenarios should be put into the Postman collection for automated testing.
• Address details are not loaded correctly into the 2nd server when importing a patient

Null pointer exception on patient search result display

openmrs-module-mpi-client/api/src/main/java/org/openmrs/module/santedb/mpiclient/api/impl/FhirMpiClientServiceImpl.java

Line 253 in 372df5f

MpiPatient mpiPatient = fhirUtil.parseFhirPatient((org.hl7.fhir.r4.model.Patient) goldenRecordEntry.getOther().getResource());

Review and determine the correct handling of locations

Currently, the location that gets attached to the patient is the isanteplus default location.

This location is sent attached the patient's identifier, and mapped in the FHIR2 module identifier translator.

However, we should likely use the location information set in the global settings (mpi-client.msg.sendingFacility or registrationcore.mpi.sendingFacility)

In general, we need to review our strategy for managing and setting locations for patients being sent to the MPI, since using the default location does not seem like the correct approach.

Patient source display isanteplus.sedish for patient import

Ensure correct gender code is set

When creating a new patient, a request is sent out to the MPI to search for matching patients. This search encodes the gender (where populated) incorrectly. For instance, searching:

localhost:5001/fhir/Patient?family%3Acontains=Lalka&given%3Acontains=Ale&gender=F&address-state%3Acontains=-&address-city%3Acontains=-&_include=Patient%3Alink&_format=json

Note that gender is queried for if it is F. The FHIR valueset for administrative gender specifies that this should be female.

patient import and registration error

Timeout failure on OpenCR during registration

Timeout failure on OpenCR during registration

mothers maiden name not showing in search results

openmrs-module-mpi-client/api/src/main/java/org/openmrs/module/santedb/mpiclient/util/FhirUtil.java

Line 505 in 6ad8030

// Mother's maiden name