Projekt-KPI-Snapshots
Die Entität ProjectKpiSnapshot ermöglicht den Zugriff auf die tägliche KPI-Historie von Projekten. InLoox erfasst nächtlich einen Snapshot aller numerischen und datumsbezogenen KPIs für jedes aktive Projekt, einschließlich benutzerdefinierter Felder.
Gespeichert werden nur Tage, an denen sich ein Wert tatsächlich geändert hat. Jede Zeile gilt von ihrem EventDate bis zu ihrem ValidUntil-Datum. Das hält die Historie kompakt — ein Projekt, dessen Kosten sich drei Wochen lang nicht ändern, erzeugt eine Zeile und nicht 21. Wenn Sie für jeden einzelnen Tag einen Wert benötigen, verwenden Sie die Funktion GetSeries, die die gespeicherten Zeilen zu einer lückenlosen Tagesreihe expandiert.
Dieser Endpunkt erfordert, dass das Feature KPI Trends für den Account aktiviert ist, sowie die Benutzerberechtigung Verlaufsdaten lesen (standardmäßig aktiviert). Feldebenenrechte werden angewendet: Finanzwerte werden nur zurückgegeben, wenn der anfragende Benutzer auch Budget-Leserechte für das jeweilige Projekt besitzt.
Datenmodell
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
ProjectKpiSnapshotId | guid | Eindeutiger Bezeichner der Snapshot-Zeile. |
ProjectId | guid | Das Projekt, zu dem dieser Snapshot gehört. |
EventDate | date | Das Kalenderdatum, an dem dieser KPI-Wert erfasst wurde. |
ValidUntil | date? | Das letzte Datum, für das diese Zeile gültig ist. Null bedeutet, dass die Zeile den aktuellen Wert abbildet. |
CreatedAt | datetime | Server-Zeitstempel, wann die Zeile geschrieben wurde. |
Die Snapshot-Tabelle enthält außerdem eine Spalte pro erfasstem KPI. Alle KPI-Spalten sind dynamisch und hängen von der Projektkonfiguration ab. Verwenden Sie die Funktion GetSeries, um KPI-Werte in einem strukturierten Zeitreihenformat abzurufen.
Endpunkte
Projekt-KPI-Snapshots auflisten
/odata/ProjectKpiSnapshotGibt Snapshot-Zeilen zurück. Unterstützt OData-Abfrageoptionen ($filter, $select, $orderby, $top, $skip).
Der direkte Zugriff auf die Snapshot-Tabelle eignet sich für erweitertes Reporting. Für Standard-Trend-Diagramme empfiehlt sich die unten beschriebene Funktion GetSeries.
Funktionen
KPI-Trend-Zeitreihen für ein oder mehrere Projekte abrufen
/odata/ProjectKpiSnapshot/GetSeriesGibt tägliche KPI-Zeitreihen für bis zu 200 Projekte und bis zu 20 Felder zurück.
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
projectIds | guid[] | ✅ | Liste der Projekt-IDs, für die Trend-Zeitreihen abgerufen werden sollen. Maximal 200 Projekte pro Anfrage. |
fields | string[] | ✅ | Liste der abzurufenden KPI-Feldnamen (z. B. "TotalCostActual", "PercentComplete"). Maximal 20 Felder pro Anfrage. Unbekannte Feldnamen werden stillschweigend übersprungen. |
from | date? | — | Startdatum (inklusive) für den Zeitraum. Standardmäßig 90 Tage vor heute, wenn nicht angegeben. |
to | date? | — | Enddatum (inklusive) für den Zeitraum. Standardmäßig heute, wenn nicht angegeben. |
Die Antwort gibt einen Zeitreiheneintrag pro angeforderter Projekt- und Feldkombination zurück, mit täglichen Datenpunkten für den angeforderten Datumsbereich (Lücken werden mit dem zuletzt bekannten Wert aufgefüllt).
OData-Abfragebeispiele
GET /odata/ProjectKpiSnapshot/GetSeries?projectIds=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&fields=TotalCostActual,PercentComplete
GET /odata/ProjectKpiSnapshot/GetSeries?projectIds=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx,yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy&fields=TotalCostActual&from=2025-01-01&to=2025-12-31
GetSeries liefert dieselben Daten, die auch den Sparkline-Spalten in der Projektliste und den Trend-Widgets im Projekt-Dashboard zugrunde liegen. Der Parameter fields akzeptiert dieselben Spaltennamen, die auch im DynamicProject-Endpunkt erscheinen.