Implementation Guide

Connect to the EMR instance and follow the instructions below. This guide was tested on a dockerised EMR implementation.

A. Install the DHIS2 Integration App

Assuming you have Bahmni installer latest version installed and running successfully.

1. Update your distribution.

   sudo yum update

2. Navigate to the home directory.

   cd /home

3. Clone the binaries repo.

   git clone https://github.com/khobatha/bahmni-app-dhis2-integration-rpms.git

4. Install the dhis integration app.
   Navigate to the binaries folder

   cd bahmni-app-dhis2-integration-rpms

   Install the latest version of the dhis2 integration app

   sudo yum install dhis-integration-1.0-1_060721.noarch.rpm

B. Configure DHIS2 Integration: Security

1. Download and place the ssl.conf file.

   
   cd /etc/httpd/conf.d/ 
   
   wget https://raw.githubusercontent.com/Possiblehealth/possible-config/89662e8e823fac3dbcaf111aa72713a63139bb03/playbooks/roles/possible-dhis-integration/templates/dhis_integration_ssl.conf
   
   

2. Navigate to the ssl.conf file and disable (comment out) all configuration entries (SSLCertificateFile, SSLCertificateKey, SSLCertificateChainFile) containing hiels.org.

   nano /etc/httpd/conf.d/ssl.conf
   

3. Use openssl to generate a self signed certificate, valid for 1 year, and copy it to /etc/bahmni-certs. NB: Use hostnamectl command to check the static hostname of the container and enter it as the Common Name (CN) when prompted for the CN by the openssl tool.

   cd ~

   openssl req -newkey rsa:4096 -x509 -sha256 -days 365 -nodes -out dhis2_integration_app.crt -keyout dhis2_integration_app.key

   cp dhis2_integration_app.crt dhis2_integration_app.key /etc/bahmni-certs 

4. Update /etc/httpd/conf.d/ssl.conf with new configuration entries for SSLCertificateFile and SSLCertificateKey.

   SSLCertificateFile /etc/bahmni-certs/dhis2_integration_app.crt

   SSLCertificateKeyFile /etc/bahmni-certs/dhis2_integration_app.key

5. Restart http service to reload the new ssl template configurations and verify that it is running.

   sudo systemctl restart httpd

   sudo systemctl status httpd

6. Install the self-signed ssl certificate into the system keystore.
   Navigate to the home directory

   cd ~

   The next step is now to import the certificate into the system keystores (cacerts). NB: You may use sudo find / -name cacerts to locate the exact path to your system keystore. Use the container static hostname as an alias.

   keytool -importcert -alias 0568561e1f23 -keystore /usr/java/jre1.8.0_131/lib/security/cacerts -storepass changeit -file dhis2_integration_app.crt

   keytool -importcert -alias 0568561e1f23 -keystore /etc/pki/java/cacerts -storepass changeit -file dhis2_integration_app.crt

7. Restart dhis-integration service to reload the new security configurations and verify that it is running.

   sudo systemctl restart dhis-integration

   sudo systemctl status dhis-integration

C. Configure DHIS2 Integration App: Properties

1. Update the properties file of the DHIS2 integration app with right configuration. NB: Use the hostname of the EMR container in the openmrs.root.url and openmrs.db.url as exemplified below.
   Navigate to the propertiles file.

   nano /etc/dhis-integration/dhis-integration.yml

   Key	Description	Example
   openmrs.root.url	Url to access Openmrs service	https://[host-d]/openmrs/ws/rest/v1
   bahmni.login.url	When user isn't logged in, then user is redirected to this url.	https://[host-id]/bahmni/home/#/login?showLoginMessage
   reports.url	Bahmni reports url. Used for downloading reports.	https://[host-id]/bahmnireports/report
   reports.json	This file contains configurations of DHIS2 reports.	/var/www/bahmni_config/openmrs/apps/reports/reports.json
   dhis.config.directory	This folder contains DHIS2 integration configurations program wise.	/var/www/bahmni_config/dhis2/
   dhis.url	The DHIS2 government server instance url.	Ex. 1: http://100.100.100.100:8080/ Ex. 2: http://200.100.20.30:8888/hmistest/ Note that the url could be at domain or ip address level (ex1) or could be at a specific path(ex2)
   dhis.user	The username to access DHIS2 instance.	[username]
   dhis.password	The password for the DHIS2 user.	[password]
   openmrs.db.url	Mysql connection url to access "openmrs" database. Set valid user and password in the url.	jdbc:mysql://[host-id]/openmrs?user=[username]&password=[password]
   odoo.db.url	Postgresql connection url to access "odoo" database. Set valid container ip, user and password in the url.	jdbc:postgresql://[erp-container-ip]/odoo?user=[username]&password=[password]
   submission.audit.folder	All DHIS2 submissions are stored in this directory. Ensure the directory exists and "bahmni" user has access to it, or configure a different directory.	/dhis-integration-data
   server.port	Server config. Port for server to listen to.	8040
   server.context-path	Server config. Mapping incoming requests.	/dhis-integration/
   dhis.integrator.root.url	URL to access dhis-integration app service	http://[host-id]:8040
   dhis.integrator.scheduler.user	Username of openmrs user with full reports privileges .e.g facility data clerk	[user]
   dhis.integrator.scheduler.password	Password of openmrs user with full reports privileges.	[password]

2. Ensure Bahmni reports service is installed and running successfully.

   
     systemctl status bahmni-reports
    

3. Restart ssl and dhis-integration services.
   Restart httpd

   systemctl restart httpd

   Restart dhis-integration service

   systemctl restart dhis-integration

   The DHIS2 Integration App should now be accessible from the landing screen, given that the user has reporting privileges.

D. Configure DHIS2 Integration App: OpenMRS Privileges

Create a new OpenMRS privilege named "Submit DHIS Report" and grant it to all user groups that will use the App.

1. Navigate to OpenMRS home page (e.g localhost/openmrs).
2. Select Administration.
3. Select Manage Privileges.
4. Select "Add Privilege" and add the "Submit DHIS Report" privilege.
5. Select "Manage Roles" and add the "Submit DHIS Report" privilege to all user roles that need to use the DHIS2 Integration App to sync reports to DHIS2.

E. Configure New Program and Map to DHIS2

1. Load a simple OpenMRS report to map to DHIS2:
   Navigate to /development inside the EMR container:

   docker exec -it bahmni_docker_emr-service_1 bash

   cd /development/bahmni_config_release/

   Disable the release version of bahmni_config092 and pull a development version containing the test report:

   mv bahmni_config092 bahmni_config092_bkp

   git clone https://github.com/khobatha/bahmni_config092.git

   Refresh Bahmni landing page and to go to Reports and ensure that report TESTS-01 | DHIS2 Integration App SYNC Test report has been loaded and that it runs.
2. View configs for the TESTS-01 | DHIS2 Integration App SYNC Test report:
   View the report implementation:

   cd bahmni_config092/openmrs/apps/reports/sql/

   nano dhis2_integration_test.sql

   View the configuration that registers the report in Bahmni for viewing under Bahmni reports. You must scroll to the end of the config file to see the configuration entry for the test report:

   cd bahmni_config092/openmrs/apps/reports/

   nano reports.json

3. Put the following configuration in the TESTS-01 | DHIS2 Integration App Sync Test report reports.json config to make it a DHIS2 program and therefore have it listed under the Integration App for mapping to DHIS2.
   Example: Safe motherhood program

   "DHISProgram": true

4. Navigate to the DHIS2 Integration App on Bahmni and ensure that the TEST-01 report is now listed under DHIS2 programs.
5. Create DHIS2 mapping configs for the TESTS-01 | DHIS2 Integration App Sync Test report:
   Navigate to the DHIS2 Integration App mappings configs directory:

   cd bahmni_config092/dhis2

   Create a new json file to store the mappings for the TESTS-01 report:

   touch TESTS-01_DHIS2_Integration_App_Sync_Test.json

6. Define the mappings for the TESTS-01 report in TESTS-01_DHIS2_Integration_App_Sync_Test.json:

   DHIS2 mapping configuration file should have the following structure:

   
   {
     "orgUnit": "<orgUnitId | find it from DHIS instance>",
     "reports": {
       "<name of 1st sub report | find it from reports.json>": {
         "dataValues": [
           {
             "categoryOptionCombo": "<category option combination id | find it from DHIS instance>",
             "dataElement": "<data element id | find it from DHIS instance>",
             "row": <row number of the cell | find it from output of the SQL report>,
             "column": <column number of the cell | find it from output of the SQL report>
           },
           {
             "categoryOptionCombo": "<category option combination id | find it from DHIS instance&lgt;",
             "dataElement": "<data element id | find it from DHIS instance>",
             "row": <row number of the cell | find it from output of the SQL report>,
             "column": <column number of the cell | find it from output of the SQL report>
           },
           ............more data element mappings............
         ]
       },
       "<name of 2nd sub report | find it from reports.json>": {
       "dataValues": [......]
       },
       "<name of 3rd sub report | find it from reports.json>": {
       "dataValues": [......]
       },
       ............more sub report mappings............
     }
   }
   

   An example configuration for Safe Motherhood program will look like the following Example: Safe motherhood program

   Key	Description
   orgUnit	This is the organisation unit ID from DHIS
   reports	<>This is list of reports which are the inner reports of concatenated report of the program. Each report name is a unique key in this object. 'Antenatal Checkup' is one of the inner reports configured in concatenated report, for example.
   dataValues	This is list of data element mappings. Each mapping maps a cell in SQL output to a dataElement in DHIS.
   categoryOptionCombo	This is the 'category option combination id' of the dataElement in DHIS.
   dataElement	This is the 'data element id' of the dataElement in DHIS.
   row and column	This 'row and column' numbers refers to a particular cell in the output of configured SQL.

   Notes: To find out the orgUnit Id, dataElement Id, category option combo Id do the following:

   1. Access the DHIS2 government server in your browser.
   2. Open data entry apps and select appropriate organisation and location.
   3. Once the data entry forms are visible, click on the input boxes where you enter the data.
   4. Right click on the input box and select "Inspect" from the options.
   5. Copy the Id of the html element from window (See image), it would look like the following string: "kSnqP4GPOsQ-kdsirVNKdhm-val".
   6. This string is in the format of "dataElementId - categoryOptionComboId - ...."
   7. These dataElementId and categoryOptionComboId need to be used in DHIS2 configuration file. Refer the below image.