Skip to content

Program rollup KPIs

A program groups several related projects under one PM. The Program Settings → Rollup KPIs page controls two things about how those projects’ signals combine at the program boundary:

  1. Which KPIs appear on the program overview — a per-KPI on/off list.
  2. How project health aggregates into the single program health dot — one program-wide policy.

Open it at Program → Settings → Rollup KPIs. The design and rationale are recorded in ADR-0169: Program rollup KPIs configuration.

This is intra-program only. A program rolls up its own projects; there is no cross-program aggregation — that would be portfolio scope, which is an Enterprise concern.

ActionMinimum role
View the rollup configProgram Viewer
Change KPIs or the aggregation policyProgram Manager

A program Viewer sees the page in read-only mode (a “Read-only” badge replaces the controls). Only a Program Manager or above can change the configuration.

Ten KPIs can be enabled. The page groups them into three sections for scannability — the grouping is presentational only; the program stores a flat list of the enabled identifiers.

KPIIdentifierWhat it shows
Schedule healthschedule_healthEach project’s schedule performance band (the SPI proxy), combined by the aggregation policy. The same value as the program health dot
Schedule variance (SV)schedule_varianceEach project’s mean lateness of completed baselined tasks, in days, combined by the aggregation policy (positive = late)
Baseline variancebaseline_varianceEach project’s forecast finish minus its active-baseline finish, in days, combined by the aggregation policy (positive = later than the baseline)
Critical task countcritical_tasksIncomplete tasks on the critical path, summed across the program’s projects
Milestone healthmilestone_healthEach project’s milestone band (critical when an open milestone’s forecast finish has passed, at risk when one is due within 7 days), combined by the aggregation policy
KPIIdentifierWhat it shows
At-risk tasksat_risk_tasksIncomplete tasks with 5 or fewer working days of float, summed across the program’s projects
Risk scorerisk_scoreProbability × impact of every open or mitigating risk, summed across the program’s projects
P80 completion datep80_completionThe latest P80 finish among the projects’ own Monte Carlo forecasts

The exact definition of each KPI, and what the API returns when one cannot be computed, are on the metric vocabulary page. The rollup response carries the same sentences in its definitions map.

KPIIdentifierWhat it shows
Cost variance (CV)cost_varianceEarned value minus actual cost, summed across the program’s projects (negative = over budget)
Budget utilizationbudget_utilizationTotal actual cost ÷ total budget across the program’s projects, a ratio of sums, not an average of project ratios. It is spend against budget, not a cost performance index (CPI)

The cost KPIs carry a value only for someone who is Program Manager or Owner on the program and Project Manager or Owner on every project in it. A program role does not reach a project’s budget. Everyone else, including a program Scheduler, Member or Viewer, sees them as Restricted to managers of every project (cost_restricted). They are unavailable, with a reason that names what is missing, when any project in the program has no budget (no_budget, with projects_without_budget), or when anyone who logged time on a project or is assigned to one of its tasks has no rate (missing_rates, with missing_rate_count). See When a figure cannot be computed.

Only enabled KPIs appear on the program overview and its rollup tiles. KPI toggles save optimistically — the switch flips immediately, and rapid changes are batched into a single save.

A KPI with no backing data source is shown but locked in the picker. Its switch cannot be turned on — enabling one would save a KPI that could never render a value. Each row states why, and GET /api/v1/programs/{id}/rollup-config/ returns the same set as unavailable_kpis (an identifier → reason-code map) so any API client can render the same explanation instead of hard-coding the list. The map is empty once every KPI has a source.

A KPI that is already enabled — because it was switched on earlier, or because the methodology defaults below seeded it — stays switchable off so you can clear it. Until you do, the overview shows a dash with the reason rather than a fabricated number: GET /rollup/ returns {"available": false, "reason": "..."} for it.

An enabled KPI that has a source but no data yet (no baseline for the variances, no forecast for P80 completion) keeps its place in the response with a null value, or unknown for a band, and a reason saying what is missing.

The methodology defaults deliberately still seed these KPIs where they fit the methodology. That is forward-looking rather than an oversight: the intent (“this program should show cost variance”) is recorded now, and the tile starts rendering on its own once the backing data lands — no settings change and no migration.

The KPI set is deliberately closed: the API rejects unknown identifiers rather than silently dropping them. Three KPIs that touched team-boundary or aggregation-correctness concerns (team velocity, scope-change count, resource utilization) were excluded during design review — see ADR-0169 for the reasoning.

A program does not start blank. When a program is created, its enabled-KPI list is seeded from the program’s methodology (Waterfall, Agile, or Hybrid), so a new program is useful on day one without manual setup. Existing programs were seeded the same way when the feature shipped.

MethodologyDefault enabled KPIsDefault policy
WaterfallSchedule health, Baseline variance, Critical task count, Milestone health, Budget utilization, Cost varianceWorst-case
AgileMilestone health, P80 completion date, At-risk tasks, Risk scoreWorst-case
HybridThe union of the Waterfall and Agile sets (de-duplicated)Worst-case

Defaults are a starting point. Once seeded, the config is yours: changing the program’s methodology later does not re-seed or overwrite your choices.

The aggregation policy decides how the individual project health signals combine into the one program health dot shown on the overview. That dot is the rollup of each project’s schedule performance band, the same value as the Schedule health KPI; it is not a rollup of the project health chips. It is a single program-wide choice (a radio group), not a per-KPI setting. Because it changes what executives see at a glance, this control uses an explicit Save with an “Unsaved changes” prompt rather than saving on every click.

PolicyIdentifierHow project health combines
Worst-case (recommended, default)worstProgram health equals the worst health across all projects. One critical project makes the program critical.
AverageaverageNumeric average of project health scores. Dilutes a single critical project.
Budget-weightedweighted_by_budgetEach project is weighted by its budget. If any project has no budget, the rollup uses the average instead and reports policy_available: false with policy_unavailable_reason: "no_budget". The weighting is applied only for someone who is Program Manager or above on the program and Project Manager or above on every project in it, because a weighted figure reveals how the budgets compare. Everyone else gets the average with policy_unavailable_reason: "cost_restricted", whether or not any budget is set.
Task-weightedtask_weightedProjects with more tasks carry proportionally more weight in the average.

worst is the default and the recommended choice for most programs because it never lets a single critical project hide behind healthier ones. The weighted policies exist for client-facing rollups where a small fit-out should not drag down a large shell-and-core program. The chosen policy applies uniformly to every enabled KPI — there is no per-KPI policy override.

Why are some KPI changes instant but the policy needs a Save button? KPI toggles are low-stakes display preferences, so they save optimistically. The aggregation policy changes the headline health signal executives read, so it uses an explicit Save to avoid silent flips.

I enabled a KPI but no value shows on the overview. The settings page persists which KPIs are enabled for display. The rollup computation that produces the actual values is a separate part of the program overview; an enabled KPI with no underlying data (for example, no saved baseline for variance KPIs) will not render a value.

Does changing the program methodology reset my KPIs? No. Methodology seeds the defaults only at creation. After that the config is user-owned and is never auto-recomputed.

Can I roll up across multiple programs? No. Rollup is intra-program only. Cross-program and portfolio aggregation is an Enterprise capability outside the scope of this page.

What is the API behind this page? GET and PATCH /api/v1/programs/{program_id}/rollup-config/, returning enabled_kpis (a list of identifiers) and aggregation_policy. Reads require program Viewer; writes require Program Manager or above. Every change is captured in the program’s history for audit.