MHero Installation and Configuration

mHero Installation and Configuration

Note: Some of this page is in draft form and may not work correctly just yet. In particular the OpenHIM installation docs. This will be rectified in the coming months.

Introduction and Overview

mHero is a free SMS mobile phone based communications system between MOH staff,Health Workers and Community Health Workers. This is achieved by the interoperability between Intrahealth's iHRIS (or any HRIS with CSD compliant) and UNICEF's Rapidpro and utilizing the OpenHIE architecture. The platform uses health workforce data to target specific communications based on cadre,location and other information. Communications, which can be triggered both centrally and locally, go far beyond traditional “message blasts” offered by many technology vendors. Real-time monitoring, complex multi-path surveys, monitoring and detailed analysis can be conducted with ease. This tutorial will use iHRIS as a HRIS.

mHero Components

1. iHRIS-it is an integrated Human Resource Information System which is used to track and manage health workforce data.
2. Rapidpro-is a free and open source framework designed to send and receive data using basic mobile phones, manage complex workflows, automate analysis and present data in real-time.
3. Health Worker Registry- It is an OpenHIE component used to bring health workforce information together from variety of sources and represent that information in a common format against a common standard in order to facilitate the use of health workforce information across the health information system. Health Worker Registry is implemented by Openinfoman,this tutorial will be using the two terminologies interchangeably.
4. OpenHIM - a component that provides security and access control mechanisms for mHero

About the OpenHIM

OpenHIM stands for the Open Health Information Mediator. The OpenHIM is an interoperability layer: a software component that eases integration between disparate information systems by connecting client and infrastructure components together. Its role is to provide a facade to client systems - providing a single point-of-control for defining web service APIs and adapting and orchestrating requests between infrastructure services. While doing this the OpenHIM also provides extensive security and access control mechanisms that enables the user to protect personal information within an HIE. It also enables monitoring and alerting services to ensure that the HIE is always running optimally.

OpenHIM security and privacy

Privacy and security are vital components of a coherently designed HIE. The OpenHIM is a cornerstone on which HIEs are built and it specialises in managing the interfaces on which systems interact with the HIE and on which components of the HIE communicate with each other. Therefore, the OpenHIM employs a number of mechanisms to ensure that traffic to and from an HIE is kept private and secure.

The OpenHIM provides the following features to ensure that personal information is protected:

1. It makes it easy to ensure that traffic coming to the HIE or within it is encrypted. It does this by providing a certificate management facilities.
2. It provides authentication mechanisms to ensure that only systems that are known and trusted can access the HIE services.
3. It provides access control mechanisms to ensure that only systems that actually need access to certain services are allowed to access them.

How the OpenHIM fits into the mHero architecture

Within the context of mHero, the OpenHIM performs a few vital functions.

1. It triggers the synchronization between RapidPro and the OpenInfoMan.
2. It provides visibility into the messages being exchanged. This allows the user to ensure that the data exchange is occurring correctly.
3. It ensures that the communication between components occurs securely and it logs the transactions for historical and audit purposes.
4. It provides authentication and authorisation mechanisms to control access to the OpenInfoMan documents

The OpenHIM provides polling channels to trigger the synchronization between RapidPro and the OpenInfoMan. These polling channels execute periodically and trigger an mHero mediator which in turn pulls data out of the OpenInfoMan and pushes it into RapidPro. To learn more about polling channels please see the OpenHIM docs here.

The OpenHIM provides a web console that enables the user to view these synchronization message. This enables any problems to be debugged effectively and provides confidence that the synchronization is working effectively.

The OpenHIM was designed to protect an HIE by providing mechanisms to secure transactions between various components of the HIE. It can ensure that requests that access certain OpenInfoMan documents come from known and authorised sources.

Within mHero, the OpenInfoMan contains a number of documents which contain health worker and facility information. The OpenHIM prevents unauthorised access to these documents by implementing a role-based access control mechanism. This allows documents with sensitive information to be secured and documents with non-sensitive information to be as open and accessible as necessary.

Configuring the OpenHIM for mHero

Configuring the OpenHIM to work with mHero is fairly straightforward. A debian package has been created that will automatically configure the OpenHIM for the mHero context. This takes care of most of the configuration that is require. You can find this package here: https://github.com/jembi/openhim-config-mhero.

To install it simply execute the following on server to host the OpenHIM:

<source lang="bash"> sudo add-apt-repository -y ppa:openhie/release sudo apt-get update sudo apt-get install openhim-console openhim-core-js openhim-mediator-mhero </source>

After that the OpenHIM console will be accessible on http://localhost. For more information about how to use the OpenHIM console and edit the base configuration, see http://openhim.readthedocs.org/en/latest/user-guide/index.html.

Individual Components Installation

iHRIS can be installed by referring to its installation page which is http://wiki.ihris.org/wiki/Installing_iHRIS_4.2 while OpenInfoman can be installed by referring to OpenInfoMan installation page which is https://github.com/openhie/openinfoman and Rapidpro can be installed by referring to the Rapidpro installation page http://rapidpro.github.io/rapidpro/docs/development/.

Linking iHRIS,Rapidpro and OpenInfoman.

To setup mHero, iHRIS,Rapidpro and OpenInfoman needs to be connected together. There are two connections in here:

1. Connecting iHRIS and OpenInfoman
2. Connecting OpenInfoman and Rapidpro
   • Push all Health workers to Rapidpro.
   • Pull all created Rapidpro contacts back to OpenInfoman.

Connecting iHRIS and OpenInfoman.

The OpenInfoman is built on an international standard called Care Services Discovery (CSD). So to connect iHRIS and OpenInfoman,it will need to make iHRIS data to conform to CSD and then this data can be loaded to OpenInfoman. This video tutorial - https://www.youtube.com/watch?v=oxmRhW4Q2T4 shows how CSD documents can be generated and published in iHRIS. Generated CSD documents can then be pulled by the OpenInfoman and this video tutorial - https://www.youtube.com/watch?v=ev-my7-ZQ0I explains how to configure OpenInfoman to pull iHRIS published CSD documents. The simplest way of saying this is,iHRIS publishes health worker data in CSD format and OpenInfoman subscribes to the iHRIS CSD data.

The process above of publishing iHRIS data into CSD standard and openInfoman fetching iHRIS published CSD data has been automated within openHIM by the use of a mediator called openhim-mediator-mhero which is a nodejs service that is connected to openHIM to automate the whole process

Connecting OpenInfoman and Rapidpro.

This connection requires that each health worker that has a valid phone number in OpenInfoman to be created in Rapidpro as a contact. Once these contacts are created in Rapidpro,they will then need to be pulled and converted to CSD and then pushed to OpenInfoman with they corresponding Rapidpro ID,this is done in order that OpenInfoman knows which Health worker has an associated contact in Rapidpro. This connection can be achieved by two PHP scripts which all comes with the openinfoman-rapidpro library - https://github.com/openhie/openinfoman-rapidpro and can both be found under resources/tools.

1. https://github.com/openhie/openinfoman-rapidpro/blob/master/resources/tools/synchronize.php. This script is used to create contacts in Rapidpro of all health workers in OpenInfoman that have phone numbers. The following are the explanations of some variables that needs to be set in the synchronize.php script: <source lang="bash"> $openinfoman = array( url'=>'http://localhost:8984/CSD/csr/CSD-Providers-Connectathon0150120/careServicesRequest/urn:openhie.org:openinfoman-rapidpro:get_json_for_import/adapter/rapidpro/get' ); </source> Replace localhost and port number with an appropriate openinfoman server address and port number. Replace CSD-Providers-Connectathon0150120 with an appropriate Openinfoman CSD document that was created during iHRIS and OpenInfoman connection. <source lang="bash"> $rapidpro= array( 'url' =>'https://app.rapidpro.io/api/v1/contacts.json', 'auth_token' => 'xxxxxxxsupersecretxxxxxxxx', 'group_name' => 'mHero Group' ) </source>
   • url-is the Rapidpro API for adding contacts,replace https://app.rapidpro.io with your appropriate Rapidpro address.
   • auth_token-This is the Rapidpro security token which can be found in webhook under Account Details.
   • group_name is the Rapidpro group name to which you want the contacts to be created,if this is left blank then no contact that will be created in any group.

   These can be set directly into the script but they can also be set through environmental variables I.e <source lang="bash"> export RAPIDPRO_AUTH_TOKEN=XXXXXXX. </source> The synchronize.php script can be executed as follows from command line: <source lang="bash"> php synchronize.php </source>

2. https://github.com/openhie/openinfoman-rapidpro/blob/master/resources/tools/iti_74_query_for_updated_services.php. This script is used to pull all created contacts in Rapidpro. The variables for this script are similar to the one in synchronize.php with one more added variable which is the slug,this can be found in Rapidpro under organization information of Account Details. Before running the script for the first time,it will require to create an empty document in Openinfoman to be used for storing the output of the script of which are Rapidpro contacts converted in CSD format. To create the document,follow these 2 easy steps
   • Go to service directories of Openinfoman <source lang="bash"> cd /var/lib/openinfoman/resources/service_directories </source>
   • Run the below command to create an empty document. <source lang="bash"> sudo touch file_name.xml </source> replace file_name with the name of the file to be created.

   Once the file is created,run the script as follows: <source lang="bash"> cd /var/lib/openinfoman/resources/tools; php iti_74_query_for_updated_services.php > ../service_directories/file_name.xml </source> Make sure that you have root access in order to be able to write into the file_name.xml. After that,go to the front-end of Openinfoman and navigate to CSD Endpoints and then click the Load and Register Sample Service Directories link. If this is the first time running the script,the name of the file should be selected and then initialized by clicking the initialize link,but if this isn't the first time running the script,the file should just be reloaded by clicking on the reload link in order that it pulls any new contacts.

Enabling mHero Module in iHRIS

To enable mHero in iHRIS,mHero and IL-HWR modules will need to be enabled in-line with csd-data-address-type,csd-data-dow,csd-data-gender,csd-data-provider-status,csd-data-provider-data-model,csd-search and CSD-data modules in the site configuration. These modules can be enabled by just adding the below lines of codes between the <metadata></metadata> inside the site configuration file. <source lang="xml"> <enable name="csd-data-address-type" /> <enable name="csd-data-dow" /> <enable name="csd-data-gender" /> <enable name="csd-data-provider-status" /> <enable name="csd-data-provider-data-model" /> <enable name="IL-HWR" /> <enable name="mHero" /> <enable name="csd-search" /> <enable name="CSD-data" /> </source>

Configuring mHero module inside iHRIS

Various Rapidpro work-flows needs to be instantiated from iHRIS to individual health worker or to a group of health workers. For Rapidpro work-flows to be visible from iHRIS front-end,below configurations will need to be done.

1. Login into iHRIS.
2. Navigate to mHero Page Builders by clicking the following links: <source lang="xml"> Configure System → Page Builder → Scroll down to mHero and click on Edit Page link → Page and Primary Form Configurations. </source>
3. Then Rapidpro details should now be filled as follows:
   • Rapidpro Token is the security token which can be found under the Account Details on the top right corner of Rapidpro.
   • Host- This is the Rapidpro address.
   • Organization Short Name – Is the slug which can be found under organization information of Account Details.
   • CSD Host-This is the OpenInfoman address in this format http://localhost:8984/CSD/csr/Rapidpro-Contacts/careServicesRequest where by Rapidpro-Contacts is the directory holding Contacts pulled from Rapidpro to OpenInfoman.
Navigate to mHero_person_workflow Page Builders by clicking the following links: <source lang="xml"> Configure System → Page Builder → Scroll down to mHero_person_workflow and click on Edit Page link → Page and Primary Form Configurations. </source>
4. Repeat the procedures in step 3 above to configure mHero_person_workflow page.

See also Starting A Workflow Starting A Workflow in iHRIS

Day-to-day operation of the HIE

The OpenHIM is the central place that provides a view into how the HIE is performing. In day-to-day operation of mHero the OpenHIM web console should be monitored periodically to ensure that the synchronization of data is occurring successfully. It can also provide useful statistics about the performance of the OpenHIM for larger mHero implementations.

It is useful to plan for this and assign a technical person that understand the exchange quite well to monitor this console periodically to ensure the smooth running of the HIE. This person will be instrumental in identifying problems early and ensuring that they get resolved correctly.

Related Pages

Using mHero