OpenHIE Discourse!

On 13 December 2019 our community is offically moving from mailing lists to OpenHIE Discourse as acollaborative communication forum. Learn how you can get started with OpenHIE Discourse!

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

 

Role within DATIM

Mediator

Scripts

API Endpoints

DATIM-OCL Sync

Process shell scripts to perform synchronization requests between DATIM DHIS2 and OCL

openhim-mediator-shell-script

A generic mediator developed by Jembi that can execute shell scripts.

  • datim-sync-mer

  • datim-sync-sims

  • datim-sync-mechanisms

 

DATIM-OCL Export

Used when a person or a computer hits a specific link.  It generates exports for IMAP exports and MER landing page on OHIE Metadata Clearinghouse

openhim-mediator-landing-page

Extension of the openhim-mediator-shell-script that adds support for including URL parameters in the request that are passed on to the scripts.

  • datim-imap-export

  • show-mechanisms

  • show-mer

  • show-sims

  • show-tieredsupport

 

DATIM-OCL IMAP Import

Process IMAP (indicator map) import and status requests.

openhim-mediator-imap-import



  • datim-imap-import

  • datim-imap-status

 

Results Transformation Service

Used by transformation service to map incoming data files from MOH to Datim indicators

openhim-mediator-ocl



??

 

A. Installation

A.1. Installing Mediators

A.1.1. Installing Shell Script Mediator

 

Code Block
languagebash
sudo git clone https://github.com/jembi/openhim-mediator-shell-script.git /usr/share/openhim-mediator-shell-script
sudo vim /usr/share/openhim-mediator-shell-script/config/default.json # Add openhim username, password and url
cd /usr/share/openhim-mediator-shell-script/
sudo  npm install
sudo mkdir /etc/openhim
sudo wget https://raw.githubusercontent.com/jembi/openhim-mediator-shell-script/master/config/default.json
sudo mv default.json /etc/openhim/mediator-shell-script.json
sudo vim /etc/systemd/system/openhim-mediator-shell-script.service


Code Block
languagetext
[Unit]
Description=OpenHIM shell-script mediator
[Service]
WorkingDirectory=/usr/share/openhim-mediator-shell-script
ExecStart=/usr/bin/npm start
Restart=always
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=shell-script-mediator
Environment=NODE_ENV=production
[Install]


Code Block
languagebash
sudo systemctl start openhim-mediator-shell-script
sudo mkdir /opt/openhim-shell-scripts
cd /opt/
sudo git clone https://github.com/OpenConceptLab/ocl_datim.git
sudo chown -R centos:centos /opt/ocl_datim/
sudo chown -R centos:centos /opt/openhim-shell-scripts/
sudo su centos
vim /opt/openhim-shell-scripts/datim-sync-mer.sh
	#!/bin/sh
	python /opt/ocl_datim/syncmer.py true
vim /opt/openhim-shell-scripts/datim-sync-sims.sh
	#!/bin/sh
	python /opt/ocl_datim/syncsims.py true
vim /opt/openhim-shell-scripts/datim-sync-mechanisms.sh
	#!/bin/sh
	python /opt/ocl_datim/syncmechanisms.py true
exit
sudo chmod ug+x datim-sync-mer.sh
sudo chmod ug+x datim-sync-sims.sh
sudo chmod ug+x datim-sync-mechanisms.sh
sudo yum -y install python-pip
cd /opt/ocl_datim/
sudo pip install -r requirements.txt


A.1.2. Installing Landing page mediator


Code Block
languagebash
sudo git clone https://github.com/maurya/openhim-mediator-landing-page.git /usr/share/openhim-mediator-landing-page
sudo vim /usr/share/openhim-mediator-landing-page/config/default.json #Add openhim username, password and url
cd /usr/share/openhim-mediator-landing-page/
sudo  npm install
sudo vim /etc/systemd/system/openhim-mediator-landing-page.service 


Code Block
languagetext
[Unit]
Description=OpenHIM landing page mediator
[Service]
WorkingDirectory=/usr/share/openhim-mediator-landing-page
ExecStart=/usr/bin/npm start
Restart=always
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=landing-page-mediator
Environment=NODE_ENV=production
[Install]


Code Block
languagebash
sudo systemctl start openhim-mediator-landing-page
sudo chown -R centos:centos /usr/share/openhim-mediator-landing-page/
sudo chmod ug+x /opt/ocl_datim/show-imap.sh
sudo chmod ug+x /opt/ocl_datim/show-mechanisms.sh
sudo chmod ug+x /opt/ocl_datim/show-merindicators.sh
sudo chmod ug+x /opt/ocl_datim/show-sims.sh
sudo chmod ug+x /opt/ocl_datim/show-tieredsupport.sh


A.1.3. Installing IMAP IMPORT mediator


 

Code Block
languagebash
sudo git clone https://github.com/maurya/openhim-mediator-imap-import.git /usr/share/openhim-mediator-imap-import
sudo vim /usr/share/openhim-mediator-imap-import/config/default.json # Add openhim username, password and url
cd /usr/share/openhim-mediator-imap-import/
sudo  npm install
sudo vim /etc/systemd/system/openhim-mediator-imap-import.service


Code Block
languagetext
[Unit]
Description=OpenHIM IMAP Import mediator
[Service]
WorkingDirectory=/usr/share/openhim-mediator-imap-import
ExecStart=/usr/bin/npm start
Restart=always
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=imap-import-mediator
Environment=NODE_ENV=production
[Install]

 

 

Code Block
languagebash
sudo systemctl start openhim-mediator-imap-import



 

A.1.4. Installing openhim-mediator-ocl mediator

  • Description: Mediator for MOH to PEPFAR conversion with OCL

    ssh to test.ohie.datim.org

  • Copy the folder `https://github.com/pepfar-datim/DATIM-OCL/tree/master/src/openhim-mediator-ocl` to `/usr/share/openhim-mediator-ocl`

     

 
Code Block
languagebash
sudo vim /usr/share/openhim-mediator-ocl/config/config.json # Add openhim username, password and url
sudo vim /usr/share/openhim-mediator-ocl/config/mediator.json #Put in proper information under config section at the bottom of the file.
cd /usr/share/openhim-mediator-ocl/ 
sudo npm install
 
#add service and start mediator
sudo vim /etc/systemd/system/openhim-mediator-ocl.service


Code Block
languagetext
[Unit]
Description=OpenHIM OCL mediator
[Service]
WorkingDirectory=/usr/share/openhim-mediator-ocl
ExecStart=/usr/bin/npm start
Restart=always
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=ocl-mediator
Environment=NODE_ENV=production
[Install]


Code Block
languagebash
sudo systemctl start openhim-mediator-ocl

Verify the mediator is created:  Login to OpenHIm Admin Console, click Mediators, you should see openhim-mediator-ocl is started (with green color under Last Heartbeat)  

 

A.1.4.1  Create directories

 

Code Block
languagebash
sudo mkdir /etc/oclMediator. # stores uploaded import file
sudo mkdir /var/log/upstart 
sudo mkdir /var/log/upstart/ocl-java-app. # stores logs for java app
sudo mkdir /usr/local/share/ocl # stores config.properties for java app
sudo mkdir /tmp/MOH_files # stores generated xml /zip files based on import file
#grant access to the folder
sudo chown -R centos:centos /var/log/upstart
sudo chown -R centos:centos /var/log/upstart/ocl-java-app

 

A.1.4.2  Create config.properties for java app 

 

Code Block
languagebash
sudo vim /usr/local/share/ocl/config.properties

 

 

Code Block
languagebash
dhis.domain=[https://test.geoalign.datim.org/]
dataStorePath=api/dataStore/MOH_imports/
errorDataStorePath=api/dataStore/MOH_imports_error/
dhis.username=xxxx
dhis.password=xxxx
pollingTimeout=5
ocl.domain=[https://test.ohie.datim.org:5000]
ocl.token=xxxx
adxPath=/tmp/MOH_files/
archivePath=/var/log/upstart/
datastore.useDataStoreForMappings=false
datastore.useDataStoreForMappings.domain=[https://test.geoalign.datim.org/]
datastore.useDataStoreForMappings.username=xxxx
datastore.useDataStoreForMappings.password=xxxx
maxErrorRowsStored=1000

A.1.4.3  Create certificate

  • Login to OpenHim Admin Console from browser on test.ohie.datim.org
  •  Click Certificates
  • + Add Client certificate
  • Use `oclServlet` for name
  • follow instruction to download 2 files: oclServlet.cert.crt, oclSevlet.key.pem
  • convert certificate to p12 format using the 2 files downloaded

Code Block
languagebash
openssl pkcs12 -export -out oclServlet.p12 -inkey oclServlet.key.pem -in oclServlet.cert.crt
  • Ener a password when prompted. Record the password to be used later in A.1.4.6.1.
  • Verify oclServlet is showing under Trusted Certificates in Admin Console
  • put the oclServlet.p12 file and the password in test.geoalign  (# see A.1.4.6.1)

A.1.4.3.a  Alternative method to get the certificate (if the above method doesn't work)

  • Get the oclservlet.p12 and key (the export password) from test system, such as test.geoalign
  • Get the certificate oclServlet.cert.crt file which was used to generate the above .p12 file
  • Drop/Upload the certificate file (oclServlet.cert.crt) to test.ohie using OpenHIM AdminConsole -> Certificates
  • Restart OpenHIM when prompted
  • Put the oclServlet.p12 file and key in test.geoalign (if different) 

A.1.4.4.  Add Channel, Route, Client using Admin Console 

  • Login to OpenHIM Admin Console on test.ohie.datim.org from browser 
  • Create oclServlet client on test.ohie
    1. In the test.ohie OpenHIM navigate to the 'Clients'
    2. Click on the '+Client' button
    3. Give the client a name of ‘MOH data uploader UI’ and ID of 'oclServlet' 
    4. Under Client Certificate choose the oclServlet certificate 
    5. Check the moh-upload role
      1. if moh-upload role does not exist, under Add New Role enter "moh-upload"
    6. Click the 'Save Changes' button

 

  • Create MOH data upload channel 
    • In test.ohie OpenHIM navigate to the 'Channel' interface
    • Click on the '+Channel' button 
    • Give the channel a name of 'MOH data upload channel' and description of 'This channel is used for uploading MOH data on DHIS2 to get PEPFAR mappings' 
    • Under Request Matching
      • which URL patterns will match this channel: '/uploadMoh.*'
      • Which clients should be able to access this channel: 'moh-upload'

    • Under Routes, click Add New Route
      • Route Name: OCL Mediator
      • Route Path: /uploadMoh
      • Host: localhost
      • Port: 3004
      • Click Set Route
    • Click the 'Save Changes' button



A.1.4.5.  Restart the java app

  •  Find the processor id at port 8090 for the java app
    • sudo netstat -nlp | grep 8090
  • Kill the processor id  
    • Example:  sudo Kill 22919
  • restart mediator to start the java app
    • sudo systemctl start openhim-mediator-ocl


A.1.4.6.  Configuraton on test.geoalign

 A.1.4.6.1. ssh to test.geoalign

  • upload the certificate oclServlet.p12 file (from 1.4.3. ) to /tmp 

    Code Block
    languagebash
    sudo mkdir /etc/oclServlet
    sudo mv /tmp/oclServlet.p12 /etc/oclServlet/oclServlet.p12
     


  • create /etc/oclServlet/oclservlet.properties  based on  https://github.com/pepfar-datim/DATIM-OCL/blob/master/src/OclServlet/oclServlet.properties

    Code Block
    languagebash
    sudo vim :/etc/oclServlet/oclservlet.properties


    Code Block
    languagebash
    remoteSystem.useAsync=1
    remoteSystem.domain=https://test.ohie.datim.org:5000
    remoteSystem.mohUploadPath=/uploadMoh
    remoteSystem.username=[leave empty]
    remoteSystem.password=[leave empty]
     
    dhis2.domain=https://test3.global.datim.org
    dhis2.username=xxxx
    dhis2.password=xxxx
     
    certificate.file=/etc/oclServlet/oclServlet.p12
    certificate.key=key/export password from step 1.4.3.
    
    
    


A.1.4.6.2. Login to test.geoalign from browser


A.2. Installing Mediators - using ansible scripts

on local machine:

Code Block
languagebash
sudo git clone https://github.com/pepfar-datim/DATIM-OCL /tmp
sudo vim /tmp/DATIM-OCL/install_scripts/ansible_scripts/ansible_scripts_mediators/mediator_inventory  # Change to proper host names for ohie_server and web_server as needed.  #Change sensibleansible_user name under Ohio_server and web_server 
sudo vim /tmp/DATIM-OCL/install_scripts/ansible_scripts/ansible_scripts_mediators/variables.yaml   
 # add github username to ghusername, add all the needed configurations. Set testingBaseFolder if needed for local or sandbox, leave it empty for test/stage/prod. 
cd /tmp/DATIM-OCL/install_scripts/ansible_scripts/ansible_scripts_mediators
#run the script
ansible-playbook  --key-file <path_to_ssh_user_github_rsa_pem_file>  -i mediator_inventory mediator.yaml # for <path_to_ssh_user_github_rsa_pem_file> such as ~/.ssh/github_rsa.pem


Login to the OpenHIM Admin Console on the Ohie server,  Click on Mediators from the left navigation, and verify the following mediators are created and started:


  • imap-import
  • landing-page
  • shell-script
  • openhim-mediator-ocl
  • opemhim-mediator-authenticator


A.2.1. Manual steps to config OCL Mediator

A.2.1.1  Get the certificate

  • Get the certificate oclServlet.cert.crt file which was used to generate the /etc/oclServlet/oclServlet.p12 file from geoalign.datim.org
  • Login to OpenHIM Admin Console at ohie.datim.org, click Certificates from left, drop/Upload the certificate file (oclServlet.cert.crt) 
  • Restart OpenHIM when prompted

A.2.1.2.  Add Channel, Route, Client using Admin Console 

  • Login to OpenHIM Admin Console on ohie.datim.org from browser 
  • Create oclServlet client on test.ohie
    1. In the test.ohie OpenHIM navigate to the 'Clients'
    2. Click on the '+Client' button
    3. Give the client a name of ‘MOH data uploader UI’ and ID of 'oclServlet' 
    4. Under Client Certificate choose the oclServlet certificate 
    5. Check the moh-upload role
      1. if moh-upload role does not exist, under Add New Role enter "moh-upload"
    6. Click the 'Save Changes' button

 

  • Create MOH data upload channel 
    • In test.ohie OpenHIM navigate to the 'Channel' interface
    • Click on the '+Channel' button 
    • Give the channel a name of 'MOH data upload channel' and description of 'This channel is used for uploading MOH data on DHIS2 to get PEPFAR mappings' 
    • Under Request Matching
      • which URL patterns will match this channel: '/uploadMoh.*'
      • Which clients should be able to access this channel: 'moh-upload'

    • Under Routes, click Add New Route
      • Route Name: OCL Mediator
      • Route Path: /uploadMoh
      • Host: localhost
      • Port: 3004
      • Click Set Route
    • Click the 'Save Changes' button



A.2.1.3  Restart the java app 

From terminal connect to the ohie.datim.org server,

  •  Find the processor id at port 8090 for the java app
    • sudo netstat -nlp | grep 8090
  • Kill the processor id  
    • Example:  sudo Kill 22919
  • restart mediator to start the java app
    • sudo systemctl start openhim-mediator-ocl

Code Block
languagebash
sudo netstat -nlp | grep 8090 #get the processor id
sudo Kill <processor id> #replace with the processor id from above command
sudo systemctl start openhim-mediator-ocl


A.2.1.4. Login to geoalign from browser

B. Management Operations

B.1. Restart the mediators-




B.2. Check logs

  • tail -fn 1000 openhim-mediator-shell-script.log
  • for OCL Mediator
    • tomcat log location on test.geoalign: /var/log/tomcat
    • java app log on test.ohie: /var/log/upstart/ocl-jva-app

 



B.3. Updating scripts