PCA - Programs Management
The Program Configuration App (PCA) provides a centralized dashboard for creating, managing, and configuring DHIS2 programs. From the home screen you can search and filter existing programs, review their status at a glance, and take actions such as editing, sharing, backing up, or converting programs.
Version note: This documentation reflects PCA v3.0.0+, which introduces HNQIS 3.0 support, H1→H3 program conversion, assessment data transfer, and new status indicators on program cards.
Program Types
The PCA supports the following program types in DHIS2:
Type | Description | Notes |
|---|---|---|
Event Program | Programs without registration that track discrete events. |
|
Tracker Program | Programs with tracked entity registration; support Tracked Entity Types and Attributes. |
|
HNQIS 2.0 TO BE REMOVED | Health facility quality improvement programs using the HNQIS 2.0 framework. | Requires HNQIS Framework metadata to be installed on the server. |
HNQIS 3.0 NEW in v3.0.0 | Modern HNQIS framework programs, successor to HNQIS 2.0 with an improved structure and feedback rules. | Requires updated HNQIS Framework metadata package on the server. |
HNQIS 1.X (Legacy) | Legacy HNQIS programs; mostly read-only in PCA. Can be converted to HNQIS 3.0 via the Convert action. | New creation is not available; existing programs can be migrated. |
Programs Home Screen
The home screen displays a paginated, searchable list of all programs in your DHIS2 instance. Each program is shown as a card with key information and quick-access actions.
Searching and Filtering
Use the search bar at the top of the list to filter programs by UID, Name, Short Name, or Code. Searches are case-insensitive and match partial strings. Press Enter or click the Search button to apply the filter. Click Clear to reset the search and return to the first page.
Pagination
The list is paginated with configurable page sizes: 5, 10, 15, 20, 25, 50, or 100 programs per page (default: 10). Your chosen page size and current page position are automatically saved and restored across sessions.
Program Card Details
Each card in the list displays:
Program Icon & Color — Customizable visual identifier set when creating or editing the program.
Program Name — Full name (truncated with a tooltip on overflow).
Program Type Badge — Color-coded label (e.g., TRACKER, EVENT, HNQIS 2.0, HNQIS 3.0).
Stage Count — Number of Program Stages configured for the program.
Info Popover — Click the info icon to view and copy the Program ID, Name, Short Name, and Code to your clipboard.
Status and Warning Indicators
Program cards display warning badges when issues require attention. The table below describes each badge and the action needed to resolve it.
Badge | Color | Meaning | Action Required |
|---|---|---|---|
Important upgrade required | Info | The HNQIS program was built with a deprecated PCA version (prior to v2.0.6) and will not function correctly. | Open the program and run Set Up Program again to apply updated logic. |
Build version outdated | Info | The program's logic was built with an older PCA version and may be missing bug fixes or new features. | Run Set Up Program (HNQIS) or Build Program Rules (Event/Tracker) to update. |
Build logic not yet created | Info | The program has never had its logic built (no build version is recorded). | Run Build Program Rules to generate the program's logic for the first time. |
Missing data element prefix | Info | No Data Element Prefix is configured for this program. | Edit the program and add a prefix in the Basic Settings step. |
HNQIS Framework access restricted | Info | The program requires an HNQIS metadata package version that is not installed on the server. | Go to Settings → HNQIS Framework Status to review and install the required metadata package. |
Programs with an access restriction are displayed at reduced opacity and cannot be opened until the issue is resolved.
Program Actions
Each program card has an action menu (⋮) with options that vary by program type.
Available for All Program Types
Edit Program — Open the multi-step configuration wizard to modify settings.
Sharing Settings — Configure user and group access permissions for the program and its related metadata objects.
Assign Organisation Units — Define which Organisation Units have access to the program.
Export JSON Metadata — Download the complete program metadata as a JSON file for local backup or migration.
Backup Program — Create a restore point stored server-side.
Restore Program — Roll back the program to a previously saved server backup.
Additional Actions for HNQIS Programs
Convert to Modern HNQIS Program — Converts a legacy HNQIS 1.X program to the modern HNQIS 3.0 format. Only available when the server's HNQIS framework metadata is ready for conversion.
Transfer Assessment Data to Modern HNQIS — Migrates historical assessment data from a legacy HNQIS program to its converted HNQIS 3.0 counterpart.
Delete Program is intentionally disabled in the PCA as it will be supported at a later release. Programs must be deleted directly from the DHIS2 Maintenance app.
Creating or Editing a Program
Click Add Program on the home screen, or Edit Program from a card's action menu, to open the configuration wizard. The wizard is non-linear — you can click any step heading to jump directly to it.
Step 1 — Basic Settings
Program Type (required) — Select Tracker, Event, HNQIS 2.0, or HNQIS 3.0. Locked on existing programs except during an HNQIS upgrade flow. HNQIS options are unavailable if the required framework metadata is not installed.
Data Element Prefix (required, non-HNQIS) — Up to 25 characters; applied to all Data Elements associated with the program during setup.
Program Name (required) — Up to 230 characters.
Program Short Name (required) — Up to 50 characters.
Program Code (optional) — Up to 50 characters.
Icon & Color (Tracker and Event programs) — Choose a DHIS2 icon and a custom color to visually identify the program in the list.
Tracked Entity Type (Tracker programs only) — Select the Tracked Entity Type for the program from an autocomplete list.
Step 2 — Framework / Program Settings
HNQIS programs: Configure the Health Area, settings reference, and other framework-specific options.
Event / Tracker programs: Configure enrollment and incident dates, expiry rules, feature type (point, polygon, none), category combo, and other standard DHIS2 program settings.
Step 3 — Tracked Entity Attributes
Tracker programs only. Select the Tracked Entity Attributes to include in the program and configure per-attribute display, searchability, and sort order settings.
Field validation runs in real time. Steps with unresolved errors are visually highlighted in the step navigator when the form is submitted so you can quickly identify and fix issues.
Global Settings
The Settings menu (gear icon, top-right of the home screen) provides application-level options:
HNQIS Framework Status — Review the HNQIS metadata packages installed on the server and their version compatibility. Use this view to diagnose programs showing the "Access Restricted" badge.
About PCA — View the current application version and build information.
Related Documentation
For step-by-step instructions on adding specific program types, see:
How to add a new Tracker Program — Click Here
How to add a new Event Program — Click Here
How to add a new HNQIS Framework Program — Click Here
Previous Documentation (October 2023)
The content below is preserved from the original version of this page.
You are provided with a simple-to-navigate and easy-to-use dashboard from which you can quickly create and update Programs as needed.
In the DHIS2 instance you're using, by using the PCA there are three main types of programs you can work on: Event Programs, Tracker Programs and HNQIS 2.0 Programs.
This documentation offers comprehensive, detailed instructions for working with these types of Programs. Click below to access full details on how to add a new Programs:
How to add a new Tracker Program - Click Here
How to add a new Event Program - Click Here
How to add a new HNQIS 2.0 Program - Click Here