DHIS2 Integration
OpenBoxes Lift can fill your monthly stock form in DHIS2 for you. You choose the form on your own DHIS2 server, match your OpenBoxes locations and products to it, look at the figures, and Lift sends them after a dry run, by hand or on a schedule once each month closes.
It is included on every plan: Shared, Dedicated and Enterprise. There is no add-on and nothing extra to buy.
What it sends#
Lift sends aggregate figures only: one number per facility, per product, per month, keyed by the DHIS2 identifiers of your form. The figures come from Lift's once-a-day stock check of your instance, not from a live reading.
These are the figures you can map to places on your form. The names are the ones the portal shows in the Lift figure column.
| Lift figure | What it is |
|---|---|
| Opening balance | Stock on hand at the morning check on the 1st of the month |
| Received | Supplier receipts, and returns from wards unless you turn that off. Transfers from your other locations only if you turn that on |
| Dispensed | Stock issued and consumed. Transfers to your other locations only if you turn that on |
| Losses: expired | Stock written off as expired |
| Losses: damaged | Stock written off as damaged |
| Losses: total | Expired plus damaged, and returns to suppliers if you turn that on |
| Positive adjustments | Adjustments, count corrections and stock loads that added stock |
| Negative adjustments | Adjustments, count corrections and stock loads that removed stock |
| Net adjustment | Positive adjustments minus negative adjustments |
| Closing balance | Stock on hand at the morning check on the 1st of the next month |
| Days out of stock | Days whose end-of-day stock was zero, from the daily checks |
| Maximum level | The maximum stock level set in OpenBoxes at the end of the month |
| Minimum level | The minimum stock level set in OpenBoxes at the end of the month |
| Quantity to order | Maximum level minus closing balance, never below zero |
| Average monthly consumption | Issued plus consumed, averaged over this month and the two before it. Not sent with fewer than 3 months of history |
| Months of stock | Closing balance divided by average monthly consumption, to one decimal place |
You map only the figures your form asks for. Several OpenBoxes locations can share one DHIS2 facility (organisation unit); their figures are added together.
What is never sent: no person names or email addresses, no lot numbers, no prices or money, and no product or location names. Only numbers, keyed by DHIS2 identifiers.
Before you start#
You need:
- DHIS2 version 2.40 to 2.43. Older versions are refused. A server newer than 2.43 connects, with a warning.
- The standard (ISO) calendar. Servers that use another calendar, for example the Ethiopian or Nepali calendar, are not supported yet.
- A monthly form (a data set with a monthly period) that you report stock on. Weekly, quarterly and other periods are not supported.
- An https address with a certificate from a public certificate authority, reachable from the internet over IPv4 on the standard https port (443). A certificate from a private authority fails, and so does an address with another port number in it. A server that only accepts known addresses works once it allows both of Lift's addresses (see If your DHIS2 server has an IP allow-list). Servers reachable only over a VPN cannot be connected yet.
- A DHIS2 account for Lift to sign in as. We recommend a data entry account that can enter data only for the forms you report on, not one that can change closed periods or that holds every authority (ALL). Lift signs in with either:
- a personal access token (recommended). It starts with
d2p_; in DHIS2 you create one from your profile, then Personal access tokens; or - a username and password for that account.
- a personal access token (recommended). It starts with
- That account assigned to your facilities (organisation units) and given data entry access to the form.
- Your OpenBoxes locations and products set up in OpenBoxes. If you want Quantity to order, Maximum level or Minimum level, set minimum and maximum levels for those products and locations in OpenBoxes; Lift does not keep a second copy of them.
The public DHIS2 demo servers (play.dhis2.org, play.im.dhis2.org) cannot be used: Lift does not send your figures to a public demo.
If your DHIS2 server has an IP allow-list#
Many ministry servers only accept connections from known addresses. If yours does, add both of these addresses to its allow-list:
35.196.140.4034.26.184.92
Allow both. Lift's DHIS2 traffic can come from either address, so a server that allows only one of them will sometimes refuse Lift. These addresses are fixed.
They are used only for DHIS2. Slack, Microsoft Teams and PagerDuty messages and webhook deliveries come from other addresses, which can change, so do not use these two addresses to identify that traffic.
Who can do what#
| Task | Who |
|---|---|
| Connect, edit or remove a DHIS2 server, replace its token, turn it off or on | Account owner only |
| Choose the schedule and completion settings | Account owner only |
| Remove values from DHIS2 | Account owner only |
| Choose forms, match facilities and products, preview, dry run, send and check | Account owner, or a teammate with the Admin role |
| See the connected servers, the forms and the History tab (not the facility and product matches or the preview) | Every other teammate |
Roles are set on the portal's Users page.
Setting it up#
1. Connect a DHIS2 server#
- In the portal, open Integrations, then the Connections tab.
- On the DHIS2 tile, choose Open DHIS2.
- Choose Connect a DHIS2 server (the account owner sees this button; other teammates are asked to have the owner start here).
- Fill in:
- Name: a name you will recognise.
- Server address: the https address you open DHIS2 at, for example
https://dhis2.example.org/dhis. - Sign in with: Personal access token (recommended) or Username and password.
- Save.
The token or password is stored encrypted and never shown again.
2. Wait for approval#
A DHIS2 server our team has not approved before waits for approval before Lift contacts it. Approval is per server address, so a server already approved for another account does not wait again. Until then its status is Waiting for approval, and Lift makes no request to it. When a waiting server is decided, we email the account owner: "Your DHIS2 server is approved" or "We could not approve your DHIS2 server".
Once approved, the status is Connected, and Test connection checks the address, the certificate, the sign-in, the version and the calendar (one test a minute). Changing the address to a different server sends it back for approval; a change of path on the same server does not.
A connection's status is one of Waiting for approval, Not approved, Connected, Needs attention or Turned off. The owner can also Replace token, Edit, Turn off and Remove it.
3. Choose a form#
Choose Choose a form, then Choose a monthly form. The list shows only monthly forms that the DHIS2 account can enter data for. Choose Add this form.
If the form asks for a funding source (an attribute option), pick one Funding source; every figure is sent under it.
Each form then has five tabs: Facilities, Products and columns, Preview and send, History and Schedule and completion. If someone changes the form in DHIS2, choose Read the form again from DHIS2.
4. Facilities#
On Facilities, match each OpenBoxes location to a DHIS2 facility. Suggest matches proposes matches for you to check. A location you leave empty is Not sent.
5. Products and columns#
On Products and columns, match each product and figure to a place on the form. Choose the layout your form uses:
- One row per product: each product is one data element, and the figures (for example consumption and end balance) are its columns.
- One data element per product and figure: each figure of each product is its own data element, sometimes split further (for example discarded, by reason).
Each row has a Multiply by factor for converting units, for example 0.01 when OpenBoxes counts single units and the form counts boxes of 100.
For a long product list, use Download as CSV to edit the matches in a spreadsheet and Upload a CSV to load them back.
6. What counts as received and dispensed#
Under What counts as received and dispensed you choose four settings:
| Setting | Default |
|---|---|
| Count transfers in as received | Off |
| Count transfers out as dispensed | Off |
| Count returns from wards as received | On |
| Count returns to suppliers as losses | Off |
Transfers between your own OpenBoxes locations are not counted by default, because Lift cannot yet tell a transfer inside one facility from a delivery by another store. Turn them on only if these locations never send stock to each other.
7. Preview and send#
- On Preview and send, pick a Month. Only closed months are offered (never the current or a future month), up to the last 12.
- Read What would be sent. Each value shows Where it comes from, and the month is marked Not ready, Provisional or Final (see Timing). Download the exact data gives you the file Lift would send.
- Choose Dry run. DHIS2 checks everything and saves nothing.
- Choose Send to DHIS2. A send needs a dry run that passed for the same figures within the last 15 minutes. A send replaces values Lift sent before for the same places.
- Choose Check what DHIS2 has at any time to read the values back from DHIS2 and compare them with what Lift sent.
Warnings in the preview never stop a send. A value Lift cannot work out is marked Not sent and left out, and the rest of the form still goes.
If a new send leaves out values that an earlier send put in DHIS2, the account owner can use Remove these values from DHIS2. Lift runs a dry run first, then removes exactly the values listed.
8. History#
History lists every dry run, send, check, completion and removal, with who started it: Account owner, Admin or Scheduled.
9. Schedule and completion#
On Schedule and completion the account owner chooses when a form is sent:
| Option | What happens |
|---|---|
| Only when someone sends it | Nothing is sent automatically. This is the default |
| As soon as the month closes, and correct it by the 10th | Lift sends on the 1st, and sends again by the 10th only if a figure changed |
| Once, on a day of the next month | Lift sends once, on the day you choose (1 to 28) |
Mark the form complete in DHIS2 can be Never (the default), After the final send or After every successful send.
Hold a scheduled send when the preview has warnings is off by default. Turn it on if you would rather look at a month with warnings before it goes.
Timing#
- Months are your account's calendar months, in the time zone set under Settings > General (US Eastern if none is set).
- A month is ready after the morning check on the 1st of the next month. From then it is Provisional: movements entered in the next few days can still change it.
- It is Final from the check on the 10th. Entries dated more than 8 days in the past no longer change the month, and such backdated entries never reach Lift's monthly figures.
- The form's lock date wins. If your DHIS2 form closes (its expiry days or data input periods) before the 10th, the scheduled correction goes on the day before the form closes instead, still only if a figure changed. If that day would fall before the first send (a form that closes very soon after the month ends), there is no correction. A form that closes before Lift has the month cannot be scheduled, and Lift never sends after the form's lock date.
- Approved data is never overwritten. If a facility's figures for the month are approved or accepted in DHIS2, Lift skips that facility and names it. Lift never approves data itself.
- Months before Lift's daily stock check started for your account have nothing to preview.
- Your first month may be incomplete. The daily stock check started in late September 2026, and for a new account it starts on the day the account joins. If there was no check on the 1st of your first month, its Opening balance is not known and is not sent, and its Days out of stock covers only the days Lift checked.
Limits#
- Up to 3 DHIS2 servers per account, and up to 10 forms per server.
- Up to 10 sends by hand a day per account (removing values from DHIS2 counts as a send), and one connection test a minute per account.
What it does not do#
- Nothing comes back from DHIS2 into OpenBoxes. It is one way.
- No tracker programs or events, and no ADX. Monthly aggregate forms only.
- Not live. The figures come from the once-a-day stock check.
- No approval in DHIS2. Lift never approves or accepts data.
- No servers reachable only over a VPN, no private certificate authorities, and no calendars other than the standard (ISO) one, yet.
- No sending while your instance is suspended.
Troubleshooting#
| Message | What it means |
|---|---|
| "Lift could not reach this server." | The address is wrong, or the server only accepts known addresses and does not allow both of Lift's addresses yet (see If your DHIS2 server has an IP allow-list) |
| "Lift reached the server but could not trust its certificate." | The certificate comes from a private authority. Lift needs one from a public authority |
| "DHIS2 did not accept the token or password." | The token may have expired. Create a new one in DHIS2, then use Replace token |
| "Lift works with DHIS2 version 2.40 or later. This server runs ..." | The server needs upgrading to DHIS2 2.40 or later |
| "This server uses a calendar Lift does not support yet." | The server does not use the standard (ISO) calendar |
| "The address answered, but Lift could not read the reply as DHIS2." | The address should end where your DHIS2 starts, for example https://dhis2.example.org/dhis |
| "This DHIS2 account cannot enter data for any monthly form." | Ask your DHIS2 administrator to give the account data entry access to the form you report on |
| "DHIS2 refused the whole form, so nothing was saved." | Usually a facility, data element or column no longer matches. Choose Read the form again from DHIS2 and fix the matches it marks |
| "... values were not accepted by DHIS2. The rest were saved." | DHIS2 refused some rows; the reasons are listed under the result |
| "The form for ... closed on ... on your DHIS2 server." | The form's lock date has passed. Nothing was saved, and Lift will not try again |
| "... approved in DHIS2, so they cannot be changed from Lift." | That facility's month is approved in DHIS2 and was skipped |
| "Run a dry run of these figures first." | A send needs a passed dry run of the same figures within the last 15 minutes |
| "Lift missed some stock movements this month, so the movement figures are not sent." | Those values are held back as Not sent; the rest of the form still goes |
| "Lift has no stock check for the 1st of this month, so the opening balance is not known." | The opening balance is held back as Not sent; the rest still goes |
| "The opening balance plus movements does not match the closing balance. You can still send." | A warning only. It never blocks a send |
For anything else, ask in the support chat in the portal.
Importing DHIS2 data when you move onto Lift#
This integration sends figures to DHIS2. It does not bring DHIS2 data into OpenBoxes, and a DHIS2 aggregate data-value export still cannot be imported when you move onto Lift.
Those exports are per-period summary counts (opening balance, received, distributed, closing balance) keyed by DHIS2 identifiers. They contain no item-level stock (no lots, no expiry dates, no individual movements), and OpenBoxes works out stock from transactions, so summary counts have nothing to attach to. The import wizard recognises these files and explains this rather than guessing at a mapping.
Instead, export item-level data from the system that feeds DHIS2: the facility's stock cards, an eLMIS such as OpenLMIS, or spreadsheets of movements (date, type, product, quantity). Those import fine, including as transaction history. See Migrating your data, or contact support for help with an import.
Related#
- DHIS2 overview: what is sent, how the month works and who can do what, on one page.
- Integrations overview: everything that connects today.
- Migrating your data: importing item-level data when you move onto Lift.
