This guide shows how to connect DHIS2, the open-source health and program information system used by many governments and NGOs, with mWater, step by step and with no coding required. Data can flow both ways: pull DHIS2 indicators into mWater using the AI Integrator, and send mWater survey results back to DHIS2.
DHIS2 and mWater both speak “API.” mWater’s Integrator includes an AI assistant that writes the
connection code for you. You describe what you want in plain language and paste in the DHIS2
address and an access token. Pulling into mWater is the easiest direction and is fully no-code.
Sending out to DHIS2 is also achievable without code by using DHIS2’s own upload screen.
Quickstart - Data from DHIS2 to mWater
1. Create a personal access token in DHIS2
2. Paste it and your endpoint to mWater's Integrator along with instructions on what you want to pull
3. Save the integration and start using the data in your visualizations
Downloadable technical guide
You can refer to a separate, detailed guide in English here.
DHIS2 in five minutes
DHIS2 organizes data differently from mWater. You don’t need to be an expert, but understanding five
terms will make the rest of this guide easier to grasp and will help you give the mWater AI assistant clear
instructions
- Organisation unit.A place in the facility hierarchy (country → region
→ district → facility). Often abbreviated “org
unit.” - Data element. A single thing being measured, e.g. “Malaria
cases” or “Water points functional.”
- Category option combo. A breakdown of a data element, e.g. by age or sex
(“Female, <5”). Every value has one (often
“default”).
- Period The time the value refers to, in a fixed code
format.
- UID. An 11-character ID DHIS2 gives every object, e.g.
fbfJHSPpUQD. APIs use UIDs, not names.
The two kinds of data you can pull
• Aggregate data. Totals already summed by facility and period (e.g. “320 malaria cases, Coast
District, March 2026”). Best for dashboards and indicators. Lives behind /api/analytics and
/api/dataValueSets.
• Tracker / event data. Individual records (one person, one case, one event). More granular. Lives
behind /api/tracker and /api/analytics/events.
For most mWater ↔ DHIS2 work you’ll use aggregate data. This guide focuses there, and notes where
tracker data differs.
Data from DHIS2 to mWater - Steps
This is the easy, fully no-code direction. You describe what you want, paste your DHIS2 details, and the mWater AI Integrator builds, tests and schedules the connection for you.
Step 0 (do this once): get your DHIS2 address and token. Your API base is your DHIS2 web address followed by /api (e.g. https://dhis2.example.org/api). You an test it by opening …/api/me.json while logged in. Then in DHIS2 open your profile → Account security → Personal access tokens → Create new token (Server/script context). Copy the token (it starts with d2pat_ and is shown only once) and treat it like a password.
Next build the import.
First, in mWater go to Manage → Integrations → Manage import integrations → New Import Integration, and pick the destination tableset with source type API.
Second, in the AI assistant describe the data in plain language and paste your DHIS2 address; when asked for credentials, paste the d2pat_ token into the secure secrets field, never into the chat.
Third, let the AI inspect the API, map the fields to columns and show a preview, then check a few values against DHIS2. Finally, set a schedule (Daily or Weekly, in UTC) and Save & Run. Recommend use a relative period such as the last 12 months so each run pulls a rolling window.
For already-summed totals, point the AI at /api/analytics/dataValueSet.json with dx, pe and ou dimensions.
This direction shapes your mWater data to match what DHIS2 expects, exposes it through an Export Integration, then loads it into DHIS2.
The target shape: every value sent to DHIS2 carries four IDs plus the value: dataElement, period, orgUnit, categoryOptionCombo, and value. DHIS2 rejects UIDs it doesn't recognise, so the real work is mapping: your mWater site → a DHIS2 orgUnit UID, and your question or indicator → a DHIS2 dataElement UID.
Create the export.
First, in mWater go to Integrations → Manage export integrations → New Export Integration.
Second, name it and pick the source table (your survey responses or a calculated indicator table).
Third, define columns that exactly match the DHIS2 fields, using calculated expressions to translate (dataElement, period as YYYYMM, orgUnit, categoryOptionCombo, value). Finally, choose output JSON — the best match for DHIS2 — save, and copy the export URL.
Load it into DHIS2 in one of two ways. No-code: open the export URL, save the file, then in DHIS2 use Import/Export → Data import with the format and ID scheme set to UID; run a Dry run first, fix any rejected rows, then import for real. Automated: once the mapping is proven, a small scheduled job on the DHIS2 side can POST the export feed to /api/dataValueSets.
Full detail, endpoint tables and troubleshooting are in the written guide linked near the top of this page.
Illustrated examples
Let's go through the above steps together with a concrete example.
Everything below was captured live from the DHIS2 Sierra Leone demo
(play.dhis2.org, login username admin, password district) and the mWater portal. The same principles apply to your live data.
Part 1
covers the process to export data from DHIS2 to mWater: create a personal access token, find your data's
IDs (UIDs), and then putting it into the Integrator.
Part 2 covers getting data from mWater to DHIS2: Build the export that sends mWater data out.
Data from DHIS2 to mWater - Illustrated example
Both directions need DHIS2 to trust mWater. Set this up once. The recommended method is known as the Personal Access Token (PAT).
1 — Open a DHIS2 demo instance. The demo catalog at im.dhis2.org/public/instances; sign in with admin / district and pick a stable instance.
2 — Log in to the DHIS2 Sierra Leone demo with admin / district. The demo resets nightly, so it is safe to practice on.
3 — Once signed in, click your avatar (top-right). Account security is where DHIS2 keeps your personal access tokens.
4 — Account settings opens in the User Profile app. The left sidebar lists “Personal access tokens” — open it.
5 — Manage personal access tokens. There are none yet so click “Generate new token.”
6 — Choose the token context. Pick “Server/script context” as that’s what the Integrator needs.
7 — Token details. Give it a clear name (e.g. “mWater Integrator”) and an expiration, then generate.
8 — The token is shown only once. Copy it now and paste it into the secrets field; treat it like a password.
9 — Find your data’s IDs via the API: /api/dataElements.json lists each data element’s 11-character UID (e.g. “ANC 1st visit” = fbfJHSPpUQD). You can give these to the Integrator if you want to guide it more deeply on what exact data to bring across.
10 — Now the mWater/Solstice side. The Integrations page has two halves: Import Integrations (pull data in) and Export Integrations (expose data out).
11 — Import Integrations list, with “+ New Import Integration” (top-right). This is the home for a DHIS2 pull.
12 — The Import Assistant: choose a workspace, pick API or Webhook, and describe what to import in plain language and the AI builds the connection.
13 — The same assistant with the DHIS2 prompt pasted in: base URL, token auth, the analytics dataValueSet endpoint, the columns, and a daily incremental run.
Example instruction used: Pull from the analytics dataValueSet endpoint: /api/analytics/dataValueSet.json?dimension=dx:fbfJHSPpUQD&dimension=ou:ImspTQPwCqd&dimension=pe:LAST_12_MONTHS
Each record has: dataElement, period, orgUnit, categoryOptionCombo, value. Create a table with those columns plus an import timestamp. Run daily and only add new or changed rows (incremental import).
Then give your personal access token and base URL https://play.im.dhis2.org
14 - Integration being created
The data pulled from DHIS2 will then be available in the table or tables created by the integration and you can start using it in your visualizations.
Data from mWater to DHIS2 - Illustrated example
Here we create an export integration in mWater, then
First we create an Export Integration
Export Integrations list. Each export has a shareable api.mwater.co URL and CSV / JSON / GeoJSON formats. This is the feed DHIS2 reads on its side.
New Export Integration: name it, then click “Select Data Source” to choose the table and define the DHIS2-shaped columns.
Define columns that exactly match the DHIS2 fields, using calculated expressions to translate as
needed:
– dataElement — the mapped DHIS2 UID for that field
– period — format your date as DHIS2 period code, e.g. monthly YYYYMM
– orgUnit — the mapped DHIS2 org-unit UID for the site
– categoryOptionCombo — the right combo UID, or leave to default
– value — the measured number
Choose output format JSON (matches DHIS2 best) or CSV. Save and use Preview to check. Copy the export URL.
In DHIS2 you can then upload the export through DHIS2's Import/Export app. Go to the Data Import screen and upload the file by setting the matching format (JSON or CSV) and the ID scheme to UID.
The other direction: the DHIS2 Import/Export app loads data into DHIS2. Data Import accepts JSON, CSV, DXF2, ADX and PDF.
Data import – basic options: upload your file, choose the format and an import strategy (Merge / Append / Update / Delete).
Data import – advanced options: set the ID scheme to UID, and click “Start dry run” first to validate without saving.
You can then try a dry run to see and fix any rejected rows, and finally a real import.
To automate this further, you can use the DHIS2 API and build a script that leverages the export endpoint you have created in mWater.
