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.

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

1. Current stock on hand
2. Current months of stock on hand
3. The amount of stock in adjustments
4. The amount of stock received
5. The amount of stock issued
6. The amount of stock expiring within 90 days
7. The amount of stock expired
8. Average monthly consumption
9. Days out of stock
10. Stock at the beginning of the month
11. Stock at the end of the month
12. Whether the item is currently stocked out

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 “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.

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: Only visible and used if Basic authentication is not checked. The client name mSupply must use to access the database.
• Secret: Only visible and used if Basic authentication is not checked. The secret that is used for mSupply to access the DHIS2 database. No need to enter this if none was provided.
• Setup: Here you choose how to identify the elements of data that you send to DHIS2 must be identified. Your choice depends on how DHIS2 is configured.
  • Using category option combo: Choose this if DHIS2 is using attribute option combos where there is one category option combo assigned per data element (AMC, stock on hand etc.) for an entire data set. For this option, you need to tell mSupply what the DHIS2 category option combo ID is for each data element you want to push (i.e. Active column is checked) in the Data elements to push table.
  • Different data elements per item: Choose this if there is a different identifier for each data element for each item. These identifiers need to be entered for each item in item user fields or item custom fields - you enter the name of the field the value is stored in into the Data elements to push table in the Custom field name column.
  • Push only 1 data element: Choose this if you are only pushing a single data element (e.g. AMC, stock on hand etc.) for each item to DHIS2. In the Data elements to push table you must check only a single box in the Active column and no values need to be entered in the Category option ID or Custom field name columns.
• 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.
  • Prefix column: If the data element ID needs to have a prefix added to it before it is sent to DHIS2 then enter that in this column.
• 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.
• Store field reference: Enter the name of the store custom data field that identifies which stores to send data to DHIS2 for. Data will be sent for all stores that have a value in the store custom data field with this name.
• Round off checkbox: If checked then mSupply will round numerical data values to the nearest whole number as some DHIS2 setup only accept integers.
• No. of items per payload: Enter the number of pieces of information to send in a particular call to the DHIS2 server. If there are more than this number of pieces to send then they will be split up into separate calls with this number of pieces of information in them. Helpful if there is a lot of information to send but the DHIS2 server can't handle the volume of information (which usually results in internal errors being returned).
• 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!