23.02. DHIS2 LMIS integration

DHIS2 is an open source data warehouse that can be used to store, aggregate and display health data. It has also been modified to be used as a simple stock reporting and ordering tool at small health facilities. mSupply can interact with this functionality to receive the stock on hand reports and requisitions and create replenishment orders for the facilities based on that information. This page describes how it works and what setup must be carried out in mSupply.

In this scenario, the supplying facility is using mSupply and the requesting facility is using a DHIS2 Event app. The requesting facility creates and saves a requisition in the event app and it is saved to the DHIS2 database. On a daily basis, mSupply checkes the DHIS2 database for completed requisitions, retrieves them and sends them to the supplying store's copy of mSupply as a customer requisition. The process is illustrated in this diagram:

The next part of the process is that the sending store sends goods to the facility that requested them with the requisition. The goods are sent with a packing list that contains a QR code. When the receiving facility receives the goods they add the consignment to the DHIS2 RTS capture app by scanning the QR code and check what has arrived. When they are happy the receiving facility marks the consignment as complete.

On a daily schedule mSupply checks the DHIS2 database for complete consignments and retrieves them (at the same time mSupply fetches stock on hand figures for the items in the various facilities. This is not shown in the diagram below). mSupply processes the details of the consignment and sends details of the stock supplied for the consignment to the DHIS2 server. The DHIS2 server then sends the updated stock levels to the RTS capture app at the requesting facility.

This process is illustrated in the following diagram:

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 data to and retrieve data from a DHIS2 LMIS instance, you need to tell mSupply where the data has to go and come from. To do that, go to File > Preferences and click on the DHIS2 LMIS tab to get to this window:

• Use DHIS2 checkbox: If checked then the DHIS2 interface is turned on and data is sent to and pulled from DHIS2. If it is unchecked then the interface is turned off and no data is shared with 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 checked. The client name mSupply must use to access the database.
• Secret: Only visible and used if Basic authentication is checked. The secret that is used for mSupply to access the DHIS2 database. No need to enter this if none was provided.
• 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.
• Send errors to this email address textbox: All errors will be sent to theis email address. Enter multiple email addresses by separating them with a semicolon (;).
• 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 whose name is 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 setups only accept integers.
• Name field reference textbox: The name of the name custom field used to store the ID of the corresponding name in DHIS2.
• Store field reference textbox: The name of the store custom field used to store the ID of the corresponding store in DHIS2
• Order program ID textbox: Put the ID of the DHIS2 Order program used for requisitions in this field. Click the Manual pull data button next to this field to immediately fetch completed requisitions from DHIS2, rather than waiting for it to be done on the automatic schedule.
• Receipt program ID textbox: Put the ID of the DHIS2 Receipt program used for shipment receipts in this field. Click the Manual pull data button next to this field to immediately fetch completed consignments from DHIS2, rather than waiting for it do be done on the automatic schedule.
• STR program ID textbox: Enter the ID of the DHIS2 STR program used for storing Stock on Hand values into this field. Click on the Manual pull data button next to this field to immediately fetch stock on hand figures for facilities, rather than waiting for it do be done on the automatic schedule.
• RTS SOH Raw data button: Click this to display the raw stock on hand data pulled from DHIS2.
• Data elements table In this table, select the data elements that you want to pull from DHIS2 for each mSupply item.
  • Active column: Check the checkbox for each data element you want to pull for an item. Click on the checkbox to toggle it on and off.
  • Data element column: Read only, the name of the element the settings in this line are for.
  • Program data element ID column: The ID of this data element in the Program.
  • Program stage ID column: The ID of the program stage this data element belongs to.
  • Attribute ID column: The ID of the attribute this data element has in the program stage.

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 every 5 minutes and regularly pull data from and send data to the DHIS2 LMIS instance. If there are any errors these will be saved in the log (see the 25.19. The system log page for details).