Get Help from Others
Q&A: Ask OpenMRS
Discussion: OpenMRS Talk
Real-Time: IRC Chat | Slack
Also available here.
Also available here.
These analyses are a work-in-progress and open to public comment.
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
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.
You also want to make sure that communication between the systems is over https
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.
You can setup the entire stack of software using docker, for more details see.
Otherwise you can install the individual components, please continue reading.
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 including blank ones for the rest of the prompts, of course you need to accept the Oracle java license. When the installer is running it might prompt you on the command line to enter this mysql root password along the way.
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:
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.
You MUST restart the machine where this SHR is installed for the contents of the new XdsCodes.xml to be loaded.
You MUST set the default locale to English rather than
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
Open the /etc/openhim/config.json file in an editor and set the following properties:
Run the command below:
sudo service openhim-core restart
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
In this guide we use OpenEMPI as the client registry but there is other implementations like MEDIC-CR and OpenPIXPDQ.
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.
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.
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
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
java -jar mediator-xds-1.0.3-jar-with-dependencies.jar --conf xds-mediator.properties
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.
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
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.
If OpenHIM and the mediator are installed on separate machines or if they are installed in the same but inside a virtual box, you might need to change route settings by doing the following, select the Channels tab from the left panel, you should see a new channel named XDS.b Mediator that was created above, 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 host to value from localhost to the IP address of the machine instead.
This should not be done for a production installation, you would need to reinstall a new version of OpenMRS form scratch with the require modules.
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
To successfully submit a case report for a given patient from the OpenMRS point of care system, their preferred identifier must be of an identifier type that is mapped to one in the health information exchange. The universal identifier of the mapped identifier domain in the client registry must be a valid OID, the SHR is the one that requires this. For testing purposes you can set it to a string of numbers separated by dots e.g 22.214.171.124.4.1.21367.2010.1.2.301 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. An identifier domain in OpenEMPI is analogous to a patient identifier type in OpenMRS, also the universal identifier field of an identifier domain in OpenEMPI is equivalent to the name of a patient identifier type in OpenMRS.
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.
The assumption is that you've already setup a program in your DHIS2 instance with a tracked entity type that represents a Person along with the necessary entity attributes, for each of the global properties that have a UID suffix, the value is the UID of the corresponding entity attribute in DHIS2. The values for the Female Option Code and Male Option Code are the codes and not the UIDs of the corresponding options in DHIS2.
Please pay extra attention to the description of the Case Report Encounter Type Name global property
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
Things to keep in mind:
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.