Interface - Interface with DHIS2

Target release3.6
Epic OLMIS-5443 - Getting issue details... STATUS
Document status
eLMIS StatusImplemented
OpenLMIS StatusNot Implemented
PATH Jenny Thompson (Unlicensed)
OpenLMIS Mary Jo Kochendorfer (Deactivated)
JSI Ashraf


This is blocked by OpenLMIS and DHIS2 sharing a common understanding of:

While it is blocked, structuring the overall work this way should make it simpler.


Scope: OpenLMIS needs to send data related to RMNCH products and LLIN to DHIS2. <need to confirm what data is being sent and the scope>

Status in eLMIS: In eLMIS.

Status in OpenLMIS: Not Implemented

Priority: High priority for Tanzania


The RMNCH program and Malaria program want to see eLMIS logistics data triangulated with service statistics-related data separately collected in DHIS2 through custom dashboards created in DHIS2.

This interface requires additional configurations at both end, described in the user stories.

Indicators (all have expressed desired from MW):

  • Stock on hand (aka stock status) - in TZ
  • received quantities
  • consumed quantities (in TZ)
  • total stock out days (not in TZ however interest has been expressed)

By product, time period and facility.

In Tanzania a few special notes apply for how these indicators are currently defined for DHIS2:

  • Tanzania is transitioning from a quarterly to a monthly reporting cycle.
  • Monthly consumption of product = quarterly consumption / 3
  • Stock status, the first two months are left as 0. the current stock status is reported as the stock on hand of the last month.


User Stories

#TitleUser StoryLabelImportanceNotes
1Generate XML file for feed into DHIS2

As an administrator I need a process for generating an XML file to send to DHIS2 so that I can export to DHIS2.

Tanzania eLMIS DHIS2 interfaceMust have

This is currently a server side script in Tanzania.

2Obtain URL for data submission from DHIS2

As an administrator I need information from DHIS2 so that I can submit data with the curl tool.

DHIS2 requires: site address/URL, form submission location locational to be included on the URL, user id, and password.

Tanzania eLMIS DHIS2 interfaceMust haveDHIS2 expects data to be submitted through  “curl” utility. DHIS2 will provide these information.
3Automate the data feed routine

As an administrator, I need to be able to automate monthly data submission so that user intervention is not required for this to happen consistently each month.

Tanzania eLMIS DHIS2 interfaceMust haveThis is done through server side scripting.


Facilities list

Product list

Data items list

<dataValueSet xmlns="" >

<dataValue orgUnit="Lo423ozVkFw" dataElement="ndLcCJP1R5n" period="201607" value="0"/>

<dataValue orgUnit="Lo423ozVkFw" dataElement="ndLcCJP1R5n" period="201608" value="0"/>

<dataValue orgUnit="Lo423ozVkFw" dataElement="ndLcCJP1R5n" period="201609" value="0"/>

<dataValue orgUnit="Lo423ozVkFw" dataElement="m6oXxb5XAUn" period="201607" value="0"/>

<dataValue orgUnit="Lo423ozVkFw" dataElement="m6oXxb5XAUn" period="201608" value="0"/>

<dataValue orgUnit="Lo423ozVkFw" dataElement="m6oXxb5XAUn" period="201609" value="0"/>

<dataValue orgUnit="Lo423ozVkFw" dataElement="DZKHCq8f3NQ" period="201607" value="0"/>

<dataValue orgUnit="Lo423ozVkFw" dataElement="DZKHCq8f3NQ" period="201608" value="0"/>

<dataValue orgUnit="Lo423ozVkFw" dataElement="DZKHCq8f3NQ" period="201609" value="0"/>

<dataValue orgUnit="Lo423ozVkFw" dataElement="EpNzl1xg26I" period="201607" value="0"/>

<dataValue orgUnit="Lo423ozVkFw" dataElement="EpNzl1xg26I" period="201608" value="0"/>

<dataValue orgUnit="Lo423ozVkFw" dataElement="EpNzl1xg26I" period="201609" value="0"/>

<dataValue orgUnit="Lo423ozVkFw" dataElement="JmxXYzhJMA6" period="201607" value="0"/>

<dataValue orgUnit="Lo423ozVkFw" dataElement="JmxXYzhJMA6" period="201608" value="0"/>

<dataValue orgUnit="Lo423ozVkFw" dataElement="JmxXYzhJMA6" period="201609" value="0"/>


Sample XML file



Discussion about Facility List Sync and Product List Sync as a blocker

The Governance Committee recommended that we develop the DHIS2 interface before developing facility list and product list synchronization. This section provides an area for discussion around the assumption that the Facility List Sync and Product List Sync are blockers.

Craig's comments:

From my perspective, the answer is "Yes" we can, and maybe should, do the DHIS2 integration before we do the facility and product list syncing. The DHIS2 integration will focus on identifying the org unit hierarchy, developing the pertinent data elements and identifying indicators that add value to DHIS2 consumers. eLMIS is already integrated with DHIS2 and we have a clear map between the DHIS2 field data elements, indicators and geographic hierarchy between OpenLMIS v2 and DHIS2. To put it another way, we have all of the information we need to do the DHIS2 integration.

Facility list sync vs DHIS2 org unit integration

The facility list sync epic focuses on developing automated mechanisms to share location information between OpenLMIS and another system. Regardless of the approach, OpenLMIS must be able to consume a list of locations and map them to the internal representation of the geographic hierarchy and list of locations in OpenLMIS. OpenLMIS must also be able to serve the list of locations and geographic hierarchy to a third party system so they can consume it. Beyond that, we need to develop a mechanism for moderating changes between each system when a location is created, edited or archived in any of the systems.

The DHIS2 org unit integration is a much reduced set of tasks because the focus is on mapping so the country can report information from OpenLMIS to DHIS2 for either data value sets or through DHIS2 tracker. In this case, OpenLMIS just needs to know the DHIS2 org unit ID of each location and geographic hierarchy level that's stored in OpenLMIS. When OpenLMIS needs to push information to DHIS2, these org unit IDs will be mapped to the outgoing JSON or XML and pushed to DHIS2. The minimum viable product does not require a two way sync. Instead, the user should be able to add DHIS2 org unit IDs for each location and step in the geographic hierarchy and view a report of all facilities that includes the DHIS2 org unit ID so they can go and correct any errors.

Product list sync vs. DHIS2 data element/value setup

Note: I'm getting a bit beyond my element here because I don't know exactly how products are structured in DHIS2. I assume they are added as either data elements or values. They could also be mapped to DHIS2 tracker as program elements.

The product list sync feature focuses on ensuring products are appropriately represented across OpenLMIS, ERP system(s) and reporting systems. In this case, there would be a mechanism to represent a product in a certain way in OpenLMIS and map that product to a different product in the ERP or reporting system using GS1 standards or not. The core development would include extending the OpenLMIS v3 orderable model to include representations from external sources so mapping can be done where there is the same product referenced by different codes in OpenLMIS and the third party system. If OpenLMIS does not have a representation of that product, the implementer should be able to import it along with pricing information for a particular trade item. Furthremore, OpenLMIS will need to be able to "serve" or export the product list in a way that it can be consumed by a third party (again following GS1 standards or not).

I expect that the need for product information in DHIS2 is drastically different from the needs of an ERP. The core use case for DHIS2 is program related reporting either through value sets or tracker. In this case, locations are most likely reporting aggregate values of a particular commodityType so that can be mapped against the health information that's stored in DHIS2. For example, they need to know how many vials of BCG were consumed, the number of doses per vial on aggregate and closed vial wastage in number of vials and doses. This information will then be compared against the total number of children given BCG during the same time period and they will be able to calculate open vial wastage. OpenLMIS will need to retain a map between the calculated indicators by commodityType (both vials and doses) and the DHIS2 dataElements, dataValues or indicator codes. This mapping is more like a commodityType to DHIS2 indicator mapping unless there is an initiative to store trade items in DHIS2.

From my perspective, the need for product information in DHIS2 is limited to commodityTypes and the product list sync requires a detailed list of trade items, lots, expiration dates, VVM status, price. etc.

The elephant in the room

From my perspective, the integration with DHIS2 isn't an integration between OpenLMIS and DHIS2. It's an integration between the reporting stack and DHIS2. As I understand it, the OpenLMIS microservices will not be aggregating information. That task is solely reserved for the reporting system. OpenLMIS could push individual values to DHIS2 through data pumps, if we want, but that doesn't solve the majority use case of "reporting" to DHIS2. In this case, the reporting stack needs to retain the map between the OpenLMIS geographic hierarchy and the DHIS2 org unit hierarchy. The reporting stack will also need to calculate the indicators that are required to be pushed as data value sets by period to get aggregate information into DHIS2. We could extend this to work with DHIS2 tracker if there is a clear use case, forwarding events when they are picked up in Nifi.

Open Questions

Below is a list of questions to be addressed as a result of this requirements document:


A District Consumption Comparison report is mentioned elsewhere in the gap analysis document. Is this also a Tanzania gap?

"Displays consumption comparison across multiple districts. The comparison is represented by % i.e. total consumption of district x/total consumption of all districts * 100."

Yes, It is a gap in Tanzania
2For Tanzania user stories: review/update the users and "so thats".

3Is the only scope of data around consumption? Is there ever a need for DHIS2 to know the current SOH levels?Yes

Out of Scope

OpenLMIS: the global initiative for powerful LMIS software