feat: support program-stage data element values in TE aggregate analytics [DHIS2-21763]

[luciano-fiandesio]

Summary

Extends the tracked-entity aggregate endpoint /api/analytics/trackedEntities/aggregate/{trackedEntityType} so the value parameter can be a program-stage data element (an event value), not just a tracked-entity attribute.

Previously value resolved only to a numeric tracked-entity attribute — a single column on the flat one-row-per-tracked-entity table analytics_te_<tet>. Event data element values live in a separate table (analytics_te_event_<tet>) with many rows per tracked entity (one per event), so they could not be aggregated. This PR reduces each tracked entity's events for the stage to one chosen event, joins it back, and aggregates it — giving correct per-tracked-entity results.

value now accepts programUid.programStageUid.dataElementUid (with an optional stage offset), in addition to the existing bare attribute UID.

What this enables

• Average birth weight per org unit — from the Birth stage of the Child Programme.
• Sum / min / max / count of any numeric event data element, grouped by org unit and/or tracked-entity attributes (e.g. total doses administered per org unit; min/max measurement per district).
• Average birth weight per org unit and gender — the event value combined with an attribute group-by key.
• Count of tracked entities that have a recorded measurement per org unit — aggregationType=COUNT over the data element counts non-null values (one per tracked entity), not events.
• Value from a chosen visit — the stage offset picks which occurrence to read: [0] latest (default), [-1] the visit before, [1] the first.

Example queries

# Average latest birth weight (Child Programme, Birth stage) per org unit
GET /api/analytics/trackedEntities/aggregate/nEenWmSyUEp
    ?dimension=ou:QII5GqfDfO3;DiszpKrYNg8
    &value=IpHINAT79UW.A03MvHHogjR.UXz7xuGCEhU
    &aggregationType=AVERAGE

# Sum / min / max of the same value per org unit — swap aggregationType=SUM|MIN|MAX

# Average birth weight per org unit AND gender (attribute group-by key)
GET .../aggregate/nEenWmSyUEp
    ?dimension=ou:QII5GqfDfO3;DiszpKrYNg8,cejWyOfXge6
    &value=IpHINAT79UW.A03MvHHogjR.UXz7xuGCEhU&aggregationType=AVERAGE

# Average birth weight per org unit, filtered to Female (WHERE, not a group-by column)
GET .../aggregate/nEenWmSyUEp
    ?dimension=ou:QII5GqfDfO3;DiszpKrYNg8
    &value=IpHINAT79UW.A03MvHHogjR.UXz7xuGCEhU&aggregationType=AVERAGE
    &filter=cejWyOfXge6:IN:Female

# COUNT of tracked entities with a non-null value per org unit
GET .../aggregate/nEenWmSyUEp?dimension=ou:...&value=<prg.stage.de>&aggregationType=COUNT

# The first recorded value instead of the latest (stage offset)
GET .../aggregate/nEenWmSyUEp?dimension=ou:...&value=<prg>.<stage>[1].<de>&aggregationType=AVERAGE

The response is the same grid shape as the existing aggregate endpoint: one column per grouped dimension (carrying the dimension-item UID) plus a trailing numeric value column; grouped org-unit UIDs resolve to names via metaData.items.

Generated SQL

Aggregating a data element requires reducing each tracked entity's events for the stage to a single chosen event before joining, otherwise the join would match every event and the aggregation would count events instead of tracked entities.

select t_1."ou",
       avg((ev."eventdatavalues" -> 'UXz7xuGCEhU' ->> 'value')::DECIMAL) as "value"
from analytics_te_nEenWmSyUEp t_1
left join (select trackedentity, eventdatavalues
           from (select trackedentity, eventdatavalues,
                        row_number() over (partition by trackedentity
                                           order by occurreddate desc) as rn
                 from analytics_te_event_nEenWmSyUEp
                 where programstage = 'A03MvHHogjR'
                   and jsonb_exists(eventdatavalues, 'UXz7xuGCEhU')
                   and status != 'SCHEDULE') e
           where rn = 1) ev on ev.trackedentity = t_1.trackedentity
group by t_1."ou"

• The inner row_number() over (partition by trackedentity order by occurreddate <dir>) + rn = <offset> selects one event per tracked entity (default: the latest event that carries the data element).
• jsonb_exists(eventdatavalues, '<de>') restricts to events that actually have the value (used instead of the ? operator, which NamedParameterJdbcTemplate would misparse as a bind placeholder).
• status != 'SCHEDULE' excludes scheduled events (which have no occurreddate), matching the row-level query.
• The value is aggregated with the per-data-element PostgreSQL cast; COUNT counts non-null values.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
1 Accepted issue

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud