Instant OpenHIE Setup


Open Health Information Exchange (OpenHIE) is a community of practice that builds interoperable data standards so that HIS can talk to one another, enabling individuals across the health system to access the information that they need. Instant OpenHIE activities will provide portable, launchable versions of multiple OpenHIE components to facilitate:

  1. Demonstrable reference products - those that align with the OpenHIE Community's vision for low resource contexts Rapid software development of mediators and point-of-service systems by making it possible to launch several applications easily so the developer can focus on their task

  2. Reproducible, version-controlled infrastructure for user-contributed tests of the OpenHIE Architecture profiles, workflows, and use cases.

  3. Production-ready containers and orchestratable components that are deployable in any context.

  4. Extensibility so that anyone may create Instant OpenHIE packages and plug them into the existing Instant OpenHIE functionality.

Core Services

The Instant OpenHIE Core Package is the common base of the Instant OpenHIE system and it provides fundamental components that other packages may build off of. This package consists of two components that support all other packages, these are:

  • An Interoperability Layer

  • OpenHIM

  • A FHIR Server - HAPI FHIR

Health Management Information System (HMIS) Package

This package has two parts to it:

  • District Health Information System 2 (DHIS2)

  • PostgreSQL - the database for DHIS2

Health-Worker-Registry & Health-Workforce manager

  • iHRIS

The Client Registry Package is a key component of Instant OpenHIE.

Our reference technology is the Open Client Registry (OpenCR) service which has two dependencies: -HAPI FHIR (this is the Core package FHIR Server instance)

  • FHIR Extractor

  • Open Client Registry (OpenCR)

Elastic Packages

The elastic-* package family are infrastructure packages that provide components for the elastic stack for data analytics and other useful tools. There are two packages


  • fhir-extractor

     - a simple node.js service that queries the _history endpoint of HAPI FHIR and forwards the bundle to Logstash.

  • logstash - processes the FHIR bundle and breaks it does into individual resources and stores the raw resources in elasticsearch. It can also be configured to pre-process, join, flatten and enrich resources using it's json manipulation DSL. This makes reports easier to run where the raw FHIR resources are highly nested and relational thus difficult to report on.


  • elastic-search - acts as the data mart. All reporting data should go into it in a format favourable for reporting. aggregation queries to elasticsearch can be made to draw up reports.

  • kibana - a visualisation, data discovery and dashboard tool that is part of the elastic stack

  • jsReport - a tool separate from the elastic stack which is useful for creating pixel perfect reports that are exportable to PDF and excel using HTML and CSS. It can be scripted to query elasticsearch as it's data source.


The Open Health Information Mediator (OpenHIM) is a middleware component designed to ease interoperability between disparate information systems. It provides secure communications and data governance as well as support for routing, orchestrating and translating requests as they flow between systems.

Official Docs

Deployable Components

  1. OpenHIM Core The OpenHIM core component is responsible for providing a single entry-point into an HIE.

    Docker Image


    • Mongo DB, OpenHIM core uses Mongo DB as its primary database.


    1. Docker Container Environment Variables.

      • mongo_url, MongoDB Url e.g mongodb://username@password//

      • mongo_atnaUrl, MongoDb Url e.g mongodb://username@password//

      • NODE_ENV, Node Environment used e.g production, development

    2. Default.json

      • Holds the config for the application server. e.g port, bind_address e.t.c

OpenHIM Certificate Issue

Note: It has an inbuilt certificate that should be updated with one by trusted by CA that can be done by uploading it on the OpenHIM console. OpenHIM Core also should be publicly available. To avoid regularly updating/buying the certificate and using LetsEncrypt instead do this:

If one is using a docker image one can use HTTP internally (check the default.json above to do this) and proxy HTTPS requests to it using preferred web server. For a kubernetes setup you can achieve the same by two ways: First, one can use ingress normally or Second use LoadBalancer service type and assign a domain to that external ip.,for both update https to http (check the default.json  to do this). HTTPS requests will also be proxied to HTTP port. For router ports i.e 5001, 5000 one can also do the same on the HTTP port. Remember to update the default.json (check below on OpenHIM console configurations) file on the OpenHIM console with the domain, port and protocol(HTTPS) used for OpenHIM core.

  1. OpenHIM Console

    The OpenHIM console component provides a web application to configure and manage the OpenHIM-core component.

    Docker Image


    • An existing OpenHIM Core.


    1. Default.json

      • Holds some configurations for the UI and host, port configurations to OpenHIM core.

    NOTE: To automatically import OpenHIM config one can utilize the Mapper Importer Job here by installing the chart and updating the following values deployMcsdMockService and mcsdEndpointImporterJob.enabled to false and this mapperConfigImporterJob.enabled to true then ensure mapperConfigImporterJob.OpenHIMImportJson has the correct data that should be imported. Finally update the OpenHIMCoreConfiguration with your configurations in values.yaml.

  2. OpenHIM Mediator Mapping

    The Mapping Mediator's function is to allow data validation, mapping, and orchestration between disparate systems.

    Docker Image


    • An existing OpenHIM Core

    • MongoDB


    1. Docker Container Environment Variables.

    • OpenHIM_URL OpenHIM core url





HAPI FHIR is a complete implementation of the HL7 FHIR standard for healthcare interoperability in Java.

It interacts with the following applications:

  • FHIR Extractor

    • Extracts data from fhir server and pushes them to logstash for analysis or visualization later on.

  • iHRIS

    • Uses FHIR resources for its configurations and record keeping.

  • OpenCR

    • Can be used together with fhir to share info about a patient or any other health data.

  • OpenHIM

    • Can be used to authenticate requests to the fhir server i.e it can act as an authorization middleware, by use of OpenHIM channels.

    • Can be used by OpenHIM mediators to link separate systems.

Docker Image


  • Database: Can by mysql, postgres, H2 or other Relational Databases supported by hibernate.


  1. Docker Container Environment Variables.


  2. application.yaml

    • Holds the config for the application server. e.g port, bind_address e.t.c


Applications that helps track and manage their health workforce data to improve access to services. Uses fhir resources for its configurations and other health related data.

Official Guide

Docker Image


  • FHIR Server, It initially uploads its definitions and configs to it for later query.

  • Redis for caching.

  • Elastic Search used for search.

  • Kibana, visualizes elastic search data


  1. Docker Container Environment Variables.





Unfortunately at the moment of writing the following images ihris/upload-definitions (responsible for uploading definitions) and ihris/ihris-config (responsible for uploading configs) require a bit of tweaking. The following was done to have them working:

FHIR Extractor

Extracts data from fhir server and pushes them to logstash for analysis or visualization later on.


  • FHIR Server

  • OpenHIM, Polling channel can poll the Fhir Extractor periodically to send data to logstash.

  • Logstash


  1. Docker Container Environment Variables.

    • GET_URL fhir server url

    • POST_URL logstash server url


Open Client Registry (OpenCR) is an open source and standards-based client registry. A client registry facilitates the exchange of patient information between disparate systems. A client registry holds patient identifiers and may include patient demographic information.

Docker Image


  • FHIR Server

  • OpenHIM Mediators

  • Elastic Search


  1. Docker Container Environment Variables.


Helm Chart for these services can be found here.

  1. What services are crucial to have for an initial openhie setup?

    Depending on project requirements one might end up with these three at the very least.

    1. OpenHIM Console (requires OpenHIM core)

    2. OpenHIM Core (requires mongodb), channels to communicate or route requests to other services can be setup see example used here under Channels.

    3. Hapi Fhir Server (requires a relational DB)

  2. How can you handle OpenHIM console login issue?

    OpenHIM core has an inbuilt certificate that is used to encrypt communication between different services. One has to update the certificate with a trusted one and make OpenHIM core publicly available to avoid login issue (mentioned here under NOTE:) on OpenHIM console. This becomes inconvenient if you don't have one (trusted Certificate), or your certificate is only valid for a relatively limited period e.g LetsEncrypt certs. A workaround for this is mentioned here.