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

You will find here how to set the mediator configuration file.

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. We have two (2) types of data: a simple concept field value and a dropdwon concept value. For each type we need to add the reference in the index.js file, in the rigth payload (according to the CBS form to send from OpenMRS to DHIS2).

Add or Modify a simple concept field to send to DHIS2:

• Find in the formMapping.js file, the data matching object for this concept (each CBS form has its matching table object).
• Add the uuid of this concept (OpenMRS side) and the Id of the corresponding data element (DHIS2 side).
  • E.g: { "fe5fdddf-96ee-42af-9b36-0ab8c3ddd05d": "KX4MrpcRuAb" }
• In the index.js file, find the main object for the concerning DHIS2 data element (for each CBS form we have one (1) or more DHIS2 program stages as data destination).
• Add the Id of the data element following this example in the JSON payload object:
  • E.g: {"dataElement":"KX4MrpcRuAb", "value": ""}.

Add or Modify a dropdown concept field to send to DHIS2:

• Make the matching between the dropdown items of OpenMRS(using the uuid) and the dropdown items of DHIS2 (using the Id).
• Create a getDHIS2NameOfTheFieldValue function in the util.js file (by using the existing examples) to return the corresponding data element Id, according to the concept item selected in OpenMRS.
• In the index.js file, find the main object for the concerning DHIS2 data element.
• Create the variable which will receive the item value as:
  • E.g: var patientNameOfTheFieldValue = "";
• Use the existing example to retrieve the value of the selected item into patientNameOfTheFieldValue using the new function created and the UUID of the concept question field.
• • Add the Id and the value of the variable patientNameOfTheFieldValue following this example, in the JSON payload object:
  • E.g: {"dataElement": "KX4MrpcRuAb", "value": patientNameOfTheFieldValue}.

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: 25/06/2020 Version: 1.0