DHIS2Xfer Tool – Transfer data between two DHIS2 instances


DHIS2Xfer Logo

For those of you who work with DHIS2, you know that moving data between two instances can be challenging. This situation came up while working with our client DAI, in Haiti. The Haiti Ministry of Health has two DHIS2 instances:

  1. A Tracker instance that collects patient level health data
  2. A national aggregate instance for reporting a wide variety of health indicators for the country

Users with access to both DHIS2 instances have two separate logins to visualize the data in the different systems, which is cumbersome. Project Balance was tasked to find a way to move the aggregate indicators from the Tracker instance to the national DHIS2 aggregate instance for reporting purposes.

Project Balance developed what we call the “DHIS2Xfer tool”. This tool addresses the specific requirement of transferring data (data elements + category option combo, indicators, program indicators) from one DHIS2 instance to a data element + category option combo of a DHIS2 aggregate instance. The DHIS2Xfer tool started out as an Excel VBA application and was replaced with a secure cross platform .NET core web application. The application is easy to use and greatly simplifies the process of identifying and mapping data source data objects to data destination objects in pairs of DHIS2 instances including the associated organization units.

The tool consists of two components:

  1. A web application with UI that can be run from a server or administrator’s workstation to map objects between two DHIS2 instances (organization units, data elements, indicators and program indicators) and create transfer jobs that can be either run manually on demand or on a schedule using a command line or shell application on a server.
  2. The command line or shell application that can be installed on a server to schedule automated execution of transfer jobs created using the web application.

Server credentials are encrypted in the configuration files and can be securely stored on any server for use with the command line / shell application. The application is cross platform and can be run from Windows or Linux (.NET core).

This tool is free and open source. If you would like to download and use the tool, please provide your name and email so that we may offer assistance such as training and documentation.

If you prefer not to provide your email, click here to download the tool. If you have questions, please feel free to reach out to Project Balance’s technical director, Ed Robinson.

The screenshots below highlight the main features of the system.

DHIS2Xfer Dashboard Screenshot

Fig 1: DHIS2Xfer – dashboard. This is the page that greets you after logging into the DHIS2Xfer mapping tool. From here you can see how many servers have been configured, how many pairs of organization units have been mapped, how many jobs have been created, and how many Xfer files have been generated. Xfer files are configuration files containing one or more jobs that can be scheduled to run on your server at a schedule determined by yourself (Windows task scheduler or Cron can be used).

DHIS2Xfer Manage Servers Screenshot

Fig 2: DHIS2Xfer – manage servers. You add URL and login credentials for your various DHIS2 servers here. The Sync button is used to pull the latest metadata from the server and make it available offline for mapping.

DHIS2Xfer Organization Unit Mapping Screenshot

Fig 3: DHIS2Xfer – organization unit mapping. This feature is used to map organization units between two DHIS2 instances to allow the system to transfer data from one instance to another against the correct organization unit. Org unit mappings are stored in server instance pairs.

DHIS2Xfer Organization Unit Mapping Screenshot

Fig 4: DHIS2Xfer – data object mapping (Xfer jobs). This feature lets you create mapping job, which are collections of source and destination mapped data items (source is data element and category option combo / indicator / program indicator, destination is data element and category option combo) to allow data to flow from the source to the destination when the job is run.

DHIS2Xfer Creating an Xfer Routine Screenshot

Fig 5: DHIS2Xfer – creating an Xfer routine (one or more jobs). This feature allows you to combine one or more jobs into an Xfer routine to be run on demand from within the graphical interface or on schedule from a server using the shell / command line application.

DHIS2Xfer Edit, Export, or Run a Transfer Routine Screenshot

Fig 6: DHIS2Xfer – edit, export or run a transfer routine. This feature allows you to run an existing Xfer job on demand or download the configuration file to be run from your server by the command line / shell console application.