> For the complete documentation index, see [llms.txt](https://docs.oomus.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.oomus.org/integrations/dhis2.md).

# DHIS2 Guide

This guide walks you step by step through the complete configuration of the DHIS2 Tracker integration with Oomus CampaignID.

***

## Prerequisites

Before you begin, make sure you have:

| Prerequisites           | Description                                                                  |
| ----------------------- | ---------------------------------------------------------------------------- |
| DHIS2 instance          | Version 2.36 or higher, accessible from the Internet                         |
| Dedicated DHIS2 account | Read permissions (`Metadata: can view` + `Tracker: export tracked entities`) |
| Oomus permissions       | Role `programme_admin` on your Oomus CampaignID account                      |
| Oomus plan              | Regional Ops or higher for full DHIS2 integration                            |

### Creating a dedicated DHIS2 account (recommended)

It is strongly recommended to create a **dedicated DHIS2 account** for Oomus, with read-only permissions:

1. In DHIS2: Maintenance > Users > Add a user
2. Name it `oomus_sync` or similar
3. Assign the role `Metadata viewer` + `Tracker program read`
4. Note the username and password

Oomus CampaignID never modifies **ever** DHIS2 data. The read-only account guarantees the integrity of your data.

***

## Supported DHIS2 versions

| Version | Support                         | Notes                                |
| ------- | ------------------------------- | ------------------------------------ |
| 2.36    | Supported (baseline)            | Tracker API v1                       |
| 2.37    | Supported                       |                                      |
| 2.38    | Supported                       |                                      |
| 2.39    | Supported                       |                                      |
| 2.40    | Supported                       | Tracker API v2 available             |
| 2.41    | Supported (recommended)         | Best performance                     |
| 2.42+   | Compatibility checked regularly | Contact support if there is an issue |

***

## Step 1 — Configure the connection

### Via the Oomus CampaignID interface

1. From the Dashboard, navigate to **Integrations > DHIS2**
2. Click **"Add a DHIS2 connection"**
3. Fill in the fields:
   * **URL** : `https://dhis2.sante.gov.sn` (no trailing slash)
   * **Username** : your dedicated DHIS2 account
   * **Password** : account password
4. Click **"Test connection"**
5. If the test succeeds, click **"Save"**

### Via the API

```bash
# Configure the connection
curl -X POST https://api.oomus.health/dhis2/config \
  -H "Authorization: Bearer <YOUR_TOKEN>" \\
  -H "Content-Type: application/json" \\
  -d '{
    "url": "https://dhis2.sante.gov.sn",
    "username": "oomus_sync",
    "password": "DHIS2Password"
  }'

# Test the connection
curl -X POST https://api.oomus.health/dhis2/test-connection \
  -H "Authorization: Bearer <YOUR_TOKEN>" \\
  -H "Content-Type: application/json" \\
  -d '{
    "url": "https://dhis2.sante.gov.sn",
    "username": "oomus_sync",
    "password": "DHIS2Password"
  }'
```

***

## Step 2 — Select a DHIS2 program

1. In the Oomus interface, click **"Select a DHIS2 program"**
2. The list of accessible Tracker programs is displayed automatically
3. Select the program to integrate
4. Click **"Preview enrollments"** to verify the available data

***

## Step 3 — Attribute mapping

Attribute mapping is the most important step. It determines which DHIS2 data will appear on the generated cards.

### How to identify DHIS2 attribute codes

In your DHIS2 interface:

1. Go to **Maintenance > Programs > \[Your Program]**
2. Select the tab **Tracked entity attributes (TEA)**
3. For each attribute, note the **Code** (Code column)

Example of common codes (vary depending on your instance):

| DHIS2 code     | Meaning       |
| -------------- | ------------- |
| `MMD_PER_NAM`  | First name    |
| `MMD_PER_LST`  | Last name     |
| `MMD_PER_DOB`  | Date of birth |
| `MMD_PER_SEX`  | Sex           |
| `MMD_PER_ADR`  | Address       |
| `PHONE_NUMBER` | Phone number  |

### Available Oomus card fields for mapping

| Oomus card field  | Description            |
| ----------------- | ---------------------- |
| `first_name`      | Beneficiary first name |
| `last_name`       | Last name              |
| `date_of_birth`   | Date of birth          |
| `gender`          | Sex (M/F/U)            |
| `beneficiary_id`  | Beneficiary local ID   |
| `phone_number`    | Phone number           |
| `health_center`   | Health center name     |
| `org_unit`        | Organisation unit      |
| `enrollment_date` | Enrollment date        |
| `zone`            | Geographic zone        |

### Mapping configuration

```bash
curl -X POST https://api.oomus.health/dhis2/assign-codes \
  -H "Authorization: Bearer <YOUR_TOKEN>" \\
  -H "Content-Type: application/json" \\
  -d '{
    "programme_uid": "P3jJH5Tu5VC",
    "mappings": [
      {"dhis2_attribute_code": "MMD_PER_NAM", "card_field": "first_name"},
      {"dhis2_attribute_code": "MMD_PER_LST", "card_field": "last_name"},
      {"dhis2_attribute_code": "MMD_PER_DOB", "card_field": "date_of_birth"},
      {"dhis2_attribute_code": "MMD_PER_SEX", "card_field": "gender"},
      {"dhis2_attribute_display_name": "Phone Number", "card_field": "phone_number"}
    ]
  }'
```

***

## Step 4 — MPI resolution

During each synchronization, the MPI engine is invoked automatically. Here is how to understand the results:

### Synchronization indicators

After each synchronization, the following metrics are available:

| Indicator            | Description                            |
| -------------------- | -------------------------------------- |
| `mpi_resolved`       | Enrollments linked to an existing MPI  |
| `mpi_created`        | New MPI identifiers created            |
| `mpi_pending_review` | Probable duplicates pending review     |
| `sensitive_blocked`  | Attributes blocked by the AI guardrail |

### Handle pending duplicates

Go to **MPI Dashboard > Duplicate review** to process pending identities (score 0.75–0.94).

***

## Step 5 — Configure automatic synchronization

### Choose the interval

| Interval | Recommended use case                            |
| -------- | ----------------------------------------------- |
| 10 min   | High-traffic clinic, very fresh data required   |
| 15 min   | Active clinic, vaccination campaign in progress |
| 30 min   | Standard use, regular programs                  |
| 60 min   | Low-volume program, resource savings            |
| 180 min  | Light synchronization, seasonal programs        |

```bash
curl -X POST https://api.oomus.health/dhis2/sync-schedule \
  -H "Authorization: Bearer <YOUR_TOKEN>" \\
  -H "Content-Type: application/json" \\
  -d '{
    "programme_uid": "P3jJH5Tu5VC",
    "interval_minutes": 30,
    "enabled": true,
    "auto_generate_cards": false
  }'
```

***

## Step 6 — Generate cards

### Preview before mass generation

Before launching a generation on thousands of beneficiaries, preview the card of a real enrollment:

1. In the Oomus DHIS2 interface, select an enrollment
2. Click **"PNG card preview"**
3. Check that all fields are correctly mapped and displayed

### Start generation

```bash
curl -X POST https://api.oomus.health/dhis2/generate-cards \
  -H "Authorization: Bearer <YOUR_TOKEN>" \\
  -H "Content-Type: application/json" \\
  -d '{
    "programme_uid": "P3jJH5Tu5VC",
    "template": "pulse",
    "dpi": 300,
    "include_mpi_id": true,
    "enrollment_filter": {
      "enrollment_date_from": "2026-01-01",
      "org_unit": "DiszpKrYNg8"
    }
  }'
```

***

## Step 7 — Distribute cards

From the **Distribution** tab of the DHIS2 view in Oomus:

1. Select the beneficiaries (individually or in groups)
2. Choose the channel: WhatsApp, SMS or Google Wallet
3. Customize the message (if applicable)
4. Click **"Send"**

Distribution logs are available in the **Distribution > Logs**.

***

## Common troubleshooting

| Issue                       | Possible cause            | Solution                                                  |
| --------------------------- | ------------------------- | --------------------------------------------------------- |
| Connection test fails (401) | Incorrect credentials     | Check the DHIS2 username and password                     |
| Connection test fails (503) | DHIS2 inaccessible        | Check that the URL is accessible from the Internet        |
| Unmapped attributes         | Incorrect attribute codes | Check the codes in DHIS2 Maintenance > Programs           |
| Synchronization blocked     | DHIS2 version < 2.36      | Update DHIS2 or contact support                           |
| Excessive duplicates        | Inconsistent DHIS2 data   | Clean up the data at the source, then reset the MPI cache |

***

## Next steps

* [DHIS2 API reference](/api-reference/dhis2.md)
* [Sovereign MPI identity](/features/mpi-sovereign-identity.md)
* [Multichannel distribution](/features/distribution.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.oomus.org/integrations/dhis2.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.