This needs to be generalized for all O2 / O3 deployments, this is a POC based on OpenMRS 2.8 in Cote d’Ivoire

Draft

Prepared by I-TECH DIGI and ITECH-CIV July 2024

INTRODUCTION

Welcome to the OpenMRS Connection to HAPI FHIR Server Implementer's Guide. This guide provides a step-by-step approach for implementers to establish a connection between OpenMRS and a HAPI FHIR server, facilitating seamless data exchange. It covers essential setup processes, configuration, and deployment strategies applicable to OpenMRS 2.x (O2) and OpenMRS 3.x (O3) environments.

INTENDED AUDIENCE

This guide is intended for implementers responsible for implementing and managing an OpenMRS Health Information Exchange implementation. It assumes a basic understanding of Docker, Git, and web-based application management. Whether you are setting up a new instance or integrating an existing implementation, this guide provides the necessary steps to ensure a successful implementation.

GETTING STARTED: LOCAL SETUP

HOW TO SET UP THE PROJECT LOCALLY

1. Create a Project Directory:

   • Create a directory for the project on your local machine.

   • Navigate to the created directory.

2. Clone the Repository:

   • Open Visual Studio Code (VS Code) within the project directory.

   • Clone the repository using the following command

     git clone https://github.com/SIGDEP-3/SIGDEP-3-Docker-Setup.git

   • Change into the project directory:

     cd SIGDEP-3-Docker-Setup/

3. Review Docker Configuration:

   • Open the docker-docker-local-pilot.yml file to review the services configured:

     • Sigdep3: Configures the OpenMRS service.

     • Sigdep3-db: Configures the OpenMRS database.

     • OpenHIM IOL: Configures MongoDB, OpenHIM console, and OpenHIM core.

     • Pipeline-controller: Configures FHIR analytics.

4. Start the Project:

   • Run the following command to start the services:

     sudo docker compose -f docker-compose-local-1.yml up

How to Start the OpenMRS Instance Locally

1. Start OpenMRS:

   • Open a new terminal and run:

     bash

     Copy code

     sudo docker compose -f docker-compose-local-pilot.yml up sigdep3 sigdep-db

2. Access the OpenMRS Login Page:

   • Open a browser and navigate to http://localhost:8080/openmrs.

   • If prompted to initialize the database, wait a few minutes.

3. Login and Configure Search Index:

   • Login with admin and Admin123.

   • Navigate to Administration > Maintenance > Search Index.

   • Click on Rebuild Search Index.

1. To get started with setting up the project locally, create a directory for the project on your local machine and change directory to the created project.

2. Open the visual studio code in the project directory

3. Navigate to the project GitHub repository and click on SIGDEP-3/SIGDEP-3-Docker-Setup

4. Copy the project url to clipboard

5. On visual studio, clone the project in your project folder using the command; git clone https://github.com/SIGDEP-3/SIGDEP-3-Docker-Setup.git

6. Upon successful cloning of the project, change the directory into the project using the command; cd SIGDEP-3-Docker-Setup/

7. Click on the docker-docker-local-pilot.yml file

Note: The following services are setup in the docker-docker-local-pilot.yml file.

• The Sigdep3 service displays the configuration for the OpenMRS

• The Sigdep3 db represents the database service for the OpenMRS instance

• The OPENHIM- Interoperability layer (IOL)service is configured for the Mongo database, OpenHIM console and OpenHIM core respectively.

• The pipeline-controller is configured for FHIR analytics.

8. At this juncture spin up the project by executing startup the project by running the command; sudo docker compose -f docker-compose-local-1.yml up. The project will be started successfully.

HOW TO STARTUP THE SIGDEP3 EMR LOCALLY 

1. Upon successfully spinning up the project locally, the next step is to spin up the OpenMRS instance locally. Open a new terminal and startup the SIGDEP3 instance by executing the command sudo docker compose -f docker-compose-local-pilot.yml up sigdep3 sigdep-db. The SIGDEP3 instance will be started.

2. Click on the README.md file to open. 

3. Open a new terminal and execute the commands git lfs fetch,git lfs checkout and git lfs pull respectively

4. Start up your browser and type the url;  localhost:8080/openmrs. The login page is displayed.

Note: You might encounter the system initializing the database setup before the login page is displayed. Please be patient this may take a few minutes to complete. 

5. Login to the instance. The default username and password are admin | Admin123.

6. Upon successful login click on Administration.

7. At this juncture, the search index should be rebuilt. Click on Search Index under Maintenance.

Note: The search index must be rebuilt in order for the instance to execute any search. For instance, searching the concept dictionary or searching for a patient.

8. Click on the Rebuild Search Index button.

Note: The server-side will execute the search index rebuild

Note: Upon the completion of the search index the search index rebuilding, a notification will be displayed

Note: A search in the dictionary will return the respective result(s). The illustration below shows a CD4 concept search. 

HOW TO STARTUP THE OPENHIM-IOL

The OpenHIM Interoperability layer service is started  during the initial spinning up of the project. 

1. To access the OpenHIM instance, enter the url http://localhost:9000/ on your browser. The Console heartbeat will be displayed. The login page is displayed

2. Ideally, you should enter the login credentials to proceed. However, this is a new installation. Notice the self signed certificate error message.

3. Click on the link text field.

4. Click on the Advanced button.

5. Click on proceed to localhost (unsafe)

Note: Upon clicking on proceed to localhost, the OpenHIM console Heartbeat is displayed.

6. Click on the previous tab on the browser. Log on to the instance by entering the credentials; username: root@openhim.org and password: OpenHIM and clicking on the Login button

7. Upon successful login click on Transactions. The There are no transactions for the current filters  message is displayed.

8. Click on Channels. The client registry channels are displayed as well as the central FHIR server channel.

9. Click on the central FHIR server channel. 

Note: Upon clicking on the channel, the basic info tab is displayed. This tab displays the information about the channel. For instance, the name, description of what the channel does as well as the methods.

10. Click on the Request Matching tab. The url pattern for matching the channel is displayed as well as the clients.

11. Click on the Route tab. The central fhir server configuration is displayed.

12. Click on the pencil configuration to view the configuration. The route name, host, port, route path, route path transform, basic authentication username and basic authentication password are displayed.

Note: These configurations are set on the project under the local-test-openhim-config.json file as illustrated below.

HOW TO STARTUP THE DATA PIPELINE 

1. To startup the data pipeline, open a new terminal and execute the command: sudo docker -f docker-compose-pilot.yml up pipeline-controller 

2. Type the url http://localhost:8090/ on your  browser. Upon a successful pipeline startup, the FHIR Pipelines Control Panel is displayed.

Note: The streaming pipeline configurations are displayed under the application.yml file of the local-streaming-pipeline folder of the project. This file displays the FHIR module loaded on the SIGDEP-3 instance, as well as the patient resources under the resourceList which are:

patient,Encounter,Observation,Condition,Practitioner,Location,MedicationRequest

HOW TO SEND A NEW PATIENT RESOURCES TO THE CENTRAL FHIR SERVER

In  this illustration, a new patient is created on the SIGDEP3 OpenMRS instance and the patient resource is routed via openHIM to the FHIR central server.

1. To get started, Login to the instance. The default username and password are admin | Admin123.

2. Click on the Find/Create Patient menu item

3. Create a new person by filling  the person name, birthdate, gender and click on the Create Person button. 

4. Fill in the middle name, family name, the ID Number and click on the Save button. The patient dashboard is displayed.

5. Execute an incremental run on the local pipeline controller by clicking on the Run Incremental button

5. Log on to the OpenHIM local instance using the credentials; 

• username: root@openhim.org 

• password: openhim 

and click on the Login button

Note: Upon login, the transaction log of the local instance displays the POST transaction to the remote HAPI FHIR Server

6. Log on to the remote instance by entering the credentials; username: root@openhim.org and password: OpenHIM and clicking on the Login button

Note: Upon login, the transaction log of the local instance displays the POST transaction to the remote HAPI FHIR Server

Note: At this juncture, the pipeline is executed 

7. Access the FHIR consolidated server by typing the url: https://test1.cihis.org/fhir/ 

8. Filter the resource type by Patient to view the resources 

9. Filter the patient resource by lastUpdated to view the newly created patient Jane Doe on the Hapi FHIR server.

HOW TO SEND A LABORATORY ENCOUNTER RESOURCES TO THE CENTRAL FHIR SERVER

In  this illustration, a new laboratory order is created on the SIGDEP3 OpenMRS instance and the observation resource is routed via openHIM to the FHIR central server.

1. To get started, copy the patient ID number from the patient dashboard.

2. Click on the Demande d’examen menu item

3. Enter the Patient identifier and click on the view patient button.

4. Select the date and click on new order button

5. Fill in the form to completion.

6. Click on the save button. The order will be saved successfully.

7. Log on to the OpenHIM local instance using the credentials; 

• username: root@openhim.org 

• password: openhim 

and click on the Login button

Note: Upon login, the transaction log of the local instance displays the POST transaction to the remote HAPI FHIR Server

8. Log on to the remote instance by entering the credentials; username: root@openhim.org and password: OpenHIM and clicking on the Login button

Note: Upon login, the transaction log of the local instance displays the POST transaction to the remote HAPI FHIR Server

Note: At this juncture, the pipeline is executed 

9. Access the FHIR consolidated server by typing the url: https://test1.cihis.org/fhir/ 

10. Filter the resource type by observation to view the resources.

11. Filter the observation resource by lastUpdated to view the newly created observation for patient Jane Doe on the Hapi FHIR server.

GETTING STARTED: REMOTE SETUP 

In this section, we shall demonstrate how to connect via secure shell to an instance SIGDEP3 and start up the project remotely. A data management system Apache Hive is also used to display flattened data that can be used for visualization. 

To get started, the following prerequisites are required for the remote setup;

1. Database management system 

2. Setup SSH connection to the remote instance of OpenMRS SIGDEP3 

SSH CONNECTION

1. To begin with, a secure shell  is established to the OpenMRS instance server test1.chis.org. Therefore an implementer is required to set up a public key for SSH connection to the instance. The illustration below shows the private and public SSH keys. The command cat id_rsa.pub will display the public SSH key. The key is used to authenticate on the remote instance.

2. Upon successful setup of the public SSH on the remote instance. The instance is accessed on the Visual Studio Code. Click to open a remote window.

3. Click on Connect to Host

4. Click on the instance to connect. 

5. Upon successful connection to the instance. Click on a new terminal.

HOW TO STARTUP THE SIGDEP3 EMR REMOTELY

1. Execute the command docker ps to list the docker containers.

Note: Notice the port on which the SPARK database should be exposed 

2. Change directory into the project by executing the command; cd code/SIGDEP-3-Docker-Setup

3. Startup the project by executing the command; docker compose -f docker-compose-remote-traefick.yml up 

The project will be started successfully.

4. Expose the Apache Spark database port 10001 by clicking on the port tab.

5. Click on Forward a port and add the port.The port will be forwarded successfully.

Note: The docker-compose-remote-traefik.yml file has the configurations for the networks. The illustration below shows the pipeline controller for the remote instance.

The configurations for the SPARK database used for visualization of data is displayed as shown

HOW TO DISPLAY DATA ON APACHE HIVE DATABASE MANAGEMENT SYSTEM

In this section the Apache Hive database management system will be set up. The dbms will pull flat data that will be used for visualization. This guide provides steps on installation of the dbms.

1. Upon installation of the database management system click to startup

Note: you might be required to download SQLite driver files

2. Click on New database connection

3. Enter the localhost and the port number as exposed on the remote instance forwarded ports. Click on the finish button.

Upon successful connection click on the default drop-down menu

4. To view data, click on the default menu item then click on  tables. The tables are displayed.

5. Run an incremental within the data pipeline. 

6. To view the flattened tables from patient resources, click on View. In  this illustration patient_flat_2 is clicked. Notice the patient created under the local instance is displayed.

GETTING STARTED: DATA VISUALIZATION