dhis2-releases

DHIS2 Version 43 Upgrade Notes

Welcome to the upgrade notes for DHIS2 version 43.

It is important to be familiar with the contents of these notes before attempting an upgrade.

:warning: Please ensure you have also read the upgrade notes from the PREVIOUS RELEASE, if upgrading from an earlier version

To help you navigate the document, here’s a detailed table of contents.

Table of Contents

• Prerequisits
• API Changes
  • Platform
  • Tracker

  • Analytics

    Prerequisits

It must pass integrity check Single events without an occurred date.

API Changes

Platform

dhis.conf changes

Renamed logging keys

The following dhis.conf logging keys have been renamed to use a consistent logging.* namespace. The old keys are no longer recognized.

Old key	New key
enable.query.logging	logging.query
slow.query.logging.threshold.time	logging.query.slow_threshold
logging.request_id.enabled	logging.session_id

logging.request_id.enabled was renamed to logging.session_id because the feature adds a hashed session ID to the logging context, not a request ID.

The method.query.logging.enabled and elapsed.time.query.logging.enabled keys have been removed.

New SQL context monitoring keys

Two new keys allow adding request context as SQL comments for query attribution:

Key	Default	Description
monitoring.sql.context	off	Prepend SQL comments with request context for query attribution
monitoring.sql.context.keys	controller,method	Controls which keys are included in SQL comments. Supported keys: controller, method, requestId, sessionId

SQL comments change the query text, which can prevent PostgreSQL prepared statement caching. Adding requestId or sessionId produces unique SQL text per request or session, which prevents caching entirely and can significantly degrade performance. Only enable those for debugging.

Analytics

New skip analytics flag (for Tracked Entity Attributes)

A new flag to skip analytics (named skipAnalytics) has been introduced in Tracker. This flag allows Tracked Entity Attributes (TEAs) to be excluded from analytics tables for reasons of security and confidentiality. This functionality is consistent with the existing behavior for Data Elements within a Program Stage. The flag is not configurable through the UI yet. So, one can enable it hitting the API directly. ie:

PUT programSection/trackedEntityAttribute/VqEFza8wbwA

{   ”id”: “VqEFza8wbwA”,   ”name”: “Unique ID”,   ”shortName”: “Unique identifier”,   ”valueType”: “TEXT”,   ”aggregationType”: “NONE”,   ”skipAnalytics”: true }

The primary goal of this enhancement is to prevent the creation of columns related to skipped dimensions during the analytics table export process. This ensures alignment with the expectations set by the new flag and maintains consistency across analytics handling.

Summarizing, the dimensions with the skip flag enabled will:

• Not appear in internal analytics endpoints.
• Be unavailable for selection in Data Visualizer, Line Listing, and any other applications that expose Data Elements or Tracked Entity Attributes to users.

This restriction ensures that skipped dimensions won’t be exported to any analytics table. This means they cannot be used or selected in any analytics application.

• The existing skip analytics flag for Program Stage Data Elements remains unchanged. It continues to function as before and is located in the same configuration area.

Support for label and displayLabel in PeriodType

This release introduces support for both label and displayLabel properties in PeriodType. At present, displayLabel simply mirrors the value of label. This allows front-end applications to begin using displayLabel immediately, minimizing future changes once displayLabel is fully implemented. Users can update the label through a PUT request. ie:

PUT api/periodTypes

{ “name”: “Daily”, “displayName”: “Daily”, “isoDuration”: “P1D”, “isoFormat”: “yyyyMMdd”, “frequencyOrder”: 1, “label”: “The new label” }

The following constraints are applied, so we keep the current integrity for periods:

• PeriodType instances cannot be created via POST requests, as they are predefined with hard-coded internal type names.
• Only the label property can be updated. All other properties remain immutable.

This ensures consistency while enabling front-end applications to adopt displayLabel without requiring structural changes later.

Tracker

As described in the docs events can be of 2 different types, tracker events and single events. We made this distinction explicit in the code and the database, so the event table was split into singleevent and trackerevent tables.

Table changes

Given the new database structure, if you run custom SQL scripts or have created SQL views, you might need to adapt to the breaking changes described in the current section.

Split tables

Original event table	Single event table	Tracker event table
event	singleevent	trackerevent
eventchangelog	singleeventchangelog	trackereventchangelog
event_notes	singleevent_notes	trackerevent_notes

Split columns

Table	Original event column	Single event column	Tracker event column
programmessage	eventid	singleeventid	trackereventid
relationshipitem	eventid	singleeventid	trackereventid
programnotificationinstance	eventid	singleeventid	trackereventid

Breaking Changes

The following changes have been made to Tracker error codes to improve accuracy and consistency:​

• Error code E1084 has been removed. Depending on the context, the system will now return the more appropriate error codes: E1007 for attributes or E1302 for data values.
• Error code E1085 has also been removed. In its place, the system will return error code E1007.​

Tracker API improvements and cleanup:

• Made program a mandatory parameter in /tracker/events endpoint.
• Made program a mandatory parameter in /tracker/enrollments endpoint.
• Removed trackedEntityType as a supported parameter in /tracker/enrollments.
• Removed deprecated ou parameter from /api/tracker/ownership/transfer. Use orgUnit instead.
• Removed the job type Tracker Search Optimization from /api/jobTypes. We introduced the new Tracker trigram index maintenance.

Change Log Configuration Update

The global changelog.tracker property in dhis.conf has been removed. Change log collection is now configured per Program and Tracked Entity Type using the new enableChangeLog property. After upgrading to v43, all Programs will have change logs enabled, and Tracked Entity Types will inherit their value from the existing allowauditlog field.