integration:dhis2_lmis_integration

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
integration:dhis2_lmis_integration [2024/10/17 11:30] – [mSupply preferences] Gary Willettsintegration:dhis2_lmis_integration [2024/10/22 07:07] (current) – [mSupply preferences] Gary Willetts
Line 1: Line 1:
 {{indexmenu_n>15}} {{indexmenu_n>15}}
 ====== 23.02. DHIS2 LMIS integration ====== ====== 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 tool at small health facilities. mSupply can interact with this functionality to receive the stock on hand reports and then create replenishment orders for the facilities based on that information. This page describes the setup that must be carried out in mSupply.+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. 
 + 
 + 
 +===== The process ===== 
 +==== Fetching requisitions ==== 
 +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:  
 + 
 +{{ :integration:pasted:20241017-120358.png?700 |}} 
 + 
 + 
 +==== Acknowledging shipment receipts and sending shipment transactions ==== 
 +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:  
 + 
 +{{ :integration:pasted:20241017-120432.png?700 |}} 
 + 
 + 
  
  
Line 22: Line 42:
  
 ==== mSupply preferences ==== ==== 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 LMIS// tab to get to this window: +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: 
  
-{{ :integration:pasted:20241017-112730.png?600 |}}+{{ :integration:pasted:20241018-084816.png?600 |}}
  
   * **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.   * **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.
Line 33: Line 53:
   * **Client:** Only visible and used if **Basic authentication** is checked. The client name mSupply must use to access the 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.   * **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.
-  * **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. +  * **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. 
-    * **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. +  * **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 ('';'').
-    * **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.+
   * **Data set ID:** Enter the ID of the dataset in DHIS2 that you want to push the data to.   * **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.   * **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 [[items:item_basics:tab_general|]] 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 [[items:item_basics:tab_general|]] page for details of these custom fields).+  * **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 [[items:item_basics:tab_general|]] 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 [[items:item_basics:tab_general|]] 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.   * **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. +  * **Round off checkbox:** If checked then mSupply will round numerical data values to the nearest whole number as some DHIS2 setups 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). +  * **Name field reference textbox:** The name of the name custom field used to store the ID of the corresponding name in DHIS2. 
-  * **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. +  * **Store field reference textbox:** The name of the store custom field used to store the ID of the corresponding store in DHIS2 
-  * **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 [[admin:the_log|]] section for details) to see the results of the attempt.+  * **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.
  
 <WRAP info center round 90%> <WRAP info center round 90%>
Line 60: Line 81:
 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.  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 [[admin:the_log|]] page for details). +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 [[admin:the_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 [[https://tupaia.org | Tupaia]] project including Kiribati, Tonga, Solomon Islands, Cook Islands and Vanuatu. And lots more! 
 \\ \\
 \\ \\
  • Last modified: 2024/10/17 11:30
  • by Gary Willetts