...
| Table of Contents | ||
|---|---|---|
|
...
OpenMRS Connection to HAPI FHIR Server: Implementers Guide
Introduction
Welcome to the OpenMRS Connection to HAPI FHIR Server Implementer's Implementers Guide. This guide provides a step-by-step approach for implementers to establish a connection between OpenMRS and will help you integrate your OpenMRS 2.x or OpenMRS 3.x deployment with 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.
...
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 responsible for implementing and managing an OpenMRS Health Information Exchange implementation. It assumes a basic understanding of 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. 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
...
Create a Project Directory:
Create a directory for the project on your local machine.
Navigate to the created directory.
Clone the Repository:
...
.
...
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)
...
.
Create Directory:
mkdir OpenMRS-FHIR-Integration cd OpenMRS-FHIR-IntegrationClone 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.gitChange into the project directory:
/cd SIGDEP-3-Docker-SetupReview Docker Configuration:
Open the
docker-docker-local-pilot.ymlfile 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.
Start the Project:
Run the following command to start the services:
sudo dockerStep 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
...
Login with admin and Admin123.
...
After logging in (default: admin | Admin123), navigate to Administration > Maintenance > Search Index
...
and click Rebuild Search Index
...
How to Start the OpenHIM-IOL
Access OpenHIM:
...
. 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
...
Navigate to
Channels > Central FHIR Server Channel.Review configurations under
Basic Info,Request Matching, andRoutetabs
...
, 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
...
.
...
Review Streaming Pipeline Configuration:
Locate the
application.ymlfile in thelocal-streaming-pipelinedirectory.Review the FHIR module and patient resource configurations.
...
Step 2: Sending Patient Resources to the Central FHIR Server
...
Create a Patient in OpenMRS:
Login toUse OpenMRS
and navigate toFind/Create Patient.Fill in the patient details and saveto create a new patient.
Run Incremental Pipeline:
InOn the pipeline controller dashboard, click Run Incremental to send the patient data to the FHIR server.
Verify Data Transmission:
Login to OpenHIM and check the transaction logs for a POST request to the HAPI FHIR server.
Check Patient Data on the FHIR Server:
Access the FHIR server and filter the patient resource bylastUpdatedto verify the new patient dataCheck 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
Create a Laboratory Order:
Copy the patient ID, navigate toDemande d’examen, and create a new orderin OpenMRS for a patient.
Run Incremental Pipeline and Verify:
RepeatTrigger the
stepspipeline to
run the pipeline and check for POST transactions in OpenHIM.Verify Observation Data on FHIR Server:
Filter the observation resource on the FHIR serversend the observation resource via OpenHIM to the FHIR server.
View Resources: Log in to the HAPI FHIR server and filter the resources by Observation to see the newly created lab
encounterresult.
...
Remote Setup for OpenMRS Deployment
Step 1: SSH Connection
...
Set
...
up a secure shell
...
connection to the
...
Start the Project Remotely:
Navigate to the project directory and start the services using the appropriate Docker compose file.
Displaying Data with Apache Hive
...
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.
View Flattened Data:
...
remote server where OpenMRS is hosted. Ensure the correct SSH keys are configured.
Open a Remote Terminal in Visual Studio Code and connect to the remote host.
Run Docker Compose:
Code Block 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
Install the Microsoft Spark ODBC Driver and configure it with the required port and host settings.
Open PowerBI, navigate to Get Data > ODBC, and connect to the flat tables in Apache Hive.
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.