> 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/features/dhis2-integration.md). # DHIS2 Integration Oomus CampaignID integrates natively with **DHIS2 Tracker** to automatically synchronize beneficiary enrollments and generate cards directly from the data in your national health system. *** ## Connection setup ### Prerequisites * A DHIS2 instance (version 2.36 or later) accessible on the network * A DHIS2 user account with read access on the target Tracker programs * The rights `program_admin` on Oomus CampaignID ### Connection settings | Parameter | Description | Example | | ------------- | ----------------------------------------------- | ---------------------------- | | **DHIS2 URL** | Full URL of your instance | `https://dhis2.sante.gov.sn` | | **Username** | Dedicated DHIS2 account (read-only recommended) | `oomus_sync_user` | | **Password** | DHIS2 account password | (stored encrypted) | > Oomus CampaignID never writes to DHIS2. The account used must have **read-only** (`dhis2_safe` read-only guard). This protects the integrity of your DHIS2 data. ### Connection test After entering the settings, click **"Test connection"** to validate: ```bash curl -X POST https://api.oomus.health/dhis2/test-connection \\ -H "Authorization: Bearer " \\ -H "Content-Type: application/json" \ -d '{ "url": "https://dhis2.sante.gov.sn", "username": "oomus_sync_user", "password": "YourDHIS2Password" }' ``` **Response (success):** ```json { "status": "connected", "dhis2_version": "2.41.2", "server_date": "2026-05-15T09:00:00", "programmes_available": 7 } ``` *** ## Listing DHIS2 programs Once connected, retrieve the list of available Tracker programs: ```bash curl -X GET https://api.oomus.health/dhis2/programmes \\ -H "Authorization: Bearer " ``` *** ## Enrollment synchronization ### Synchronization modes | Mode | Description | | -------------------- | -------------------------------------------- | | **Manual** | On-demand trigger from the interface | | **Automatic (cron)** | Scheduled periodic synchronization | | **Webhook** | Event-based trigger in DHIS2 (if configured) | ### Synchronization cron configuration Available intervals: **10 / 15 / 30 / 60 / 180 minutes** ```bash curl -X POST https://api.oomus.health/dhis2/sync-schedule \\ -H "Authorization: Bearer " \\ -H "Content-Type: application/json" \ -d '{ "programme_uid": "P3jJH5Tu5VC", "interval_minutes": 30, "enabled": true }' ``` ### Synchronization process ``` Trigger (cron / manual) │ ▼ Retrieval of DHIS2 enrollments (since the last sync or configurable period) │ ▼ Attribute normalization │ ▼ MPI resolution (probabilistic engine) │ ▼ Sensitive data guard (AI — 7 categories) │ ▼ Updating the Oomus registry │ ▼ Trigger card generation (if configured) ``` *** ## DHIS2 attribute mapping Attribute mapping allows you to link DHIS2 fields to Oomus card fields. ### Mapping methods DHIS2 attributes can be mapped in two ways: **By attribute code** (recommended): ```json { "dhis2_attribute_code": "MMD_PER_NAM", "card_field": "first_name" } ``` **By display name (displayName)** : ```json { "dhis2_attribute_display_name": "First name", "card_field": "first_name" } ``` ### Example mapping configuration ```bash curl -X POST https://api.oomus.health/dhis2/assign-codes \\ -H "Authorization: Bearer " \\ -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" } ] }' ``` *** ## MPI resolution during synchronization For each synchronized enrollment, the MPI engine is automatically invoked: 1. **Extraction** of identity attributes (last name, first name, DOB, sex, commune) 2. **Scoring** probabilistic against the existing MPI registry 3. **Linking** automatic if score ≥ 0.95 (same MPI ID for all programs) 4. **Review queue** if score 0.75–0.94 5. **Creation** of a new MPI identifier if no match The result: each DHIS2 enrollment is linked to the corresponding sovereign MPI identity. *** ## Card generation from DHIS2 ### 10 DHIS2 templates available Oomus CampaignID offers **10** high-resolution card templates for DHIS2 data: | Template | Palette | Description | | --------------- | ------------------------ | ------------------------------------------------------------------------------------ | | `vital` | Medical blue / cyan | Essential health card, minimal fields | | `emerald` | Forest green / emerald | Intermediate card with program fields | | `pulse` | Dark navy / neon cyan | Full card with QR, MPI, and extended data | | `mothercare` | Pink / teal | Antenatal follow-up and mother-child vaccination | | `shield` | Slate / gold | Social protection and social rights | | `nomad` | Black / orange | Livestock and pastoral populations, large QR | | `aero` | Navy / amber | Enhanced vaccination and field campaigns | | `horizon` | Deep indigo / light blue | Premium horizontal gradient card | | `aurora` | Indigo / purple / pink | Specialized programs, perforated notches | | **`sovereign`** | **Dark navy / gold** | **DHIS2 Digital Pass — boarding-pass design identical to the interactive previewer** | #### Template `sovereign` — DHIS2 Digital Pass The template `sovereign` exactly reproduces the `Dhis2BoardingCard` component from the interactive previewer. It was completely redesigned in v5.9. **Output format** : Boarding Pass only — the Wallet Pass format has been removed from the OUTPUT FORMAT selector (v5.12). The Boarding Pass remains the standard format for PVC and PDF printing. * **Format** : 1011×375 px @ 300 DPI (480:178 ratio, horizontal boarding-pass) * **Header** : up to 3 logos + "DHIS2 DIGITAL PASS" (all caps) + "Identity Pass · eHealth Platform" — "Sovereign Id" badge removed * **MPI identifier** : label "MPI-ID" + fingerprint icon (8 ridges) + value in large bold white characters * **Attribute grid** : 2 columns × 2 rows (up to 4 attributes) with no overlap * **QR zone** : deep black background, frame with 4 gold brackets, "SCAN TO VERIFY", truncated TEI identifier * **Separator** : gold dashes with ornamental top/bottom diamonds * **Footer** : program name (uppercase) on the left + enrollment date on the right * **Configurable** via `SovereignCardConfig` : fields `accent_hex`, `bg_hex`, `bg_deep_hex`, `font_scale`, `max_attrs` * Navy/gold backgrounds with subtle topographic ellipses ### Real-time preview — Card Design tab Before launching generation, the **Card Design** tab shows a preview of the card in **real time** : * The preview refreshes automatically 450 ms after each change: template, color, logos, selected attributes, subtitle, title size * Works **offline from DHIS2** : representative sample data is used if no enrollment is available * Rendered at **300 DPI** via the same server engine as bulk generation * Status indicator: animated cyan (loading) → green (ready) → gray (no preview) * Click **"Refresh"** to force a manual update ### Launch generation from DHIS2 ```bash curl -X POST https://api.oomus.health/dhis2/generate-cards \\ -H "Authorization: Bearer " \\ -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" } }' ``` ### PNG preview with real data Before launching a bulk generation, preview a card with the real data from an enrollment: ```bash curl -X GET "https://api.oomus.health/dhis2/preview-card-png?enrollment_id=xyz123&template=pulse" \\ -H "Authorization: Bearer " \\ --output card_preview.png ``` *** ## Sensitive data guard (AI) Before any export to ML/analytics pipelines, the guard engine automatically analyzes DHIS2 attributes and **blocks sensitive data** according to 7 categories: | Category | Examples of blocked attributes | | ----------------- | --------------------------------------- | | **HIV/AIDS** | HIV serological status, viral load, CD4 | | **STIs** | Syphilis, gonorrhea, STI results | | **Tuberculosis** | TB status, DOT treatment, positive BK | | **Mental health** | Psychiatric diagnoses, psych treatments | | **Serological** | Sensitive serological test results | | **Biometric** | Fingerprints, iris, DNA | | **Financial** | Income, economic status, payments | These attributes are automatically excluded from analytical exports, debug logs, and AI processing — they remain present in the encrypted registry. *** ## Distribution from DHIS2 After generation, the cards can be distributed directly from the **Distribution** tab in the DHIS2 view: * **WhatsApp** : send the card image to the DHIS2 phone number * **SMS** : send a download link to the registered number * **Google Wallet** : issue an individual or bulk Google Wallet pass *** ## Supported DHIS2 versions | DHIS2 version | Support | | ------------- | ------------------------------ | | 2.36 | Supported (baseline) | | 2.37 | Supported | | 2.38 | Supported | | 2.39 | Supported | | 2.40 | Supported | | 2.41 | Supported (recommended) | | 2.42+ | Compatibility tested regularly | > For versions earlier than 2.36, contact the Oomus team for a compatibility assessment. *** ## Next steps * [DHIS2 integration guide](/integrations/dhis2.md) — Complete step-by-step guide * [API reference — DHIS2](/api-reference/dhis2.md) * [Sovereign MPI identity](/features/mpi-sovereign-identity.md) — MPI resolution * [Multichannel distribution](/features/distribution.md) — Send cards --- # 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/features/dhis2-integration.md?ask=&goal= ``` `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.