Case Based Reporting Module

Analysis

• Shared Health Record: Case Based Reporting- Use Cases and Requirements
• OpenHIE Save Patient Level Clinical Data Analysis
• Data Integration with OpenHIE Registries - REVIEW
• Security and Privacy - DRAFT

Requirements

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

Source Code

• Source code is available on GitHub at openmrs-module-casereport

User Guide

Also available here.

Also available here.

Integration With OpenHIE

Requirements

• 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 version that is 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 (SHR) 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

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 request 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 call 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 (OpenXDS) and saves a copy of the original CDA document in the document repository, it also parses the embedded CDA document to extract any discrete data and saves in its data store.

Installation using docker

You can setup the entire stack of software using docker, for more details see. 

Otherwise you can install the individual components, please continue reading.

 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.

sudo add-apt-repository ppa:webupd8team/java 
sudo add-apt-repository ppa:openhie/release 
sudo apt-get update 
sudo apt-get install openshr

The SHR instance can take a while to start therefore you might have to wait for a couple of minutes, for a non production installation you can speed up the start up process by adding the text below to the value of the JAVA_OPTS environmental variable in the /etc/init/openshr-rep.conf file:

-Djava.security.egd=file:/dev/urandom

To access the OpenMRS instance from the browser you can go to this url http://host_ip_address:8080/openmrs. 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 one and then restart the machine. The practiceSettingCode and healthFacilityTypeCode configured in the CBR must exist in the XdsCodes.xml.  

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.

sudo add-apt-repository ppa:openhie/release
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv EA312927
sudo echo 'deb http://repo.mongodb.org/apt/ubuntu trusty/mongodb-org/3.2 multiverse' | sudo tee /etc/apt/sources.list.d/mongodb-org-3.2.list
sudo apt-get update 
sudo apt-get install openhim-core-js openhim-console

Configuring openhim-core

Open the /etc/openhim/config.json file in an editor and set the following properties:

• You need to enable logging which is based on the ATNA profile, set the value of the auditing -> servers -> tcp -> enabled field to true.
• Because the tomcat instance installed as part of the SHR above is already listening on port 8080 unless you have installed them on different machines otherwise you'll need to reconfigure openhim-core to listen on another available port by editing the value of the api -> httpsPort field.

Restarting openhim-core

Run the command below:

sudo service openhim-core restart

Reconfiguring openhim-console

If you haven't yet, update openhim-console to use the new port you set above that openhim-core api is listening on. Also note that even when openhim-core is installed on the same machine as the console application, you need to set the host value to an IP address rather than localhost. To reconfigure the console application, below is the command to execute:

sudo dpkg-reconfigure openhim-console

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 OpenEMPI by navigating to the /usr/share/openempi/bin directory and execute the sh startup.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

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 build mediator of the mediator from here.
• Switch to the terminal, navigate to the folder where you downloaded the tar file to and run the commands below.

mkdir -p /usr/share/openshr/mediators/xds-mediator
tar -xzvf openhim-mediator-xds-1.0.3.tar.gz -C /usr/share/openshr/mediators/xds-mediator --strip-components=1
cd /usr/share/openshr/mediators/xds-mediator

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 mediator.properties file to xds-mediator.properties  
• There are other properties that you will need to update later in the xds-mediator.properties but for now update just set the ones below:

mediator.host : The host name or IP address of the machine on which the mediator is hosted

core.host : 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

pix.manager.host : The host name or IP address of the machine on which OpenEMPI is installed

pix.secure : 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

xds.repository.host : The host name or IP address of the machine on which the SHR is installed

xds.repository.secure : 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 is hosted 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

pnr.patients.autoRegister : true

                 pnr.providers.enrich : false

                 pnr.facilities.enrich : false

• You will need to add the OpenHIM SSL certificate 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 to where the JRE is installed on your machine.

echo "Q" | openssl s_client -connect openhim_server_IP:openhim_api_port > openhim.crt
keytool -import -trustcacerts -alias openhim -file openhim.crt -keystore $JAVA_HOME/jre/lib/security/cacerts

• By default, logging is enabled in the mediator via tcp which implements the IHE ATNA profile because the value of the atna.useTcp property is already set to true in the xds-mediator.properties file. If for some reason it isn't turned on or incorrectly set up, you can re-enable it by doing the following: Set the value of the atna.useTcp property to true in the xds-mediator.properties file, open the /etc/openhim/config.json file on the machine where OpenHIM is installed and set the value of the auditing -> servers -> tcp -> enabled field to true, you will also have to configure the properties below in the xds-mediator.properties file.

  atna.host : The host name or IP address of the machine on which OpenHIM is installed
  atna.useTcp : Set this to true
  atna.tcpPort : The tcp port on which the ATNA logging service in OpenHIM is listening, should match the port configured in OpenHIM's /etc/openhim/config.json file for the auditing -> servers -> tcp -> port field, the default value is 5052
  atna.secure : Set this to false for a non-production instance otherwise true to communicate over a secure connection

• 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:
  
  

java -jar mediator-xds-1.0.3-jar-with-dependencies.jar --conf xds-mediator.properties

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.
• Assuming you are still on the channels tab, click the edit icon (yellow pencil) on the right, select the Routes tab, you should see the XDS.b Mediator route, click the edit icon on the right, change the value of the host field from localhost to the IP address of the server where OpenHIM is installed. Note that localhost might not work even if you have OpenHIM and the mediator running on the same machine if they are running inside a virtual box.

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.

Upgrade OpenMRS and the SHR modules

• In OpenMRS webapp, click on Administration in the green bar at the top of the page, 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 webservices.rest 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.

Key configurations to make before you start using the setup

1. Create new identifier domains in OpenEMPI see the Manage Identifier Domains page for details, alternatively you could work with an existing one, the Universal IdentifierId Type values for the identifier domains must be set to ISO and the values of the Universal IdentifierId field must be valid OIDs, the SHR requires this, as you can see from the other existing identifier domains, the name and namespace identifier field can be set to be the same as the universal identifier value
2. Agree on an enterprise/global patient identifier domain to use and set it up in OpenEMPI as below
   
   1. On the machine where OpenEMPI is installed, open the  /usr/share/openempi/openempi-entity-3.3.0c/conf/mpi-config.xml file, you should see a global-identifier tag,  change the values if its nested tags to match those of the global ID you came up with.
3. Mediator configurations: Open the xds-mediator.properties 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 shr-cdahandler.id.format 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 Home -> Case Reports -> Configure, set the values of the listed configurations, they have fairly good descriptions, please refer to the CBR module's documentation on how to set them.
   2. The user that submits case reports is required to have a provider account that is linked to their person record.
   3. Go to Home -> Case Reports -> Identifier Mappings and map each local identifier type to one of the  identifier domain you created in step 1 above, the values must be the Universal IdentifierIds of the identifier domains in OpenEMPI you are mapping to.
6. SHR configurations: 
   1. Click on Administration in the green bar at the top of the page, 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/openxds.properties file, there is a validate.patient.id 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.
      

Integration with DHIS2 Tracker

The purpose of this integration is to be able to push case report data to a DHIS2 instance from the shared health record (SHR), whenever a case report is received in the SHR we want to be able to forward this data to DHIS2 tracker, i.e. the patient gets registered and enrolled in a specific program and then submit events to the same program whenever subsequent case reports are received for the same patient, how to set up programs in DHIS2 is beyond the scope of this documentation.

The DHIS2 tracker module needs to be installed in the SHR to provide this functionality and below are details on how to set it up.

• Note that the module has a dependency on the event module, you will need to download the latest build of the module, here is a copy you can download and install.
• Download and install the DHIS2 tracker module.
• It's important to restart the SHR (OpenMRS) instance after installing the above modules for proper functioning.
• Click on Administration in the green bar at the top of the page, under Maintenance select Settings, select Dhis 2 Tracker from the left panel and set the values of the properties according to the descriptions. To find these values in dhis2, go to apps (looks like a phone pad) and maintenance. Under the program section you will find the areas of interest to the DHIS2 tracker module (Program, Tracked entity type and Tracked entity attribute). Once in these sections click actions (3 vertical dots to the right) and select  Show Details. You will find the ID that is needed in tracker module for each attribute.

You will need to create or update an organization unit in DHIS2 and map it to your OpenMRS instance that will be submitting case reports, if you plan on submitting case reports from multiple instances then you will have to do it for each of the instances, please refer to the DHIS2 documentation on how to create/update organization units. An organization unit has a code field, to map your submitting OpenMRS instance to an organization unit, you need to do the following in the SHR

• Create a new location , Click on Administration in the green bar at the top of the page, click Manage Locations and click Add Location
• Set the value of its DHIS2 code location attribute type to match the value of the code field of the mapped location in the DHIS2 instance.
• Set the value of the ExternalId location attribute type to ORGANISATION_EXTENSION^^^&ORGANISATION_OID&ISO where ORGANISATION_EXTENSION and ORGANISATION_OID match the values of the organisation OID and extension configurations in  the submitting OpenMRS instance's respectively, typically they are values of the global properties named casereport.organisationOID and casereport.organisationExtension.

Things to keep in mind:

• For this to work, when submitting a case report for a patient, one of the triggers MUST be New HIV Case for the SHR to register and enroll the patient in the configured program in DHIS2.
• The DHIS2 instance MUST be in the same time zone as the the OpenMRS instances submitting case reports, otherwise depending on the time of the day you submit a case report you might end up with a failure with an error message in the OpenMRS instance's logs saying the event or incident date is in the future, this is because the rest API exposed by DHIS2 tracker doesn't support the time component and time zones for dates.

To view the details in DHIS2, open the Tracker Capture app and on the right panel you should select the org unit mapped to the OpenMRS instance from which you submitted the case report and you should see the patient's record.