Skip to content

Reference & Data Model

Freshness: recalculation, snapshots, trends

KPIs calculated by the server are updated in the background after every data change; this section describes when and with what delay.

KPIs calculated by the server run through a fixed chain:

Change to a record (e.g. task → completed)
↓
Delta: Which KPIs does the change affect? What changes in the value?
↓ (subtract the old record's contribution, add the new one's)
Recalculation: carry the affected KPI's value forward per scope
↓ (project → program → portfolio → organization, cascaded)
Stored value (kpi_value) → distributed to all open views
  1. Change. Every change to a table that enters a KPI (tasks, cost occurrences, risks, earnings, budgets, efforts, gate criteria, milestones, issues, projects, programs, portfolios) produces a change event.
  2. Delta. The server determines which KPIs use the table and derives from that how the value changes: a counter goes up or down by 1, a sum by the amount. Filters (state, phase, deleted, archived) are evaluated on the old and the new state of the record; a deleted or archived record no longer contributes.
  3. Recalculation. If the change cannot be expressed as a simple delta, the KPI is completely recalculated for the affected scope. This applies, among others, to KPIs with a date reference “today” (Earned Value), to minimum/maximum, to multi-level assignments (milestones and gate criteria via segments, efforts via tasks) and to changes to master fields of the project itself (budget goal, benefit, dates).
  4. Cascade. If a project value changes, the dependent program, portfolio and organization values are updated (see “Dependencies”).
  5. Stored value. The new value is written only if it has changed. The timestamp of the value therefore means “last value change”, not “last check”.
  • Normal case: a value appears a few seconds after the change in all open scoreboards. There is no refresh button.
  • Freshness budget 60 seconds: if a view requests a stored value that is older than 60 seconds, the server recalculates it live on read. If the result is the same value, nothing is written. An unchanged value stays correct, but costs a live calculation on every read after the budget has expired.
  • Short-term cache: within a server process, responses are cached for up to 30 seconds (stored values) or 5 seconds (live evaluations).
  • First sighting: for a scope that has never been calculated (new project, new organization), the value is initially empty („—“ or „Noch keine Daten“). Opening the view triggers the calculation; alternatively a background run creates missing values every 6 hours.
  • Earned Value: the Earned Value KPIs depend on the calendar day and are additionally recalculated every 5 minutes, but only for scopes that have been calculated at least once.
  • Reconciliation: every 6 hours the server checks a portion of the stored values against a complete recalculation and corrects discrepancies (25 scopes per run, oldest first). A discrepancy that arose from an incompletely processed delta is fixed there at the latest.
  • Snapshot. For every KPI calculated by the server, the background service stores a copy of the value per calendar day (UTC) as soon as it is first calculated or changed on that day. Snapshots serve exclusively for the change versus the previous day („Wert-Änderung in %“ = (current − snapshot) ÷ |snapshot| × 100, basis = most recent snapshot before today). This change is currently evaluated only by individual KPI cards, not by the scoreboards. Snapshots are not cleaned up.
  • Trend. Two KPIs additionally provide a monthly history: „Gewinn“ (profit) at project level and „Gesamtgewinn“ (total profit) of the organization (card „Trends“). The history groups earning and cost occurrences by month of the occurrence date (occurred_at); the values are per month, not cumulative. Back-dated bookings move into the correct month. Rollups (program, portfolio) have no trend.
  • Breakdowns (pie, bar, tree, for example „Aufgaben nach Status“) are always calculated live and not stored.

KPIs build on each other. The server derives from every definition which tables and which other KPIs it needs, and on a change updates all dependent values. The most important chains:

Project → Program → Portfolio / Organization
Profit → Profit (program) → Profit (portfolio)
Actual costs → Actual costs (portfolio)
Business value → Business portfolio value
Working capital (budget goal) → Working capital (portfolio)
Risk exposure → Risk exposure (program) → Risk exposure (portfolio)
Budget deviation (budget goal) → Budget deviation (program)
Open tasks → Open tasks (program)
Effort (estimated) → Effort (program)
Progress → Ø progress (program) → Ø progress (portfolio, organization)
SPI / Value CPI (per project) → SPI / Value CPI (program) → SPI / Value CPI (portfolio)

A rollup is formed from the stored values of the child projects. Child projects that do not yet have a stored value are missing from the rollup until they have been calculated for the first time. If a project changes program or portfolio, its membership in the rollup is moved.

  • Not computable (division by 0, missing baseline): value 0; ratio tiles show „—“.
  • Missing date (for example „Verzug“ (delay) without a target end): no value; the tile stays empty instead of 0.
  • Processing error on a scope: the scope is retried after 5 minutes; other scopes continue.
  • Faulty change event: is discarded after several delivery attempts; the next reconciliation (6 hours) corrects the value.
  • Organization without a service account: is skipped until the service account exists (see Service accounts).
  • Deleted project: values are no longer refreshed. Archiving is not deleting; archived projects remain included in many rollups (see Overview).
  • Changed definition: every KPI carries a definition version. If the product changes the formula, the value is rewritten on the next read or reconciliation; a reader does not check the version, the freshness budget takes on that role.

KPI recalculation · Earned Value · Guides › Scoreboard & KPI tiles