Zu Content springen
Deutsch
Anmelden
Zum Kundenportal
  • Es gibt keine Vorschläge, da das Suchfeld leer ist.

🌐 Kennzahlen (KPI) per REST API verwalten

Dieser Artikel erklärt, wie Sie Key Performance Indicators (KPIs) über die ValueStreamer REST API automatisiert erfassen, aktualisieren und verwalten können. Die Anleitung richtet sich an Entwickler und IT-Verantwortliche, die KPI-Daten regelmäßig aus Drittsystemen (z. B. ERP, MES, BI) an den ValueStreamer übermitteln möchten – einschließlich der in API v3 neu eingeführten Forecast-Funktion.

🔍 Inhalt

Voraussetzungen

  • 🔐 API-Zugangsdaten (Username + Passwort für HTTP Basic Auth)
  • 🌐 Zugriff auf eine ausführende Umgebung (z. B. Power Automate, Python, Postman, Swagger UI oder eigene Integrationslösung)
  • 🧾 UUIDs für KPI, Team und ggf. Sub-Tile/KPI-Wert (können über Meta-Endpunkte abgerufen werden)

🔑 Authentifizierung

Die Authentifizierung erfolgt über HTTP Basic Auth.

Header-Beispiel:

Authorization: Basic <Base64-encoded username:password>

ℹ️ Hinweis: Der Zugriff ist nur für Benutzer mit entsprechender API-Berechtigung möglich. ValueStreamer stellt Username und Passwort bereit – diese müssen Base64-kodiert im Authorization-Header übergeben werden.

🔗 Endpunkte im Überblick

Methode Endpunkt Beschreibung
GET /exchange/kpi Liste aller KPIs abrufen (Meta)
GET /exchange/kpi/{kpi-id} KPI-Details und Erfassungsteams abrufen (Meta)
GET /exchange/kpi-data Liste von KPI-Datensätzen abrufen
GET /exchange/kpi-data/{date}/{team-id}/{kpi-id} Einzelnen Datensatz abrufen
PUT /exchange/kpi-data/{date}/{team-id}/{kpi-id} KPI-Datensatz erstellen oder aktualisieren
DELETE /exchange/kpi-data/{date}/{team-id}/{kpi-id} KPI-Datensatz löschen

Für KPIs mit Sub-Tiles wird die UUID des Sub-Tiles als zusätzlicher Pfadparameter angehängt: /{sub-tile-id}

ℹ️ Hinweis: Ab API v3 lautet der korrekte Content-Type application/vs.v3.0+json. Bei Verwendung von v2-Headern werden neue Felder wie forecast oder adoptActualsIfPossible nicht unterstützt.

📥 KPI-Datensatz erstellen oder aktualisieren (PUT)

Beispiel-Aufruf:

PUT /exchange/kpi-data/2022-11-01/8dca904d-9134-3bb0-95b7-3f72ae3dfacf/c3ba32c2-a13a-0000-0000-000000000000

Header:

Content-Type: application/vs.v3.0+json
Authorization: Basic <base64 credentials

Body (Beispiel mit Ist- und Zielwert):

{
  "values": [
    {
      "kpiValueId": "79cf2f74-0e9c-45b5-bc4d-f437079dde7c",
      "value": 177
    },
    {
      "kpiValueId": "fd2c7750-79e1-4514-89a2-e9c103db4d6b",
      "value": 190
    }
  ]
}

✨ Tipp: Sie können auch nur einzelne Werte (z. B. nur den Istwert oder nur den Zielwert) senden – die API ergänzt oder aktualisiert bestehende Werte intelligent. Fehlende Werte werden auf Basis vorhandener historischer Daten oder mit 0 vorbelegt.

📅 Aufzeichnungsintervalle (Tag, Woche, Monat)

Im KPI-Editor legen Sie fest, ob Werte täglich, wöchentlich oder monatlich erfasst werden. Das Datumsformat ist in allen Fällen yyyy-MM-dd.

Tageserfassung (DAY) Datum direkt angeben, z. B. 2022-11-01.

Wochenerfassung (WEEK) Immer das Datum des Montags der jeweiligen Kalenderwoche angeben.

  • KW 52/2022 → 2022-12-26
  • KW 01/2023 → 2023-01-02

Monatserfassung (MONTH) Immer den ersten Tag des Monats angeben.

  • Januar 2022 → 2022-01-01
  • Dezember 2022 → 2022-12-01

ℹ️ Hinweis: Das Datumsformat yyyy-MM-dd gilt einheitlich für alle Intervalle. Ein falsches Datum (z. B. ein Mittwoch für eine Wochenerfassung) führt zu einem ungültigen Eintrag.

📝 Hinweise zum Erstellen / Aktualisieren von Datenpunkten

Beim PUT-Aufruf muss mindestens ein kpiValue übergeben werden. Je nachdem, welche Werte Sie senden, verhält sich die API wie folgt:

  1. Vollständiger Datensatz (Ist- und Zielwert): Existiert bereits ein Eintrag für die Kombination KPI + Team + Datum, wird er aktualisiert.
  2. Nur Zielwert für ein Datum in der Zukunft: Der fehlende Istwert kann in einem späteren separaten Aufruf ergänzt werden.
  3. Nicht alle Istwerte gesendet: Die API prüft, ob für die fehlenden Werte bereits Daten existieren.
    • Falls ja: bestehende Werte bleiben unverändert.
    • Falls nein: fehlende Werte werden mit 0 angelegt.
  4. Nur Istwerte, kein Zielwert: Die API prüft, ob ein Zielwert für die Kombination KPI + Team bereits vorhanden ist.
    • Falls ja: der Zielwert bleibt unverändert.
    • Falls nein: die API übernimmt den letzten bekannten Zielwert für dieses Team. Ist keiner vorhanden, wird 0 gesetzt.

⚠️ Achtung: Wenn kein Zielwert übermittelt wird und auch kein historischer Zielwert existiert, setzt die API automatisch 0. Prüfen Sie deshalb vor dem ersten Import, ob Zielwerte bereits hinterlegt sind.

🔮 Forecast-Istwerte & Übernahme (NEU in v3)

Ab API v3 unterstützt ValueStreamer die Erfassung von Forecast-Istwerten – also vorläufigen Werten für Zeiträume, die noch als Prognosezeitraum gelten.

Was ist ein Forecast-Istwert?

Ein Istwert, der für einen Prognosezeitraum übermittelt wird, wird als Forecast-Istwert (vorläufig, noch nicht übernommen) gespeichert. Sobald der Zeitraum kein Prognosezeitraum mehr ist, kann der Wert übernommen (adoptiert) werden.

Jeder Wert in der GET-Antwort enthält das neue Feld forecast (read-only):

  • true = der Wert ist ein Forecast-Istwert oder ein Forecast-Zielwert (vorläufig)
  • false = der Wert ist übernommen / endgültig

ℹ️ Hinweis: Das Feld forecast ist nur in API v3 (application/vs.v3.0+json) verfügbar. Bei älteren Content-Types wird es nicht zurückgegeben.

Was gilt als Prognosezeitraum?

Das Verhalten wird pro KPI über das Meta-Feld kpiEnteringDefaultPeriod gesteuert (abrufbar über /exchange/kpi/{kpi-id}):

Wert Bedeutung
CURRENT Nur Zeiträume strikt nach dem aktuellen Tag / der aktuellen Woche / dem aktuellen Monat gelten als Prognose. Istwerte für den laufenden Zeitraum werden sofort als endgültig gespeichert.
PREVIOUS Der aktuelle Tag / die aktuelle Woche / der aktuelle Monat gilt ebenfalls als Prognosezeitraum. Istwerte werden als Forecast-Istwerte gespeichert und müssen später übernommen werden.

ℹ️ Hinweis: kpiEnteringDefaultPeriod steuert auch die Standardanzeige im KPI-Eingabeformular der Oberfläche.

Forecast-Istwert übernehmen (adoptActualsIfPossible)

Um einen vorläufigen Forecast-Istwert zu übernehmen, setzen Sie adoptActualsIfPossible: true im PUT-Body:

{
  "values": [
    {
      "kpiValueId": "15cc7cb5-f92e-4847-8054-8bd486dbf133",
      "value": 4.0
    },
    {
      "kpiValueId": "ac1aae6e-6733-4701-9df2-0a793ab2da63",
      "value": 2.0
    }
  ],
  "adoptActualsIfPossible": true
}

Die API übernimmt den Forecast-Istwert, sobald der Bezugszeitraum kein Prognosezeitraum mehr ist. Der ursprüngliche Forecast-Wert wird zur Nachvollziehbarkeit in historicalForecastValues gespeichert.

✨ Tipp: Wenn adoptActualsIfPossible fehlt, false oder null ist, verbleiben Forecast-Istwerte im Forecast-Status – es wird kein Fehler ausgelöst.

⚠️ Achtung: Ist der Zeitraum noch ein Prognosezeitraum oder sind die Werte bereits übernommen, wird das Flag adoptActualsIfPossible stillschweigend ignoriert.

Neue Felder in der GET-Antwort (v3, read-only)

Feld Typ Bedeutung
values[].forecast Boolean true = Forecast-Istwert oder Forecast-Zielwert
historicalForecastValues[] Array Forecast-Werte vor der Übernahme (für Nachvollziehbarkeit)
historicalForecastResult Number Berechnetes Ergebnis der historischen Forecast-Werte

Beispiel-Antwort (nach Übernahme):

{
  "meta": {
    "kpiId": "bac97bbb-8abc-4230-9ef4-1a230e240138",
    "teamId": "e70ebfdd-760b-4f50-b69f-6564acb4a367",
    "subTileId": null,
    "date": "2025-07-01"
  },
  "values": [
    {
      "kpiValueId": "15cc7cb5-f92e-4847-8054-8bd486dbf133",
      "value": 3.0,
      "forecast": false
    }
  ],
  "historicalForecastValues": [
    {
      "kpiValueId": "15cc7cb5-f92e-4847-8054-8bd486dbf133",
      "value": 1.0
    }
  ],
  "result": 6.0,
  "historicalForecastResult": 2.0
}

⏱️ Hinweis: KPIs mit Einheit „Zeit"

Für KPIs mit der Einheit „Zeit" wird der Wert als Minuten seit 00:00 Uhr übermittelt.

  • 14:43 Uhr → 14 × 60 + 43 = 883
  • 08:00 Uhr → 8 × 60 = 480
{
  "values": [
    {
      "kpiValueId": "79cf2f74-0e9c-45b5-bc4d-f437079dde7c",
      "value": 883
    }
  ]
}

🔍 KPI-Datensätze abrufen (GET)

Beispiel: Alle Werte einer KPI innerhalb eines Zeitraums:

DELETE /exchange/kpi-data/2022-11-01/8dca904d-9134-3bb0-95b7-3f72ae3dfacf/c3ba32c2-a13a-0000-0000-000000000000

ℹ️ Hinweis: Der Zeitraum darf maximal 31 Tage (Tageserfassung), 6 Monate (Wochenerfassung) oder 24 Monate (Monatserfassung) umfassen. Die Ergebnisse sind absteigend nach Datum sortiert.

Der Parameter sub-tile-id ist optional und filtert die Ergebnisse auf ein bestimmtes Sub-Tile.

❌ KPI-Datensatz löschen (DELETE)

DELETE /exchange/kpi-data/2022-11-01/8dca904d-9134-3bb0-95b7-3f72ae3dfacf/c3ba32c2-a13a-0000-0000-000000000000

⚠️ Achtung: Gelöschte Einträge können nicht wiederhergestellt werden.

📌 Technische Hinweise

  • Jeder KPI-Datensatz ist eindeutig identifiziert durch: date + team + kpi (+ optional sub-tile)
  • Pro Tag / Woche / Monat ist nur ein Datensatz pro Kombination möglich
  • Datumsformat: yyyy-MM-dd (Woche = Montag, Monat = erster Tag)
  • Die API schreibt und liest Daten – sie überträgt keine Daten aktiv an Drittsysteme (kein Push/Pull)
  • UUIDs für KPI, Team, Sub-Tile und KPI-Wert werden über die Meta-Endpunkte bezogen
  • Bei aggregierten KPIs können Werte nur auf der untersten Teamebene (Leaf-Level) eingetragen werden – übergeordnete Teams werden automatisch aggregiert

✨ Tipps & Best Practices

  • 🧪 Beginnen Sie mit Tests im Swagger Editor oder Postman, bevor Sie die Integration produktiv schalten
  • 🔄 Aktualisieren Sie KPI-Werte regelmäßig für konsistente Auswertungen
  • 🧾 Prüfen Sie UUIDs von KPI, Team, Sub-Tile und KPI-Wert über die Meta-Endpunkte vor dem ersten Import
  • 📋 Nutzen Sie adoptActualsIfPossible: true in automatisierten Imports, um Forecast-Istwerte direkt zu übernehmen, sobald der Zeitraum abgeschlossen ist
  • 🔎 Prüfen Sie das Feld forecast in der GET-Antwort, um zu erkennen, ob ein Wert noch vorläufig ist

❓ FAQ

Wie finde ich die benötigten UUIDs (KPI, Team, KPI-Werte)? Nutzen Sie die Meta-Endpunkte GET /exchange/kpi für alle KPIs und GET /exchange/kpi/{kpi-id} für Details inkl. Erfassungsteams, Sub-Tiles und KPI-Wert-IDs.

Was passiert, wenn ich dieselben Werte erneut sende? Die API erkennt bestehende Kombinationen und überschreibt vorhandene Werte (PUT = Create or Update). Es wird kein Fehler ausgelöst.

Was ist der Unterschied zwischen API v2 und v3? In v3 (application/vs.v3.0+json) sind Forecast-Istwerte, das forecast-Flag in der Antwort sowie adoptActualsIfPossible und historicalForecastValues verfügbar. Für alle neuen Integrationen sollte ausschließlich v3 verwendet werden.

Wie erkenne ich, ob ein Wert noch ein Forecast ist? Das Feld values[].forecast in der GET-Antwort ist true, solange der Wert noch nicht übernommen wurde. Nach der Übernahme steht dort false, und der ursprüngliche Forecast-Wert ist in historicalForecastValues dokumentiert.

Wie übergebe ich Uhrzeit-basierte KPI-Werte? Senden Sie die Minuten seit 00:00 Uhr als Ganzzahl. Beispiel: 14:43 Uhr = 14 × 60 + 43 = 883.