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 data

DHIS2 stores data values that have 3 dimensions:

DHIS2 Dimension	Description	mSupply typical mapping
organisation unit	Can be a facility, or a region	The customer or store in mSupply
data element	The type of data that is stored	Usually a combination of an item code and the type- for instance “SOH_368c74bf” for the stock on hand of Amoxycillin 250mg Capsules (using the universal code from https://codes.msupply.foundation/detail/368c74bf)
Period	The historical time period associated with the data	Same in mSupply

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.

Common types of data that you can send to DHIS2 from mSupply for an item:

Current stock on hand

Current months of stock on hand

The amount of stock in adjustments

The amount of stock received

The amount of stock issued

The amount of stock expiring within 90 days

The amount of stock expired

Value of stock on hand

Average monthly consumption

Days out of stock

Stock at the beginning of the month

Stock at the end of the month

Whether the item is currently stocked out

Setup

Items

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:

Use the item's universal code. See the 4.01.01 Items - General tab section for details on setting this.

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

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 “Dhis2Code” store custom field containing the Org unit reference to each store you want to send data to DHIS2 for. For all stores you don't want to send data to DHIS2 for, simply leave the “Dhis2Code” custom field empty.

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

mSupply preferences

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: Choose depends on your DHIS2 configuration

Using category option combo: If you are using attribute option combos where there is one category combo assigned per data for an entire data set.

Different data elements per item: If there is an assigned data element per item per data.

Push only 1 data element: If you only have 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: Required if Using category option combo is selected in the Setup section. This is the DHIS2 category option ID for the data element.

Custom field name column: Required if Different data elements per item is selected in the Setup section. Enter the corresponding item custom field name used to identify the item corresponding DHIS2 data element code.

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 arrow 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 down arrow 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: Required for “Using category option combo” and “Push only 1 data element” setup. 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 as some DHIS2 setup only accept integers.

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.

If this page already has settings entered and they have been used to successfully connect to the DHIS2 database then a “Last successful connection: date & time” message will show next to the Test connection button.

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!

Previous: 23. Integration with other systems | | Next: 23.03. FrontlineSMS integration