DHIS2
The DHIS2 module lets BridgeERP HMS report aggregate health data to national HMIS platforms — KHIS in Kenya, eHMIS Uganda, HMIS Tanzania, DATIM / PEPFAR and similar instances built on DHIS2. It turns the hospital’s clinical activity into DHIS2 data values keyed by data element, organisation unit and reporting period, then pushes them to the ministry server and tracks confirmation. This page covers connecting an instance, mapping clinical activity to data elements, the period and org-unit model, and running a sync.
Where to find it
Everything lives under HMS Core → Integration → DHIS2:
| Menu | Opens |
|---|---|
| Configuration → DHIS2 Instances | Server connections (hms.dhis2.instance) — base URL, API version, auth and purpose. |
| Configuration → Field Mappings | Rules linking a platform metric to a data element (hms.dhis2.mapping). |
| Data Elements | The DHIS2 data-element catalogue (hms.dhis2.dataelement) with value and aggregation types. |
| Data Sets (Forms) | Reporting forms that group data elements (hms.dhis2.dataset). |
| Data Values | The actual figures queued and pushed (hms.dhis2.datavalue). |
| Org Units | The facility’s place in the national org-unit hierarchy (hms.dhis2.orgunit). |
| Sync Runs | Each push / pull job and its outcome (hms.dhis2.sync.run). |
Before you start
- Get the instance details from the ministry: base URL (for example
https://play.dhis2.org/40.0), the API major version (39, 40 or 41) and credentials. - Know your org-unit. The ministry assigns each facility a DHIS2 organisation-unit id; you cannot push without it.
- Have the data-element ids. Each figure you report maps to a ministry data element id and category-option-combo.
Step-by-step: connect an instance and push
- Open Configuration → DHIS2 Instances and create a record. Enter Name, a unique Code, the Base URL and API version.
- Pick the Auth Type: HTTP Basic (username / password), Personal Access Token (paste the PAT), or OAuth2 (PKCE). Set the Purpose (National HMIS, DATIM / PEPFAR, Ministry Internal, Research, Partner Organization or Test / Sandbox) and the ISO Country Code.
- Set the Default Reporting Org-Unit and the local Facility it maps to.
- Click Test Connection. The instance calls
/api/system/infoand posts the server version into the chatter; on success the Status turns Active, otherwise Error. - Map your metrics under Field Mappings, then create a Sync Run with direction Push and a Period, and start it. Data values move to the instance via
/api/dataValueSets.
Data elements & mapping
A Data Element describes one reportable quantity. Its Value Type mirrors DHIS2 (Number, Integer, Positive Integer, Percentage, Text, Boolean, Date, Coordinate and so on, defaulting to Integer) and its Aggregation Type says how DHIS2 combines values (Sum, Average, Count, Min, Max, None, Custom). The Domain Type is Aggregate or Tracker, and an Indicator Group ties it to a national return such as MoH 731 (HIV/ART), 705-A/B (morbidity), 710 (vaccination), 711 (service workload), 717 (family planning), 745 (mortality), DATIM / PEPFAR MER, or IDSR weekly / monthly.
A Field Mapping links a platform figure to a data element. Its Local Aggregation chooses how the source is summarised; when the aggregation is not a simple count, the Local Field names the value to sum or average.
Periods & org-units
DHIS2 keys every value by period and org-unit. The Period on a data value and on a sync run follows DHIS2 period notation (for example a monthly period like 202406). The Org Unit is the facility’s node in the national hierarchy; set a default on the instance so pushes are stamped correctly. A data value is unique per instance, org-unit, data element, period and category-option-combo, which prevents accidental double reporting.
| Period type | Submission cadence | Typical use |
|---|---|---|
| Daily | Every day | High-frequency surveillance counts. |
| Weekly | Each epi week | IDSR weekly disease surveillance. |
| Monthly | Each calendar month | The default; most routine HMIS returns. |
| Quarterly | Every three months | Programme indicators reported quarterly. |
| SixMonthly | Twice a year | Semi-annual programme reviews. |
| Yearly | Once a year | Annual facility returns. |
| FinancialOct / FinancialJul / FinancialApr | Financial year (Oct / Jul / Apr start) | Returns aligned to a fiscal calendar. |
Org-units form a hierarchy keyed by a DHIS2 UID, with a level indicating where each sits: 1 = country, 2 = province, 3 = county / zone, 4 = district, 5 = facility. Each org-unit can be linked to a local facility record so activity maps to the right reporting unit automatically.
Indicator groups
Every data element is tagged with the national report it feeds, so you can build a data set by picking a group rather than hunting individual elements.
| Group | Covers |
|---|---|
| MoH 731 | HIV / ART |
| MoH 705-A / 705-B | Under-5 and over-5 morbidity |
| MoH 710 | Vaccination |
| MoH 711 | Service workload |
| MoH 717 | Family planning |
| MoH 745 | Mortality |
| DATIM / PEPFAR MER | PEPFAR monitoring, evaluation & reporting |
| IDSR Weekly / Monthly | Integrated disease surveillance & response |
| HR / Staffing, Laboratory KPI, Finance | Operational support returns |
Data-value & sync states
| Data-value storage status | Meaning |
|---|---|
| Local only | Calculated, not yet queued. |
| Queued for push | Selected for the next sync run. |
| Pushed to DHIS2 | Sent in a sync run. |
| Confirmed by DHIS2 | The server import response accepted it. |
| Push Error | Rejected; see the error message. |
| Imported from DHIS2 | Pulled down from the server. |
A Sync Run carries a Direction (Push, local → DHIS2) and a status of Queued, Running, Success, Partial Success, Failed or Cancelled. The instance records Last Push At and Last Pull At timestamps.
Instance field reference
| Field | Meaning | Required |
|---|---|---|
| Name / Code | Label and unique key. | Yes (code unique) |
| Base URL / API version | The DHIS2 server root and API major version. | Yes |
| Auth Type | HTTP Basic, Personal Access Token or OAuth2 (PKCE). | Yes |
| Username / Password / PAT Token | Credentials per auth type. | As per auth |
| Purpose | National HMIS, DATIM/PEPFAR, Ministry Internal, Research, Partner Org or Test/Sandbox. | Yes |
| Country Code | ISO-3166 alpha-2 (KE, NG, ZA, UG, TZ, RW…). | No |
| Default Reporting Org-Unit / Facility | The org-unit pushes are stamped with and the local facility mapped. | Recommended |
| Status | Active, Disabled or Error. | Yes |
Roles & access
- DHIS2 Viewer — read instances, mappings, data values and sync runs.
- DHIS2 Operator — queue figures and run syncs.
- DHIS2 Administrator — configure instances, data elements and mappings.
MOH reporting
Because data elements can be grouped under an indicator group, the same engine feeds the standard ministry returns — for instance the MoH 711 Returns available under HMS Core → Clinical → Reports — while DHIS2 push delivers the aggregate figures to the national server. Align your data-element Indicator Group values with the return your facility submits.
Troubleshooting
| Symptom | Likely cause & fix |
|---|---|
| Test Connection returns Error | Wrong base URL, API version or credentials; the chatter shows the HTTP status returned by /api/system/info. |
| Sync run reports Partial Success | Some values were rejected; open the data values with status Push Error and read the message. |
| Nothing to push | No data values matched the filter; confirm figures are Queued for push and the period matches. |
| Duplicate value error | The same instance / org-unit / element / period / combo already exists; adjust the period or combo. |
Related
Automated MoH 731 → DHIS2
The HIV/ART MoH 731 report can stage its indicators as DHIS2 data values and push them to the national instance via the existing sync engine. On a MoH 731 report use Stage to DHIS2 to build the data values for the period, then Stage & Push to transmit; a monthly cron can do this automatically. Each indicator is mapped to its DHIS2 data element (HTC tested/positive, ART new/current, viral-load suppressed) for the facility’s org unit. Live transmission needs the instance credentials and the facility’s DHIS2 org-unit UID configured.