OPENMRS CONNECTION TO HAPI FHIR SERVER

 IMPLEMENTERS GUIDE

Draft

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

Table of contents

INTRODUCTION 2

INTENDED AUDIENCE 3

GETTING STARTED: LOCAL SETUP 3

HOW TO SET UP THE PROJECT LOCALLY 3

HOW TO STARTUP THE SIGDEP3 EMR LOCALLY 9

HOW TO STARTUP THE OPENHIM-IOL 16

HOW TO STARTUP THE DATA PIPELINE 24

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

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

GETTING STARTED: REMOTE SETUP 42

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.

Create a directory

2. Open the visual studio code in the project directory

Open VS Code

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

Navigate to Github

4. Copy the project url to clipboard

Copy url

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

Clone project

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

Change directory into cloned project folder

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

docker-docker-local-pilo.yml file

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

• The Sigdep3 service displays the configuration for the OpenMRS

Sigdep3 service

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

Sigdep3-db

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

OpenHIM IOL service

• The pipeline-controller is configured for FHIR analytics.

Pipeline controller

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

Project startup

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.

SIGDEP3 OpenMRS Instance startup

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

README file

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

README file commands

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. 

Initial setup

SIGDEP-3 login page

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

Login  to instance

6. Upon successful login click on Administration

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.

Click Search Index

8. Click on the Rebuild Search Index button.

Rebuild search index

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

Server-side search index rebuild

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

Search index rebuild completed

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

Concept search

HOW TO STARTUP THE OPENHIM-IOL

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

Project startup

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.

Login page

3. Click on the link text field.

Click on link

4. Click on the Advanced button.

Click advanced

5. Click on proceed to localhost (unsafe)

Click proceed to localhost

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

OpenHIM Console Heartbeat

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

OpenHIM console login page

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

Transactions log

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

Channels

9. Click on the central FHIR server channel. 

Click on central fhir server

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.

Channel basic information tab

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

Request matching

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

Routes tab

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.

Central FHIR Server configurations

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

local-test-openhim-config.json file 

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 

Startup pipeline controller

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

FHIR Pipelines Control Panel 

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

Local streaming pipeline application.yaml file

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.

Login  to instance

2. Click on the Find/Create Patient menu item

Click find/create patient

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

Create person

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

Create a new patient

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

1. username: root@openhim.org 

2. password: openhim 

and click on the Login button

OpenHIM console login page

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

Transaction log

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

Login page

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

Remote OpenHIM console transaction log

Note: At this juncture, the pipeline is executed 

Pipeline started

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

Accessing fhir consolidated server

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

Patient resource

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

Patient resource

Patient resources

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.

Copy patient Identifier

Login  to instance

2. Click on the Demande d’examen menu item

Click on demande d’examen

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

Enter identifier and click view patient

4. Select the date and click on new order button

Enter date and click on new order

5. Fill in the form to completion.

Fill form

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

Click save

Order saved successfully

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

3. username: root@openhim.org 

4. password: openhim 

and click on the Login button

OpenHIM console login page

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

Transaction log

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

Login page

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

Remote OpenHIM console transaction log

Note: At this juncture, the pipeline is executed 

Pipeline started

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

Accessing fhir consolidated server

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

Observation resource

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

Observation resource

Observation resource

Observation resource

GETTING STARTED: REMOTE SETUP