Skip to main content

DHIS2 interoperability

What it does​

The DHIS2 module lets operators map platform report columns to DHIS2 data elements, map UHP programmes to DHIS2 tracker metadata, push aggregate figures and programme tracker exports to configured DHIS2 targets, review import conflicts, and manage unattended push schedules.

Who can see it​

The DHIS2 section appears for anybody holding the module's read permissions — dhis2.status.read, dhis2.mapping.read and dhis2.push.read — which the Facility Admin role carries by default.

The section is also subject to module activation: a tenant or facility administrator can switch the DHIS2 module off under Platform → Modules, and the whole section disappears for that scope. If DHIS2 is missing for a user who holds the permissions, check the module's activation there before looking at roles.

Where to find it​

Open DHIS2 in the admin sidebar:

  • Connection — /dhis2 — target readiness and module capabilities
  • Mappings — /dhis2/mappings — report column → data element UID
  • Programme mappings — /dhis2/programme-mappings — UHP programme → DHIS2 tracker UIDs
  • Push runs — /dhis2/push — manual aggregate and tracker push with run history
  • Schedules — /dhis2/schedules — unattended push cadence

Common tasks​

Check whether a target is configured​

  1. Go to DHIS2 → Connection.
  2. Each target shows Configured or Not configured with its base URL when ready.

Map a report column to a DHIS2 data element​

  1. Go to DHIS2 → Mappings.
  2. Choose the Target (for example national).
  3. Select the Report, Output column, and a Data element from pulled metadata.
  4. Click Create mapping.

Map a UHP programme for tracker export​

  1. Go to DHIS2 → Programme mappings.
  2. Choose the Target and UHP programme.
  3. Enter the DHIS2 program UID, tracked entity type UID, and four attribute UIDs (sex, birth year, UHP ID, enrollment identifier). Each UID is exactly 11 characters.
  4. Click Create mapping.

Push one period manually (aggregate)​

  1. Go to DHIS2 → Push runs.
  2. Under Aggregate push, choose target, period type, and optional anchor date.
  3. Click Push aggregate now.
  4. Select the run in Run history to read per-value conflicts.

Push one period manually (tracker)​

  1. Go to DHIS2 → Push runs.
  2. Under Tracker push, choose target, period type, and anchor date (required).
  3. Optionally filter to one mapped programme, or leave All mapped programmes.
  4. Click Push tracker now.
  5. Select the run — tracker runs show a Tracker badge and may report restricted exclusions.

Schedule unattended push​

  1. Go to DHIS2 → Schedules.
  2. Enter target, period type, cron expression, and time zone.
  3. Click Save schedule.

Tips & limitations​

  • Data element UIDs on the Mappings screen must be picked from metadata — do not type UIDs by hand.
  • Programme tracker UIDs have no metadata pull yet — copy them from your DHIS2 instance.
  • A Queued push is not the same as Delivered; read the run status badge.
  • DHIS2 may return HTTP 200 with per-value conflicts in the import summary — check Run detail.
  • Unconfigured targets cannot pull metadata or push; fix DHIS2_* environment variables first.