23.01. DHIS2 integration

DHIS2 is an open source data warehouse that can be used to store, aggregate and display health data. mSupply can push data periodically to a DHIS2 instance. Before this can happen, the data to be sent and any calculations that need to be made will need to be configured, as shown below.

DHIS2 stores data values that have 3 dimensions:

With these DHIS2 has the power to show different types of data for different places of interest on various graphs. It can also aggregate those values in hierarchical groups.

1. Stock on hand
2. Stock expiring
3. Value of stock on hand
4. Average monthly consumption
5. Days out of stock
6. Issued quantity
7. Received quantity
8. Stock beginning of the month
9. Stock end of the month

To send item details to DHIS2, mSupply has to know the identity of each of its items in DHIS2. There are two options for doing this:

1. Use the item's universal code. See the 4.01.01 Items - General tab section for details on setting this.
2. Use the DHIS2 UID or the DHIS2 code. Choose which one you want to use then enter those values in an item's custom field 1, 2, 3 or 6 (the 3 text custom fields).

The final step in setting up items is to tell mSupply which ones to send data to DHIS2 for. Do this by checking the Include in DHIS2 data push checkbox on an item's details window - see the 4.01.01 Items - General tab section for details on setting this.

Stores in mSupply correspond to org units in DHIS2. mSupply needs to know the Org unit reference for each of the stores that data needs to be sent to DHIS2 for.

To do this, add a Dhis2_code store custom field containing the Org unit reference to each store you want send data to DHIS2 for. For all stores you don't want to send data to DHIS2 for, simply leave the Dhis2_code custom field empty.

For details on how to set store custom codes see the 26.07. Virtual stores section.

Before you can send mSupply data to a DHIS2 instance, you need to tell mSupply where the data has to go, what data to send and where the information comes from. To do that, go to File > Preferences and click on the DHIS2 tab to get to this window:

• Use DHIS2 checkbox: If checked then the DHIS2 interface is turned on and data is sent to DHIS2. If it is unchecked then the interface is turned off and no data is sent to DHIS2. Turning it off also disables data entry in the other fields on this page.
• Basic authentication checkbox: If checked then mSupply will use basic authentication in the call headers when sending data to DHIS2. If it is unchecked then mSupply will use authentication in the body of the calls. This setting should match the way the DHIS2 instance has been configured.
• URL: The URL of the DHIS2 database including the port if any.
• Username: The username mSupply will use to access the DHIS2 database
• Password: The password mSupply will use to access the DHI2 database
• Client: The client name mSupply must use to access the database.
• Secret: The secret that is used for mSupply to access the DHIS2 database. No need to enter this if none was provided.
• Setup
  • Using category option combo:
  • Different data elements per item:
  • Push only 1 data element:
• Data elements to push In this table, select the data elements that you want to push for each mSupply item.
  • Active column: Check the checkbox for each data element you want to send for an item. Click on the checkbox to toggle it on and off.
  • Category option ID column: Enter the ID of the item category 2 option that represents this piece of data in mSupply. Click into the appropriate cell and type or paste the value into the cell.
  • Custom field name column: This is read only and filled in by mSupply.
  • Interval column: Select the interval between successive sends of the data element. Select one of monthly, weekly, daily, first day of the month and last day of the month by clicking on the down arro in the cell and selecting the appropriate option.
  • Push data basis column: Select the basis of the data to be sent, one of previous month or current day. Again, click on the dowen arro in the cell and click on the appropriate option to select it.
• Data set ID: Enter the ID of the dataset in DHIS2 that you want to push the data to.
• Period format: Enter the format to send the period information to DHIS2. Something like “YYYYMM”, where YYYY represents the year, MM represents the month and DD represents the day.
• Item field reference: This tells mSupply where the DHIS2 item reference is stored in mSupply. If Universal code is selected then the code shown in the Universal code field of an item's details page is used (see the 4.01.01. Items - General tab page for details). If Custom field is selected then the DHIS2 item reference is taken from the item custom field entered in the accompanying text field (which should contain one of “user_field_1”, “user_field_2”, “user_field_3” and “user_field_6” (see the 4.01.01. Items - General tab page for details of these custom fields).
• Data element ID scheme: This tells mSupply what kind of DHIS2 item identifiers are stored in mSupply (in the place defined by the Item field reference section above), item codes or UIDs.
• Round off checkbox: If checked then mSupply will round numerical data values to the nearest whole number.
• Test connection button: Click this to test the connection to the DHIS2 server. You will be shown a message that tells you whether mSupply was able to connect to the DHIS2 server with the credentials you have provided.
• Manual push data button: Click this button to immediately attempt to push the data as setup in this window to DHIS2. The data will, of course, be pushed on a current day basis. View the log (see the 25.19. The system log section for details) to see the results of the attempt.

After entering the values you should click on the Test connection button to save the credentials and check that mSupply can now access the DHIS2 database. If the connection is successful you will see a green “Connection successful” message next to the button.

If the connection is not successful you will see a red “Authentication failed” message next to the button. Check your settings, edit them as necessary and try again. The connection problem may not be the credentials, it could be something else like the settings for firewalls between mSupply and the DHIS2 database.

Once configured, a scheduler will run and regularly send data from mSupply to DHIS2. If there are any errors these will be saved in the log (see the 25.19. The system log page for details).

Of course, once you have told mSupply where all the data is stored, you have to actually enter the DHIS2 item identifiers and Store identifiers into mSupply.

Connections to DHIS2 have been configured successfully for Laos and countries that are part of the Tupaia project including Kiribati, Tonga, Solomon Islands, Cook Islands and Vanuatu. And lots more!