Sending monthly stock reports from OpenBoxes to DHIS2

If your program reports stock into DHIS2, someone probably spends the first days of every month copying figures from one system into a form in another: opening balance, received, dispensed, losses, closing balance, per facility and per product. OpenBoxes Lift can fill that monthly form for you. This article explains what it sends, how the timing works, and what to have in place before you start. The full reference is DHIS2 Integration.

It is included on every plan (Shared, Dedicated and Enterprise), with no add-on to buy.

What Lift sends#

Lift sends aggregate figures only: one number per facility, per product, per month, into the monthly form (the data set) you already report on. You choose which of these figures your form asks for:

• Opening balance and Closing balance: stock on hand at the morning check on the 1st of the month, and on the 1st of the next month.
• Received and Dispensed: supplier receipts (and returns from wards, unless you turn that off), and stock issued and consumed.
• Losses: expired, damaged, and a total.
• Adjustments: positive, negative and net.
• Days out of stock: days whose end-of-day stock was zero.
• Maximum level, Minimum level and Quantity to order: from the levels you set in OpenBoxes. Quantity to order is the maximum level minus the closing balance, never below zero.
• Average monthly consumption and Months of stock: consumption averaged over the month and the two before it, and the closing balance divided by that average.

Every value is keyed by the identifiers on your DHIS2 form. No person names, lot numbers, prices or product and location names are sent. Nothing comes back from DHIS2 into OpenBoxes, and tracker programs and events are not part of it.

The figures come from Lift's once-a-day stock check of your instance, not a live reading. That is why the timing below is built around the morning check on the 1st.

How the matching works#

Your OpenBoxes locations and your DHIS2 facilities rarely line up one to one, so you match them. Several locations can share one DHIS2 facility, and their figures are added together; a location you leave unmatched is simply not sent.

Products are matched to places on the form. Lift handles the two common form layouts: one row per product with the figures as columns, or one data element per product and figure. If DHIS2 counts in a different unit, a Multiply by factor on each row converts it, for example 0.01 when the form counts boxes of 100. For a long product list you can download the matches as a CSV, edit them in a spreadsheet, and upload them back.

One setting deserves attention: transfers between your own locations are not counted as received or dispensed by default. Lift cannot yet tell a transfer inside one facility from a delivery by another store, so counting them could inflate received and dispensed: a transfer between two of your locations matched to the same facility would be counted as received at one and dispensed at the other. Turn them on only if the locations in question never send stock to each other.

Preview, dry run, then send#

Before anything reaches DHIS2 you see a preview of exactly what would be sent, with where each value comes from. A Dry run asks DHIS2 to check everything and save nothing. Send to DHIS2 needs a dry run of the same figures that passed in the last 15 minutes, so what you checked is what goes. Afterwards, Check what DHIS2 has reads the values back and compares them with what Lift sent.

If a value cannot be worked out (for example, there was no stock check on the 1st, so the opening balance is unknown), Lift marks it not sent and leaves it out; the rest of the form still goes. Warnings never stop a send on their own.

The account owner connects the DHIS2 server. The account owner or a teammate with the Admin role can match facilities and products, preview and send.

The timing: the 1st, the 10th and your lock date#

A month can only be sent once it has closed, using your account's own time zone (US Eastern if none is set).

• From the morning check on the 1st, the month is ready and marked Provisional. Movements entered in the next few days can still change it.
• From the check on the 10th, it is Final. Entries dated more than 8 days in the past no longer change it.

You can send by hand whenever you like, or let the account owner choose a schedule: As soon as the month closes, and correct it by the 10th sends on the 1st and sends again by the 10th only if a figure changed; Once, on a day of the next month sends once on the day you pick.

Two rules on the DHIS2 side always win. If your form closes (its expiry days or data input periods) before the 10th, the scheduled correction goes on the day before it closes instead, and only if a figure changed; Lift never sends after the form's lock date. And if a facility's figures for the month are approved in DHIS2, Lift skips that facility and says so rather than overwriting approved data.

What to have ready#

• DHIS2 version 2.40 to 2.43, using the standard (ISO) calendar, with a monthly form.
• An https address with a certificate from a public authority, reachable from the internet. A server that only accepts known addresses (an IP allow-list) works once it allows both of Lift's fixed DHIS2 addresses, 35.196.140.40 and 34.26.184.92. Allow both, not just one; Lift's DHIS2 traffic can come from either.
• A DHIS2 account for Lift: ideally a data entry account that can enter data only for the forms you report on, signed in with a personal access token (it starts with d2p_).
• Minimum and maximum levels in OpenBoxes for the products and locations you report on, if your form asks for quantity to order or the levels themselves.
• Three months of history before average monthly consumption and months of stock are sent.

A DHIS2 server our team has not approved before waits for approval before Lift contacts it. It shows Waiting for approval until then, and the account owner gets an email when it is decided.

Getting started#

In the portal, open Integrations, then Connections, and choose Open DHIS2 on the DHIS2 tile. The account owner connects the server; once it is approved, choose the monthly form, match facilities and products, and run a dry run on the last closed month. Your first month may be incomplete: the daily stock check started in late September 2026 (for a new account, on the day it joins), so without a check on the 1st there is no opening balance, and days out of stock covers only the days Lift checked. The dry run is still a good rehearsal. The DHIS2 Integration guide walks through each screen and lists the messages you might see and what they mean.