DHIS2 Integration
What is DHIS2?
DHIS2 (District Health Information Software 2) is the world's largest health information management system, used in over 100 countries. It serves as the backbone for national health reporting, disease surveillance, and program monitoring. Many Ministries of Health require facilities to report stock and consumption data into DHIS2 on a monthly or quarterly basis.
Why Integrate OpenBoxes with DHIS2?
If your organization manages supply chains with OpenBoxes and reports health data through DHIS2, this integration eliminates the manual re-entry of stock data. Common use cases include:
- National stock reporting --- Automatically push stock-on-hand, consumption, and stockout data from OpenBoxes to DHIS2 aggregate data sets.
- Facility-level reporting --- Map OpenBoxes warehouse locations to DHIS2 organization units so each facility's data flows to the correct reporting level.
- Commodity tracking --- Sync tracer commodity stock levels for national supply chain visibility dashboards.
- Consumption analytics --- Feed OpenBoxes dispensing data into DHIS2 indicators for program performance monitoring.
How It Works
The integration uses DHIS2's Web API to push data from OpenBoxes:
OpenBoxes (stock data) --> Data Mapping --> DHIS2 Web API --> DHIS2 Data Sets
- OpenBoxes calculates stock-on-hand and consumption for a reporting period.
- The integration maps OpenBoxes products and locations to DHIS2 data elements and organization units.
- Data is pushed to DHIS2 as aggregate data values via the
/api/dataValueSetsendpoint.
Configuration Steps
1. Gather DHIS2 Credentials
You will need:
- DHIS2 instance URL (e.g.,
https://dhis2.your-country.org) - A DHIS2 user account with data entry permissions for the relevant organization units
- The data set UID for the target reporting form
2. Map Products to Data Elements
Create a mapping between OpenBoxes product codes and DHIS2 data element UIDs:
| OpenBoxes Product | DHIS2 Data Element UID | DHIS2 Category Option Combo |
|---|---|---|
| Amoxicillin 250mg | aB3cD4eF5gH |
default |
| Malaria RDT | iJ6kL7mN8oP |
default |
Tip: Export your DHIS2 data elements via the API (
/api/dataElements.json) to get the UIDs. Filter by your data set to narrow the list.
3. Map Locations to Organization Units
Each OpenBoxes warehouse or facility must map to a DHIS2 organization unit:
| OpenBoxes Location | DHIS2 Org Unit UID |
|---|---|
| Central Warehouse | qR9sT0uV1wX |
| District Hospital | yZ2aB3cD4eF |
4. Configure Sync Settings
Through the OpenBoxes Lift portal or configuration files, set:
- Sync frequency --- Monthly, quarterly, or on-demand
- Reporting period --- Which period the data covers
- Data set --- The DHIS2 data set UID to submit against
5. Test the Integration
Run a test sync with a single facility and review the data in DHIS2 before enabling for all locations.
Data Mapping Details
The integration supports these data flows:
| OpenBoxes Data | DHIS2 Equivalent | Notes |
|---|---|---|
| Stock on hand | Closing balance | End-of-period quantity |
| Quantity consumed | Consumption | Dispensed or issued quantity |
| Quantity received | Receipts | Goods received in period |
| Stockout days | Days out of stock | Calculated per product per location |
| Quantity expired | Losses / wastage | Expired or damaged stock |
Limitations
- One-way sync --- Data flows from OpenBoxes to DHIS2 only. DHIS2 data is not pulled back into OpenBoxes.
- Aggregate data only --- The integration pushes aggregate (summarized) data, not individual transactions.
- Custom setup may be required --- Every DHIS2 instance has unique data element structures. The product-to-data-element mapping must be configured for your specific DHIS2 setup.
- Period alignment --- OpenBoxes reporting periods must align with DHIS2 period types (monthly, quarterly). Misaligned periods require manual adjustment.
Warning: Ensure your DHIS2 user account has
data entrypermissions for all target organization units. The integration will silently skip org units where the user lacks permissions.
Getting Help
If you need assistance setting up the DHIS2 integration, contact support. Enterprise tier customers receive dedicated integration engineering support for complex DHIS2 configurations.