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

OpenMRS Connection to HAPI FHIR Server: Implementers Guide

Introduction

Welcome to the OpenMRS Connection to HAPI FHIR Server Implementers Guide. This guide will help you integrate your OpenMRS 2.x or OpenMRS 3.x deployment with a HAPI FHIR server. It includes setup instructions for local environments, such as configuring necessary files and managing the Docker containers involved. These foundational steps are essential for ensuring a successful implementation of OpenMRS with HAPI FHIR.

Intended Audience

This guide is intended for implementers managing OpenMRS deployments, either as new setups or as part of ongoing integrations, particularly those focused on Health Information Exchanges (HIE) using the FHIR standard. It assumes that readers have some familiarity with Docker, Git, and web-based application management.

Local Setup for OpenMRS 2.x and 3.x

Step 1: Set Up the Project Locally

To begin, create a directory for your project on your local machine and open it in Visual Studio Code (VS Code).

1. Create Directory:

   mkdir OpenMRS-FHIR-Integration cd OpenMRS-FHIR-Integration

2. Clone Repository: Clone the project repository that contains the Docker setup for the OpenMRS-FHIR integration.

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

Step 2: Configuration Overview

The docker-compose file defines services needed for the OpenMRS-FHIR integration, including:

• OpenMRS EMR (SIGDEP3) and its database

• OpenHIM (for interoperability), with MongoDB and OpenHIM Console

• FHIR Analytics Pipeline Controller for processing FHIR data

Review the configuration in the docker-compose-local-pilot.yml file.

Step 3: Start Services

Start the services with Docker Compose:

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

This will start the necessary containers, including OpenMRS and OpenHIM.

Setting Up OpenMRS

Step 1: Start OpenMRS Instance Locally

Start the OpenMRS container separately by running:

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

Step 2: Access OpenMRS

Access OpenMRS by visiting http://localhost:8080/openmrs in your browser. If this is your first time, the system may take a few minutes to initialize the database.

Step 3: Rebuild Search Index

After logging in (default: admin | Admin123), navigate to Administration > Maintenance > Search Index and click Rebuild Search Index. This is necessary for patient and concept searches to function properly.

Setting Up OpenHIM

Step 1: Access OpenHIM Console

Open OpenHIM by navigating to http://localhost:9000 in your browser. Since this is a new setup, you might see a self-signed certificate warning. Click "Proceed to localhost (unsafe)" to continue.

Step 2: Log in to OpenHIM

Use the following credentials to log in:

• Username: root@openhim.org

• Password: OpenHIM

Once logged in, you can view Channels, including the Central FHIR Server Channel, which routes OpenMRS patient resources to the FHIR server.

Starting the FHIR Data Pipeline

Step 1: Start the Data Pipeline

Start the pipeline controller using Docker:

sudo docker-compose -f docker-compose-pilot.yml up pipeline-controller

The pipeline controller dashboard will be available at http://localhost:8090.

Step 2: Sending Patient Resources to the Central FHIR Server

1. Create a Patient: Use OpenMRS to create a new patient.

2. Run Incremental Pipeline: On the pipeline controller dashboard, click Run Incremental to send the patient data to the FHIR server.

3. Check Transaction Logs: Log in to OpenHIM to confirm the transaction has successfully routed the patient resource to the FHIR server.

Step 3: View Resources on HAPI FHIR Server

Log in to your HAPI FHIR server (e.g., https://test1.cihis.org/fhir) and search for patient resources. You should see the newly created patient.

Sending Laboratory Encounter Resources to the Central FHIR Server

1. Create a Laboratory Order in OpenMRS for a patient.

2. Run Incremental Pipeline: Trigger the pipeline to send the observation resource via OpenHIM to the FHIR server.

3. View Resources: Log in to the HAPI FHIR server and filter the resources by Observation to see the newly created lab result.

Remote Setup for OpenMRS Deployment

Step 1: SSH Connection

Set up a secure shell connection to the remote server where OpenMRS is hosted. Ensure the correct SSH keys are configured.

1. Open a Remote Terminal in Visual Studio Code and connect to the remote host.

2. Run Docker Compose:

   docker-compose -f docker-compose-remote-traefik.yml up

Step 2: Viewing Data with Apache Hive

Once the remote instance is running, use Apache Hive to access and visualize flattened FHIR data. Set up Hive on your local machine and establish a connection using the port exposed by the remote instance.

Data Visualization with PowerBI

1. Install the Microsoft Spark ODBC Driver and configure it with the required port and host settings.

2. Open PowerBI, navigate to Get Data > ODBC, and connect to the flat tables in Apache Hive.

3. Load and visualize the flattened FHIR data, including patient and observation resources.

This general guide supports both OpenMRS 2.x and 3.x deployments and provides a comprehensive overview of setting up a local or remote environment, integrating with a HAPI FHIR server, and utilizing OpenHIM for interoperability.