Interested is participating in the Google Summer of Code program? Please see the GSOC wiki page.

Wiki Spaces


Get Help from Others

Q&A: Ask OpenMRS »
Discussion: OpenMRS Talk »
Real-Time: IRC Chat


Skip to end of metadata
Go to start of metadata

The HIV Case Based Reporting Module is a proof of concept and it should NOT be used in production. It is compatible with Reference Application 2.4 and above.


This module was created as part of a CDC-funded project to demonstrate the power of driving public health decisions directly from data generated on the front lines of care, using HIV Case Based Reporting within OpenMRS integrated with an HIE as an initial use case. By design, the module allow trigger events to be defined as SQL queries. For HIV, these triggers include things like new HIV diagnosis, new HIV disease, evidence of treatment failure, lost to follow-up, etc. When trigger events are detected for a patient, the patient and associated event are added to a case report queue. A Surveillance Officer at the site reviews the queue and is able to easily submit case reports directly from the queue. Case reports are formatted into CDA documents so they can be fed directly into an Health Information Exchange (HIE).


The goal of this module is to serve as a demonstration of patient-level data feeding directly into an HIE to drive improved public health decision-making.




  • Reference Application 2.4 or later
  • A destination for case reports (e.g., an HIE). In our demonstrations, we use OpenHIE.

Source Code

User Guide

Also available here.

Also available here.

Integration With OpenHIE

These analyses are a work-in-progress and open to public comment.


  • Operating System: Ubuntu 14.04
  • A running instance of OpenMRS with the case reporting installed, if not you can follow the OpenMRS installation guide and to install the module see this guide.

OpenHIE Architectural Overview

The OpenHIE website has a more detailed installation guide here, this is more like a summarized but more specific to help one set up an instance quickly.

In this guide we are going to see how to setup an OpenHIE instance comprised of a couple of systems interacting with each other, when everything has been setup we will be able to generate a case report in one system and send it to its intended destination with the help of the all the components, below are the components that will be involved.

Interoperability Layer (IOL)

Receives all communications from services within a health geography, and orchestrates message processing among the external systems and the OpenHIE component layer. OpenHIM is the implementation that we will be using for this, for more on the IOL see here

Shared Health Record (SHR)

This is a repository containing the normalized version of content created within the community, after being validated against each of the previous registries.  It is a collection of person-centric records for patients with information in the exchange. In this guide, we'll be using a combination of an OpenMRS instance and OpenXDS, OpenMRS being the patient data store and OpenXDS the document store, OpenXDS implements the IHE XDS profile, for more on the SHR see here

Client Registry (CR)

An enterprise master patient index (EMPI) that manages the unique identity of the patients receiving health services at the various health facilities, it's the source of truth for patient identifiers. In this guide we are going use OpenEMPI, for more on the CR see here

External System

Any external system used by clinicians and by community health workers to access and update a patient’s person-centric shared health information and to record healthcare transactions, this is typically a point of care system (POC)  running at any health center and there could be several in the HIE. In our setup we will have another OpenMRS instance which is different from that of the SHR we saw earlier, it is where the case reporting module is installed therefore it will be the source of the case report documents.


To get more details about OpenHIE visit this page

Note that in this guide we chose the particular software implementations for the different components in the HIE but you can install other implementations.


Case Based Reporting Workflow Summary with OpenHIE Integration

A case report is generated for a patient and submitted from the OpenMRS based POC system to the interoperability layer, the document is submitted as a SOAP message based on the XDS profile with a CDA document embedded inside it. The IOL routes the document to the XDS.b mediator registered with it whose work is to enrich the document with an enterprise identifier of the patient, it does this by making a request to the client registry for the patient's enterprise ID and overwrites the local patient ID in the document with the enterprise one and then forwards the message to the SHR, the SHR stores the metadata associated to the document in the document registry and the original document in the document repository, it also parses the embedded CDA document to extract any discrete data and saves in its data store.

 Install the SHR

Run the commands below in the terminal, for more details see the setting up the openshr on ubuntu from a ppa 1404 trusty guide.

Only provide mysql root passwords and leave the default values for the rest of the prompts.

Assuming you kept the default values the same for the OpenSHR prompts, the OpenMRS username and password are admin and OpenSHR#123 respectively, you'll definitely have to change the password for production installations.

There is a file that contains the codes from various coding systems for the metadata that is required by the SHR in order for it to receive documents from other systems in the HIE, it's located at /usr/share/openshr/openxds/conf/actors/XdsCodes.xml, there is some extra metadata codes that you need to add to this file before you can submit case reports to the HIE. You can obtain an already updated copy of this XdsCodes.xml to replace the original and then restart the machine.

You MUST restart the machine where this SHR is installed for the contents of the new XdsCodes.xml to be loaded.

Install OpenHIM (core and console apps)

Run the commands below in the terminal, for more details see installing-the-openhim-core-and-console guide, this PDF contains the full OpenHIM documentation.

  • Keep the default values for the prompts.
  • For a demo installation you don't have to set up TLS certificate to secure your server.

Because the tomcat instance installed as part of the SHR above is already listening on port 8080, you'll need to reconfigure openhim-core to listen on another available port by editing the api -> https field in the /etc/openhim/config.json file, restart openhim-core by running the command below:

If you haven't yet, update openhim-console to use the new port you set above that openhim-core api is listening on, note that if openhim-core is installed on a separate machine, you need to set the host value to be the IP address of the remote machine, below is the command to execute:

Following the installing-the-openhim-admin-console guide, skip past the installation section since you already installed it in the previous step, find the section for how to access openhim-console and how to authenticate, you should be able to use the openhim-console in your web browser after this step at http:server_ip

Install The Client Registry

In this guide we use OpenEMPI as the client registry but there is other implementations like MEDIC-CR and OpenPIXPDQ.

  • Download and install OpenEMPI using this guide
  • Start OpenMRS by navigating to the /usr/share/openempi/bin directory and execute the sh command, you might want to be patient with it because it takes a while to be ready for use.
  • To access the application, go to http://server_ip:8080/openempi-admin in your browser where server_ip is the host name or IP address of the machine where you've installed OpenEMPI, the default username and password are both admin
  • If you've installed OpenEMPI on the same machine as the SHR or OpenHIM, you might run into some port conflicts, therefore you might need to reconfigure ports for those affected, e.g it runs inside a different tomcat instance it ship with, meaning you would need to reconfigure its tomcat instance to listen on a different port if the SHR is installed on the same machine and listening on port 8080 too.
  • You might want to check that the PIX/PDQ server has been started by running the netstat -plant | grep LISTEN command you should see a process listening on port 3600, if not then the PIX/PDQ server isn't started, see the docs here for how to start it through the OpenMEPI user interface. Alternatively, you could configure OpenEMPI to automatically start the PIX/PDQ server by setting the value of the admin-configuration/autostart-pixpdq tag to true in the /usr/share/openempi/openempi-entity-3.3.0c/conf/mpi-config.xml file.

Install The XDS mediator

The mediator can be installed on a difference machine from that where the OpenHIM is installed but it is recommended to install it on the same machine to minimize what needs to be configured for the two to communicate.

  • Download the latest version of the mediator from here, make sure to download the openhim-mediator-xds-1.0.3.tar.gz file
  • Switch to the terminal, navigate to the folder where you downloaded the tar file to and run the commands below,


At this point the mediator files have been extracted to the /usr/share/openshr/mediators/xds-mediator directory and your terminal is rooted at this folder.

  • Rename the file to  
  • There are other properties that you will need to update later in the but for now update just set the ones below: : The host name or IP address of the machine on which the mediator is hosted : The host name or IP address of the machine on which OpenHIM is installed

core.api.port :  The api port on which OpenHIM is listening, should match the port configured in OpenHIM's /etc/openhim/config.json file  for the api -> httpsPort field

core.api.user : The OpenHIM username

core.api.password : The OpenHIM password : The host name or IP address of the machine on which OpenEMPI is installed : Specifies if the connection to OpenHIM is secure i.e over HTTPs

pix.manager.port :  The port on which the PIX/PDQ server in OpenEMPI is listening, PIX/PDQ server by default listens on port 3600

pix.manager.securePort : The secure port on which the PIX/PDQ server in OpenEMPI is listening if the connection to the PIX/PDQ server : The host name or IP address of the machine on which the SHR is installed : Specifies if the connection to the xds repository (SHR) is secure i.e over HTTPs

xds.repository.port : The port on which the SHR is listening, since the the SHR is OpenMRS which in tomcat, this should be port tomcat is listening on 

xds.repository.securePort : The secure port on which the SHR is listening, since the the SHR is OpenMRS which in tomcat, this should be secure port tomcat is listening on 

xds.repository.path : Set this to /openmrs/ms/xdsrepository


If you configured any connections above to be secure, i.e you set any of the properties that end with .secure to true, you will need to add the SSL certificate from the OpenHIM server to your java truststore by running the commands below, the script assumes you set the JAVA_HOME environmental variable otherwise you will need to replace it with the path of where the JRE is installed on your machine.


  • Start the mediator by navigating to the folder where you extracted the mediator files to i.e /usr/share/openshr/mediators/xds-mediator and run the command below:

When the mediator starts, it auto registers itself with OpenHIM and if this was successful you should be able to see it listed in OpenHIM, i.e. go to the OpenHIM console application and select Mediators from the left panel.

Configure the mediator in OpenHIM

See the documentation for more details on OpenHIM, channels and mediators.

Go to the OpenHIM console's home page i.e http://openhim_server_ip

Setup the XDS.b Mediator channel

  • Select Mediators from the left panel, and then select OpenHIE XDS.b Mediator
  • On the far right, you should see a little green box with a white cross which you should click
  • Select the Channels tab from the left panel, you should see a new channel named XDS.b Mediator that has just been added

The channel you've created above is private by default, you can make it public by selecting it from the list, i.e go to the Request Matching tab, mark it as public and save the changes. Typically in production you would need to keep it private, it requires an xds role as you can see under the section labeled Which clients should be able to access this channel? Therefore, you'll need to add a Client and assign it this role, see  the adding clients guide.

Setup the PIX/PID channel (For routing Patient registration requests to the XDS.b patient registry)

  • Select the Channels tab from the left panel.
  • Click Add Channel button, set the name, under "What type of channel do you want?" select TCP, then set the TCP host to and the TCP port to 3622
  • Go to the Request Matching tab, mark the channel as public
  • Go to the Routes tab, click Add New Route, set the name, set route type to MLLP with the host to localhost and port to 3602
  • Click Save changes

Upgrade OpenMRS and the SHR modules

  • In OpenMRS webapp, navigate to Administration, under Maintenance select Settings, select the Search tab on the left panel and clear the value of the Index Version global property because it's necessary for the search index to get rebuilt.
  • Delete the existing openmrs.war file and openmrs directory from the /usr/share/openshr/tomcat/webapps directory.
  • Delete all the SHR modules i.e EXCEPT for the module from the /usr/share/openshr/openmrs/modules directory.
  • Delete the work directory from the /usr/share/openshr/tomcat directory.
  • Download and install the openmrs.war file version 1.11.5 or later i.e any version in the 1.11.x or 1.12.x release lines, don't try 2.0 or later versions because not all the SHR modules are compatible.
  • Copy the downloaded openmrs.war file to /usr/share/openshr/tomcat/webapps directory.
  • Copy the updated SHR modules below to the /usr/share/openshr/openmrs/modules directory.
    1. shr-atna-1.0.1-SNAPSHOT.omod
    2. shr-contenthandler-3.0.1-SNAPSHOT.omod
    3. shr-cdahandler-1.0.1-SNAPSHOT.omod
    4. xds-b-repository-1.1.1-SNAPSHOT.omod
    5. shr-odd-1.0.1-SNAPSHOT.omod
  • Restart your machine.

It's important to restart your machine and not just tomcat after upgrading, in fact as a general rule you should always restart the machine instead of the individual components of the SHR if you installed it using the above ubuntu package because it creates some startup scripts that run the executables with the appropriate user account and required settings, otherwise you might run into some strange issues

Some key configurations to make before you start using the ecosystem

  1. OpenEMPI ships with some patient identifier domains, an identifier domain is analogous to a patient identifier type in OpenMRS, you might want to add extra identifier domains i.e one for each patient identifier type in the OpenMRS point of care system (the instance to submit case reports), see the Manage Identifier Domains page for details. You'll need to set the Universal IdentifierId Type value for each identifier domain to ISO, the SHR requires this and not really the client registry. The Universal IdentifierId value has to be a valid OID, the SHR is the one that requires this too. For testing purposes you can set it to a string of numbers separated by dots e.g but in production you would need to obtain a valid and preferably registered OID, for more details on OIDs and obtaining one for your organization go to HL7 OIDs page.
  2. Agree on an enterprise/global patient identifier domain to use.
  3. Mediator configurations: Open the file that you created earlier above and edit the values of the properties below.
    1. client.requestedAssigningAuthorityId : Specifies the patient identifier domain to convert to when enriching a document with enterprise IDs, when a document is submitted to the HIE, it normally has local patient identifiers from the source, this tells the mediator in OpenHIM which identifier domain to convert to before forwarding the document to the SHR.
    2. client.requestedAssigningAuthority (Optional) : Specifies the  name of the patient identifier domain to convert when enriching a document with enterprise IDs.
    3. pnr.patient.autoRegister : Set it to true if you want patients to be auto registered if they don't exist in the Client Registry i.e if the mediator can't find them in the client registry by their local ID from the source.
    4. You MUST restart the mediator for the changes to take effect.
  4. The patients in the point of care  OpenMRS instance and the SHR need to have identifiers matching the format specified by the values of their respective global properties, by default they are set to %2$s^^^&%1$s&ISO and there should hardly ever be a reason to changed them, only advanced users who know what they are doing should alter them.
  5. Point of care OpenMRS instance configurations
    1. Go to Administration , under Maintenance select Settings, select Casereport from the left panel and set the values of the listed global properties below.
    2. The user that submits case reports is required to have a provider account that is linked to their person record.
  6. SHR configurations: 
    1. Go to Administration , under Maintenance select Settings, select Shr - CDAhandler from the left panel and set the values of the global properties that start with Autocreate to true or false based on your preferences.
  7. OpenXDS configurations:
    1. In the /usr/share/openshr/openxds/ file, there is a property, when a document is submitted and the patient doesn't exist in OpenXDS' PIX/PDQ registry which will be the case for new patients, the document processing will fail unless this property is set to false.