Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.



For the latest OpenMRS-DHIS2 integration work, see



Widget Connector
Widget Connector
Widget Connector

About DHIS Connector Module (DCM)


Before exporting Data to DHIS, DataSets and data elements for the DataSets must be defined. The Manage DataSets page is used to create the DataSets and define the descriptions/elements.


The first step is to configure the link to your DHIS2 server. This is done by clicking the Configure DHIS Server link under the DHIS Connector Module heading on the OpenMRS Administration page. You will need to know the URL of your target DHIS2 instance as well the details of a user that has access to the API. To test with the DHIS2 demo server, use the following details:



Before you can send Period Indicator Report data to DHIS2, a mapping must exist between the report and a DHIS2 Data Set. Mappings can either be generated via the UI or placed in the correct location. Mappings are stored as JSON on the file system at OPENMRS_DIR/dhisconnector/mappings/. On Ubuntu, this usually corresponds to /usr/share/tomcat7/.OpenMRS/dhisconnector/mappings/.

Create Mapping

To generate a mapping via the UI, click the Create Mapping link under the DHIS Connector Module heading on the OpenMRS Administration page. Then select the Period Indicator Report from the left menu and the corresponding DHIS2 Data Set from the right menu. Drag the Data Elements and Category Option Combos from the right to the matching row on the left as follows:

Image Modified

Finally, click save and give your mapping a unique name.

Exporting Existing Mapping

This module provides a way of exporting existing mappings which basically archives them into one download that can thereafter be imported/uploaded into the current or another OpenMRS instance.

Uploading Existing Mapping

The module provides an option to import or upload mappings previously exported from the current or other instances, this feature is available and will be released as part of 0.1.2

Location Mappings

Before you can send Period Indicator Report data to DHIS2, a mapping must exist between the OpenMRS Location and a DHIS2 Organization Unit. So when pushing data, the respective DHIS Organization Unit and OpenMRS Location of the Dataset will be automatically mapped. Location Mappings can be saved via the Location Mapping UI. Mappings are stored in the database at dhisconnector_location_to_orgunit table.

DHIS Connector Module - Location MappingImage Modified

Posting Data

To post data to the DHIS2 server or download the data in DXF format, click the Run Reports link under the DHIS Connector Module heading on the OpenMRS Administration page. Select the Period Indicator Report and the corresponding mapping to use.

Since Period Indicator Reports are always run for a specific location, you will also need to select the OpenMRS Location as well as the corresponding DHIS2 Organisation Unit. But with the automated location mapping feature, it will show the available location mappings when the mapping is selected. You can select the required location-org unit mappings from the available mappings.

The date selector will be changed based on the period type of the DHIS2 Data Set.

Image Modified

Once you have selected a value for all the fields, click Send Data to post data directly to the DHIS2 server, or Download JSON to download the data in DXF format.


To schedule/automate pushing data, click the Automation link under the DHIS Connector Module heading on the OpenMRS Administration page.

To add mappings, choose the mapping from the dropdown list and click Add.

You need to map the relevant OpenMRS Location and DHIS2 Organisation Unit using the Location Mapping UI before scheduling the mappings.

To push data manually, select the mappings and click Run Selected. Available OpenMRS locations and DHIS2 organization units will be mapped automatically. Automated reports will be ran and pushed automatically by the end of the relevant period.

You can toggle the automation by checking/unchecking the tick box and clicking save.

Image Modified

User Access Controlling

The DHIS Connector module comes with these user privileges.

  1. View Connection - Viewing DHIS2 Connection
  2. Manage Connection - Edit DHIS2 Connection
  3. View Location Mappings - View location-orgunit mappings
  4. Manage Location Mappings - Edit/Delete location-orgunit mappings
  5. View Automation - View scheduled mappings
  6. Run Automation - Run scheduled mappings
  7. Manage Automation - Add/Edit/Delete scheduled mappings
  8. Run Reports - Base privilege for running the reports
  9. Run Failed data - Base privilege for pushing the failed data
  10. Manage Mappings - Create/Edit Mappings
  11. Import and Export - Import and export mappings and DHIS2 API

Users are required to have the necessary user privileges in order to use the functionalities of the module. The admins can create and assign roles with the combinations of privileges. If the required privilege is missing, the user will be redirected to the Home page.

In addition, users should have privileges related to the used period indicator reports when pushing data. Also, users must have Manage Global Properties to toggle automation and to update the DHIS2 Connection. More Info...

Image Modified

Manage Data Sets

The user must define the elements for each data set and select a saved cohort from the ones saved that satisfies the description/element. The definitions must then be saved, which will make that DataSet ready for exporting to DHIS.