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.