Automated Metadata Package Installation at Instance Provisioning — Now Available on YaLIM Cloud

Implementation - Implémentation
, , ,
1

Hi DHIS2 community,

We’re pleased to share a new feature we’ve shipped on YaLIM Cloud that addresses a common pain point in DHIS2 deployments: the manual, error-prone process of importing metadata packages after instance provisioning.

The Problem

After spinning up a fresh DHIS2 instance, implementers typically need to:

  1. Download a metadata package from packages.dhis2.org or GitHub
  2. Replace default UIDs (category combos, org units) with instance-specific values
  3. Handle import ordering issues (DataSets before Sections, etc.)
  4. Resolve Hibernate dependency errors on DHIS2 2.40+
  5. Strip user/sharing references that cause NullPointerExceptions

This can take hours and requires deep DHIS2 internals knowledge.

*The Solution

We’ve built an automated metadata installation pipeline that handles all of this. When creating a new DHIS2 instance on yalim.cloud, users can select an official metadata package as their “Initial Configuration.”

The system:

  1. Downloads the package from the dhis2-metadata GitHub organization (81 repos covering the full WHO Health Data Toolkit)
  2. Prepares it by replacing default UIDs (category, categoryOption, categoryCombo, categoryOptionCombo, indicatorTypes) and the <OU_ROOT_UID> placeholder with the target instance’s own values
  3. Strips source-instance artifacts: sharing properties (which reference non-existent UserGroups), userGroupAccesses, userAccesses, dataInputPeriods, and top-level users/userGroups/userRoles arrays
  4. Imports in four dependency-ordered phases to avoid DHIS2 2.40+ Hibernate errors:
    • Phase 1: Base objects (categories, dataElements, indicatorTypes, optionSets, orgUnits, etc.)
    • Phase 2: DataSets (without Sections)
    • Phase 3: Sections (which reference DataSets)
    • Phase 4: Dependent objects (indicators, visualizations, dashboards, maps, reports)
  5. Reports the outcome back to the user through the portal dashboard

Packages Currently Available

We have tested and verified the following packages:

Package Description Status
CHIS_AGG Community Health Information System (Aggregate) — malaria, immunization, maternal health, nutrition, HMIS Available
AH_EBS Event-Based Surveillance for Acute Hazards — public health emergency detection and response Available

Additional packages from the WHO Health Data Toolkit are being progressively validated and will be rolled out over the coming weeks. The full catalog includes 81 repositories covering HIV, TB, malaria, nutrition, HMIS, and more.

Technical Architecture

The feature is built on four open components:

  • dhis2-mcp — A Model Context Protocol server providing deterministic metadata import tools. The internal service API (POST /internal/v1/metadata/install) handles the prepare → multi-phase commit pipeline.
  • dhis2-portal — Customer portal with a metadata picker on the new-instance form, a background scheduler that polls for pending installs, and lifecycle management (pending → waiting → completed).
  • dhis2-operator — Kubernetes operator that provisions DHIS2 instances and exposes a Ready condition used as a gate for the metadata import.
  • GitHub Discovery — Dynamic catalog that browses the dhis2-metadata GitHub organization, lists versions/tags, and imports domain-specific sub-packages with one click.

Key Technical Decisions and lessons learned*

  • periodType kept as string: DHIS2’s metadata import API expects periodType as a string (e.g., "Monthly"), not an object reference. We validated this across DHIS2 2.40 and 2.41.
  • sharing property stripped: The sharing property on imported objects references UserGroup UIDs from the source package. On a fresh instance, these UserGroups don’t exist, causing NullPointerException in UserGroupService.getDisplayName(). Stripping sharing lets DHIS2 assign default ownership.
  • Multi-phase import with critical/non-critical phases: Only DataSets (phase 2) and Sections (phase 3) are critical. Base objects and dependent objects may fail without blocking the install — this ensures core metadata is always available even when supplementary dashboards or indicators have inter-dependency issues.
  • atomicMode=NONE: Each phase is imported with atomicMode=NONE and importStrategy=CREATE_AND_UPDATE to allow partial imports and avoid all-or-nothing failures.

Try It

Create a new DHIS2 instance at yalim.cloud and select a metadata package during the “Initial Configuration” step.

We welcome feedback from the community. If you’re deploying DHIS2 metadata packages at scale and encounter import ordering issues, we’d love to hear about your experience.

— Romain-Rolland Tohouri, YaLIM Cloud

1 Like