MHero Installation and Configuration
From IHRIS Wiki
- 1 mHero Installation and Configuration
mHero Installation and Configuration
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.
- iHRIS-it is an integrated Human Resource Information System which is used to track and manage health workforce data.
- 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.
- 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.
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 the Health Worker Registry (HWR) 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 HWR.
To setup mHero, iHRIS,Rapidpro and HWR needs to be connected together. There are two connections in here:
- Connecting iHRIS and HWR
- Connecting HWR and Rapidpro
- Push all Health workers to Rapidpro.
- Pull all created Rapidpro contacts back to HWR.
Connecting iHRIS and HWR.
The HWR is built on an international standard called Care Services Discovery (CSD). So to connect iHRIS and HWR,it will need to make iHRIS data to conform to CSD and then this data can be loaded to the HWR. 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 HWR and this video tutorial - https://www.youtube.com/watch?v=ev-my7-ZQ0I explains how to configure the HWR to pull iHRIS published CSD documents. The simplest way of saying this is,iHRIS publishes health worker data in CSD format and HWR subscribes to the iHRIS CSD data.
Connecting HWR and Rapidpro.
This connection requires that each health worker that has a valid phone number in HWR 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 the HWR with they corresponding Rapidpro ID,this is done in order that the HWR 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.
- 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 the HWR that have phone numbers. The following are the explanations of some variables that needs to be set in the synchronize.php script:
$openinfoman = array(
Replace localhost and port number with an appropriate openinfoman server address and port number. Replace CSD-Providers-Connectathon0150120 with an appropriate CSD documents in Openinfoman that created during iHRIS and HWR connection.
'auth_token' => 'xxxxxxxsupersecretxxxxxxxx',
'group_name' => 'mHero Group'
- 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="xml"> export RAPIDPRO_AUTH_TOKEN=XXXXXXX. </source> The synchronize.php script can be executed as follows from command line: <source lang="xml"> php synchronize.php </source>
- 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="xml"> cd /var/lib/openinfoman/resources/service_directories </source>
- Run the below command to create an empty document. <source lang="xml"> 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="xml"> 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.
- Login into iHRIS.
- 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>
- Then Rapidpro details should now be filled as follows:
Navigate to mHero_person_workflow Page Builders by clicking the following links:
Configure System → Page Builder → Scroll down to mHero_person_workflow and click on Edit Page link → Page and Primary Form Configurations.
- 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 HWR 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 the HWR.
- Repeat the procedures in step 3 above to configure mHero_person_workflow page.
Starting a Work-flow
Work-flows can be started by either using reports (Bulk Work-flows) or by accessing individual health worker profile page (View page).
- Starting a Bulk Workflow To start workflows using reports,visit the home page and click the mHero link. The report to be used should be selected and then display the list oh health workers by clicking the 'select participants' button. Both of the reports has many filters at the bottom which allows to start workflows to health workers based on specific criterion. Once done,the workflow to be used should now be selected. The workflow can be started to selected healthworkers by clicking the Start Flow button. The results of the workflow can be viewed by selecting the workflow and click on the View Results button.
- Starting a Workflow Through the Health Worker Profile. Workflows can be started in this way by searching the Health Worker through search reports and click the health worker name to open the health worker profile. Once the profile is opened,at the top right corner there is the mHero logo,once that link is clicked,the mHero page will open from which the workflow to be started to this health worker can be selected and started by clicking the start Workflow. The workflow activity can be seen by clicking the 'View Results' button.