Technical Report for The Integration Of openhim with Mifos through openhim Python Mediators


The openIMIS Payment Layer Integration solution implements client/server architecture. The openIMIS upstream server exchanges data through FHIR R4 APIs such as patient (insuree), claim, billing, invoice, organization with client system such as Mifos through openHIM orchestration mediators. Figure 1 illustrates the overall payment layer architecture based on the workflow provided by the openIMIS development community.

Figure 1: Payment Layer Integration Architecture


The orchestration mediators connect to Mifos using FHIR R4 API endpoints that are transformed into Mifos canonical JSON schema for compatibility and interoperability as shown in Figure 2.

Figure 2: Payment layer orchestration mediators’ workflow

Payment information from Mifos or MojaLoop is sent or received from openIMIS through orchestration mediators developed in Python. The mediators receive payloads from the source system and transform the received schema using define business rules. The staging area is an SQLite database that is populated with transaction logs and metadata data used to define business logic and data validation rules. The payment layer mediators are deployed using openHIM interoperability layer that comprises three components: Core, Mediators, and administration console shown in Figure 3.

Figure 3: openHIM interoperability architecture
  • The OpenHIM core main functionality is to process requests and log transactions from client systems. By default, openHIM core listens on ports 5000 (HTTPS) and 5001 (HTTP) and port 8080 (API). These ports are therefore the front door through which external systems use to communicate with the OpenHIM. The openHIM console makes use of this API to manage and view the OpenHIM data while mediators use the API to register themselves and monitor heartbeats.

  • The openHIM console is a web-based interface used by administrators to register and clients, channels, mediators, users, permissions, and transaction logs.

  • Mediators are loosely coupled middleware used to enhance functionality and business logic of the core. A mediator MUST register itself with the core using a unique name, host domain or IP address, default channel, and API endpoints.


Docker is a popular containerization platform that solves the libraries and dependency issue regardless of the platform used to deploy the mediators written in Django. To package the mediators for deployment, we have provided Dockerfile and docker-compose.yml. To deploy and run the mediators, you need to perform the following steps:

  1. Build the image: This is done using docker-compose build command. The command uses the Dockerfile to build openHIM core, console, and mediators images. The -t flag tags the image so that it can be referenced when you want to run the container.

  2. Create containers: Spinning containers from the three images is done using the docker-compose up command. This will convert the images into running containers as shown in Figure 4.

  3. Figure 4: Running docker containers

3. Create super (root) user: Before loading the app, you must create a user with elevated privileges to access the web-based admin console. Use this command:

  • docker-compose run <containername/id> python createsuperuser


  • docker-compose run paymentmediators python createsuperuser

 4. Load the mediators app. For example, if deployed on localhost, use: http:localhost:9002/admin/

5. Log in to the mediators’ admin using the superuser credentials created in step 3 above.


Configuration Management is the discipline that applies a rigorous approach to ensure completion and proper integration of all the various modules in software systems. for The openIMIS payment layer integration platform simplifies configuration management by providing users with three web-based admin (See Annex 1, 2, 3 and 4 for sample admin interfaces). To load the configuration page, proceed as follows:

  1. Load the login page and supply your credentials created earlier. The admin interface shown in Figure 5 is displayed

Figure 6: Mediators configuration management interface

2. Click Add configuration button under

mainconfigs module. The form shown in Figure 6 is displayed. Enter new or update variables for the openHIM, Mifos and mediator subsystems.

Figure 6: Configuration settings form


Distributed version control systems are software tools that helps developers keep track of changes made or modifications done to the source code. We followed best practices to keep track of changes applied on openIMIS source code. To access the source code hosted on GitHub, search for openhim-openimis-payment-orchestration-mediators. You can then clone or fork the source code using the green button shown in Figure 7.

Figure 7: GitHub repo for source code and version control


To make the openIMIS payment layer fully functional, there are some outstanding tasks most of which require continuous development and integration using FHIR R4 billing and invoice resources. This requires Mifos to expose API endpoints for sharing payment information with openIMIS through the orchestration mediators developed in Python using the Django web framework. Furthermore, there is a need for more semantic interoperability testing of the integration workflow on a different production, and development platforms.


Annex 1: The following admin interface provides access to openIMIS admin for a user, permissions, and configurations management:

Figure A1: openIMIS admin console

Annex 2: The following admin interface provides access to mediator connection variables and configurations management:

Figure A2: Mediator admin console

Annex 3: The following admin console provides access to openHIM transactions and configurations management:

Figure A3: openHIM admin console

Annex 4: The following admin interface provides access to Mifos transactions and configurations management

Figure A4: Mifos admin console

Mifos-openIMIS fields mapping document