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

How to Start the OpenHIM-IOL

1. Access OpenHIM:

   • Open your browser and go to http://localhost:9000/.

   • Handle the self-signed certificate warning by clicking Advanced > Proceed to localhost.

2. Login to OpenHIM:

   • Use root@openhim.org and OpenHIM as credentials.

3. Configure Central FHIR Server Channel:

   • Navigate to Channels > Central FHIR Server Channel.

   • Review configurations under Basic Info, Request Matching, and Route tabs

How to Start the Data Pipeline

1. Start the Pipeline Controller:

   • Open a new terminal and execute: sudo docker -f docker-compose-pilot.yml up pipeline-controller

   • Access the FHIR Pipelines Control Panel at http://localhost:8090/.

2. Review Streaming Pipeline Configuration:

   • Locate the application.yml file in the local-streaming-pipeline directory.

   • Review the FHIR module and patient resource configurations.

How to Send Data to the Central FHIR Server

Sending New Patient Resources

1. Create a Patient in OpenMRS:

   • Login to OpenMRS and navigate to Find/Create Patient.

   • Fill in the patient details and save.

2. Run Incremental Pipeline:

   • In the pipeline controller, click Run Incremental.

3. Verify Data Transmission:

   • Login to OpenHIM and check the transaction logs for a POST request to the HAPI FHIR server.

4. Check Patient Data on the FHIR Server:

   • Access the FHIR server and filter the patient resource by lastUpdated to verify the new patient data.

Sending Laboratory Encounter Resources

1. Create a Laboratory Order:

   • Copy the patient ID, navigate to Demande d’examen, and create a new order.

2. Run Incremental Pipeline and Verify:

   • Repeat the steps to run the pipeline and check for POST transactions in OpenHIM.

3. Verify Observation Data on FHIR Server:

   • Filter the observation resource on the FHIR server to see the newly created lab encounter.

Getting Started: Remote Setup

SSH Connection and Remote Project Setup

1. Set Up SSH Access:

   • Establish a secure shell (SSH) connection to the OpenMRS instance server.

2. Start the Project Remotely:

   • Navigate to the project directory and start the services using the appropriate Docker compose file.

Displaying Data with Apache Hive

1. Set Up Apache Hive DBMS:

   • Install and configure Apache Hive to visualize data.

   • Connect to the remote instance via SSH and forward the required ports.

2. View Flattened Data:

   • Use the Hive interface to view and query the flattened patient data.