OpenMRStoDHIS2Mediator Developer guide

Introduction

OpenHIM mediators are separate micro services that run independently from the OpenHIM-core and perform additional mediation tasks for a particular use case. The objective of this mediator is to send data from the OpenMRS CBS form to the capture form of DHIS2 tracker.

This guide provides instructions on how to deploy, configure and use this mediator.

Prerequisites

• Git: is the distributed version control system used in this project. More informations about Git
• OpenHIM: As the mediators communicate with the OpenHIM-core, some knowledge about this interoperability layer software are required. The following documentation will help you.
• Node.js: The mediator has been built using Node. NodeJS org documentation
• Data matching dictionary: For the matching between the concepts of OpenMRS and the data elements of DHIS2. The Excel file used for that.
• DHIS2 TRACKER API: To be able to send data to DHIS2, DHIS2 offers some endpoints. This link will be helpful: DHIS2 web API for tracked entity instance
• Docker: The official docs about docker

Dependencies

This mediator uses JSON files coming OpenMRS (postToOpenHIM module), OpenHIM-Core and DHIS2.

• The postToOpenHIM module of OpenMRS: To send a request with a JSON file containing a CBS form details to OpenHIM-Core.
• OpenHIM-Core: To redirect the request to the current mediator.
• DHIS2 Tracker: To receive the data from the medaitor after data matching processes.

Project structure

• server folder: This is the main folder of the project.
  • config folder: This folder contains the configurations files.
    • config.json file: Contains all the values and informations to allow the commucation between the mediator, DHIS2 and OpenHIM-Core.
    • mediator.json file: Contains all the values and informations to allow the mediator to register in the OpenHIM-Core.
  • lib folder: This folder contains the mediator source code.
    • formMapping.js file: Contains data matching tables, some functions for tracked entity and enrollement creation and main data pushing function.
    • index.js file: The server starting point, and where the JSON payload file is structured before sending to DHIS2.
    • utils.js file: As a project library, it contains all the functions used in the project, for data matching, data conversion.
• .dockerignore file: This file is a docker image building file, to ignore files or folders.
• dockerfile file: This file is a docker image building file.
• README.md file: This file contains the instruction to follow to build the mediator docker image.

Getting started

To get started please, check the README file

Installation

The deployment documentation about this mediator can be found in the Installation guide.

Configuration

The config.json

• OpenHIM-Core info: In the api.username, api.password, api.apiURL set respectively the username, the password and the URL of your OpenHIM-Core.
• DHIS2 info: In the api.dhis2, set respectively the URL, the username and the passowrd for DHIS2 access. This account must be created in DHIS2 before.

The mediator.json

How to modify the data sending from OpenMRS to DHIS2?

Here you will find how someone could adapt the mediator to push other data from OpenMRS to DHIS2.

Security

The mediator is running inside a Docker container. It is accessible only to containers based on the same docker network. In our case, only OpenHim Core container can access this container through secure HTTPS method requests.

Document version

Last update: 05/06/2020 Version: 1.0