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

OPENMRS CONNECTION TO HAPI FHIR SERVER

 IMPLEMENTERS GUIDE

Draft

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

INTRODUCTION

Welcome to the OpenMRS Connection to HAPI FHIR Server Implementers Guide. This guide is designed to assist you in setting up the project within your environment, providing detailed instructions and resources to ensure a smooth and efficient implementation process. It includes the steps required to set up the project locally, such as creating a project directory, cloning the repository, configuring necessary files, and starting the project using Docker. These foundational steps are crucial for ensuring that your implementation is set up correctly from the beginning.

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. 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

3.

Observation resource

Observation resource

Observation resource

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.

Accessing SSH key 

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.

Click on the connection

3. Click on Connect to Host

Click connect host

4. Click on the instance to connect. 

Click on instance

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

Click on terminal

HOW TO STARTUP THE SIGDEP3 EMR REMOTELY

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

Run docker ps

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

Apache Spark dbms forwarding port

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

Change directory

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

Startup project

The project will be started successfully.

Project started successfully

4. Expose the apache spark db port 10001 by clicking on the port tab

Expose the apache dbms port 

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

Click on add port

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.

Services: pipeline controller

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

Services: Spark

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 dbms click to startup

Startup DBeaver

Note: you might be required to download SQLite driver files

2. Click on New database connection

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.

Enter host, port and click finish

Upon successful connection click on the default drop-down menu

Connection  successful

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

Click on tables under defaults

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.

View flattened data: patient resource