Fetch histories and KPIs via the API: status changes, changes and monthly values

Wie der Schlüssel für die Plattform entsteht, steht in Schlüssel für eine Reporting-Plattform anlegen. Diese Anleitung ist für die Technik, die die Plattform an knooing anbindet. Sie zeigt, wie die Plattform neben dem aktuellen Stand auch die Geschichte abholt. Dazu gehören jeder Statuswechsel der Vorgänge, jede Änderung an Vorgängen und Konfigurationselementen mit altem und neuem Wert und die Kennzahlen je Monat.

Mit diesen Daten bildet die Plattform den Stand eines Vorgangs oder Systems zu jedem Zeitpunkt nach, rechnet eigene Laufzeiten und legt die Monatskennzahlen neben Zahlen aus anderen Systemen. Den aktuellen Stand der Vorgänge und Konfigurationselemente liefern die bekannten Abrufe der Schnittstelle, die in knooing im selben Reiter beschrieben sind. Am Ende holt Ihre Plattform die Daten aller vier Abrufe regelmäßig und lückenlos ab.

Die wichtigsten Begriffe

• Abruf: eine Anfrage der Plattform an knooing, hier immer zum Lesen (GET). Der Schlüssel steht jedes Mal im Kopffeld X-API-Key.
• Eintrag: ein Element der Liste items in der Antwort, etwa ein Statuswechsel.
• Seite: eine Antwort enthält höchstens limit Einträge, Standard 200, höchstens 500. hasMore: true heißt: Es folgen weitere.
• Cursor: die Stelle, bis zu der die Plattform gelesen hat. Jede Antwort enthält ihn als nextCursor. Beim nächsten Abruf schickt die Plattform ihn als cursor mit und erhält genau die Einträge danach.
• Anfangsstand: der Eintrag mit "event": "created". Er nennt die Einordnung eines Vorgangs bei der Anlage. Alle späteren Einträge sind Änderungen davon.
• Vertraulichkeit (confidentiality): die Stufe normal, hoch oder sehr_hoch des Datensatzes. Einträge oberhalb der Grenze des Schlüssels liefert knooing nicht aus.

Schritt 1: Die Beschreibung in knooing öffnen

Klicken Sie in der Seitenleiste unten auf Einstellungen, dann auf Integrationen und auf Schnittstellen. Öffnen Sie den Reiter Dokumentation (1) und scrollen Sie zum Abschnitt Daten für Reporting- und Data-Plattformen (2).

Danach sehen Sie die vier Abrufe Statusverläufe der Vorgänge, Änderungen an Vorgängen, Änderungen an Konfigurationselementen und Kennzahlen je Monat. Neben jedem Pfad steht die Berechtigung, die der Schlüssel braucht, darunter ein Beispiel mit curl, der Adresse Ihres knooing und dem Knopf Kopieren.

12

Warum in knooing nachsehen? Die Beschreibung im Reiter passt immer zum Stand Ihres knooing und enthält Ihre Adresse. So kopieren Sie Aufrufe, die sofort funktionieren.

Beispiel: Tobias Beispiel betreut die Plattform des Controllings. Julia Beispiel zeigt ihm den Abschnitt und übergibt den Schlüssel „Reporting-Plattform Controlling“.

Schritt 2: Die Statusverläufe abrufen

Senden Sie den ersten Abruf. Mit from beginnen Sie bei einem Zeitpunkt, mit limit legen Sie die Seitengröße fest:

curl '<Adresse Ihres knooing-Systems>/api/v1/ticket-status-history?from=2026-10-01T00:00:00Z&limit=2' \
  -H 'X-API-Key: <Schlüssel>'

Danach antwortet knooing mit den Statuswechseln in der Reihenfolge, in der sie gespeichert wurden (Kennungen hier gekürzt):

{
  "items": [
    { "id": "cmv801m…", "ticketId": "cmv801f…", "ticketNumber": "INC-2026-000092", "ticketType": "incident",
      "fromStatus": "new", "toStatus": "in_progress", "occurredAt": "2026-10-14T11:01:07.254Z",
      "source": "local", "confidentiality": "hoch" },
    { "id": "cmv801m…", "ticketId": "cmv801f…", "ticketNumber": "INC-2026-000092", "ticketType": "incident",
      "fromStatus": "in_progress", "toStatus": "resolved", "occurredAt": "2026-10-14T11:01:07.784Z",
      "source": "local", "confidentiality": "hoch" }
  ],
  "nextCursor": "eyJ2IjoxLCJmIjoic3RhdHVzIiwieCI6IjExMzgyMTc0IiwicyI6IjczMCJ9",
  "hasMore": true
}

Jeder Eintrag nennt den Vorgang mit Nummer und Vorgangsart, den alten und neuen Status und den Zeitpunkt (occurredAt, in UTC). source nennt die Herkunft: local heißt in knooing geändert, bridge im Werkzeug eines Dienstleisters. Mit type=incident,problem beschränken Sie den Abruf auf bestimmte Vorgangsarten.

Warum der Status als eigener Verlauf? Aus den Statuswechseln rechnet die Plattform eigene Zeiten, etwa wie lange Vorgänge in Bearbeitung oder beim Dienstleister lagen, auch für Zeiträume, die knooing selbst nicht auswertet.

Beispiel: Die Störung INC-2026-000092 zur Warenwirtschaft ging um 11:01 Uhr UTC, also 13:01 Uhr Ortszeit, in Bearbeitung und wurde kurz danach gelöst. Sie trägt die Vertraulichkeit hoch, weil der Business-Service Warenwirtschaft so eingestuft ist.

Schritt 3: Fortlaufend weiterlesen

Speichern Sie nextCursor aus jeder Antwort. Beim nächsten Abruf schicken Sie ihn als cursor mit, from lassen Sie dann weg:

curl '<Adresse Ihres knooing-Systems>/api/v1/ticket-status-history?limit=500&cursor=eyJ2IjoxLCJmIjoic3RhdHVzIiwieCI6IjExMzgyMTc0IiwicyI6IjczMCJ9' \
  -H 'X-API-Key: <Schlüssel>'

Danach erhalten Sie genau die Einträge nach dieser Stelle, ohne Lücke und ohne doppelte. Steht in der Antwort "hasMore": true, rufen Sie sofort mit dem neuen nextCursor weiter ab. Bei "hasMore": false ist die Plattform auf dem aktuellen Stand; beim nächsten geplanten Lauf, etwa stündlich, beginnt sie wieder mit dem zuletzt gespeicherten nextCursor. Auch eine leere Antwort enthält einen nextCursor.

Jeder Abruf hat seinen eigenen Cursor. Einen Cursor der Statusverläufe nimmt der Abruf der Änderungen nicht an.

Warum ein Cursor statt eines Zeitpunkts? Ein Eintrag kann mit einem zurückliegenden Zeitpunkt gespeichert werden, etwa wenn ein Dienstleister eine Änderung verspätet meldet. Wer nach Zeitpunkt abruft, verpasst ihn. Der Cursor folgt der Reihenfolge des Speicherns und liefert auch solche Einträge. Ein Statuswechsel erscheint deshalb erst, wenn alle früher begonnenen Schreibvorgänge abgeschlossen sind. Ein ungewöhnlich langer Schreibvorgang verzögert den Abruf, bis er endet; verloren geht dabei nichts.

Beispiel: Tobias Beispiel lässt die Plattform jede Stunde abrufen und speichert nach jeder Seite den nextCursor in ihrer Datenbank.

Schritt 4: Die Änderungen an Vorgängen und Konfigurationselementen abrufen

Änderungen an Vorgängen rufen Sie genauso ab. Mit fields wählen Sie einzelne Felder, hier Kategorie und Auswirkung:

curl '<Adresse Ihres knooing-Systems>/api/v1/ticket-changes?from=2026-10-01T00:00:00Z&fields=categoryId,impact' \
  -H 'X-API-Key: <Schlüssel>'

Danach enthält jeder Eintrag in changes je Feld den alten Wert (from), den neuen (to) und für Kennungen die Anzeigenamen (fromLabel, toLabel). Zwei Einträge aus der Antwort:

{ "seq": "119", "ticketNumber": "INC-2026-000092", "event": "created", "origin": "user", "confidentiality": "hoch",
  "occurredAt": "2026-10-14T11:00:58.325Z",
  "changes": [ { "field": "categoryId", "from": null, "to": "cmv8017…", "fromLabel": null, "toLabel": "Hardware" },
               { "field": "impact", "from": null, "to": "2", "fromLabel": null, "toLabel": null } ] }
{ "seq": "126", "ticketNumber": "INC-2026-000092", "event": "classification_updated", "origin": "user", "confidentiality": "hoch",
  "occurredAt": "2026-10-14T11:01:06.322Z",
  "changes": [ { "field": "categoryId", "from": "cmv8017…", "to": "cmv8017…", "fromLabel": "Hardware", "toLabel": "Software" } ] }

Der Eintrag "event": "created" ist der Anfangsstand, die späteren sind Änderungen. Mit fields enthält auch der Anfangsstand nur die gewählten Felder. Neben Kategorie und Auswirkung liefert knooing Status, Vorgangsart, Nummer, Service, Business-Service, auslösendes System, Priorität, Dringlichkeit, Team, Dienstleister, dessen Referenz und die Rechtssperre. origin nennt, woher die Änderung kam: user (eine Person in knooing), system (eine Automatik) oder supplier (ein Dienstleister).

Änderungen an Konfigurationselementen holen Sie mit GET /api/v1/cmdb-changes. Der erste Eintrag eines Systems hat "kind": "created" und den vollständigen Stand in newValue. Danach folgt je geändertem Feld ein Eintrag:

{ "seq": "18", "ciNumber": "CI-1002", "ciName": "srv-shop01", "occurredAt": "2026-10-14T10:59:17.334Z",
  "kind": "updated", "field": "lifecycle", "oldValue": "active", "newValue": "maintenance",
  "source": "manual", "confidentiality": "normal" }

Auch archivierte Systeme bleiben in diesem Verlauf.

Warum alter und neuer Wert? Aus Anfangsstand und Änderungen bildet die Plattform den Stand zu jedem Zeitpunkt nach, etwa die Kategorie einer Störung am Monatsende oder den Lebenszyklus eines Servers am Stichtag einer Prüfung.

Beispiel: Die Störung INC-2026-000092 wurde als Hardware erfasst und später auf Software korrigiert. Aus den beiden Einträgen erkennt die Plattform diese Korrektur, die knooing in Störungskennzahlen lesen als Abweichung zählt.

Schritt 5: Die Kennzahlen je Monat abrufen

Rufen Sie die Kennzahlen ab. Mit domain wählen Sie die Bereiche: incidents für die Störungskennzahlen, itsm, cmdb und itam für die Steuerungskennzahlen. Mit months wählen Sie, wie viele Monate die Störungskennzahlen umfassen, 1 bis 25, Standard 13:

curl '<Adresse Ihres knooing-Systems>/api/v1/kpi-history?domain=incidents&months=3' \
  -H 'X-API-Key: <Schlüssel>'

Danach erhalten Sie je Monat die gelösten Störungen, Klassifizierungsgenauigkeit und Abweichungsquote als Anteil (0,875 = 87,5 %), die Abweichung je Merkmal und die Laufzeiten in Stunden. Ein Auszug:

{ "generatedAt": "2026-10-14T11:08:05.433Z",
  "domains": { "incidents": { "months": ["2026-08", "2026-09", "2026-10"], "timeZone": "Europe/Vienna",
    "series": [
      { "month": "2026-09", "resolved": 7, "withBaseline": 7, "accuracyRate": 1, "deviationRate": 0,
        "deviations": { "type": 0, "service": 0, "category": 0, "impactUrgency": 0 },
        "avgRuntimeHours": 13.209523809523807, "medianRuntimeHours": 13.8,
        "p90RuntimeHours": 19.583333333333332 } ] } } }

Die Werte sind dieselben wie in knooing im Reiter Klassifizierung & Laufzeiten. Ohne domain liefert knooing alle Bereiche, die die Person lesen darf, die den Schlüssel ausgestellt hat. Die Steuerungskennzahlen haben je Kennzahl 13 Monate mit dem Wert des Vorjahresmonats, wie in Steuerungskennzahlen im Verlauf lesen.

Warum fertige Kennzahlen und nicht nur Rohdaten? So rechnet die Plattform nichts nach, was knooing schon rechnet, und die Zahlen im Bericht stimmen mit denen in knooing überein.

Beispiel: Die Plattform übernimmt jeden Monat die Zeile des Vormonats. Für September stehen dort 7 gelöste Störungen und eine Genauigkeit von 100 %.

Was die Plattform nie erhält

• Keine Personen: keine handelnde Person, keinen Bearbeiter, keinen Melder. Die Herkunft einer Änderung steht nur als user, system oder supplier.
• Keine Freitexte: keine Titel, Beschreibungen oder Kommentare.
• Keine Sicherheitsvorfälle: Vorgänge, die als Sicherheitsvorfall gekennzeichnet sind, erscheinen in keinem Verlauf.
• Nichts über der Grenze: Datensätze oberhalb der höchsten Vertraulichkeit des Schlüssels. Die Kennzahlen je Monat sind Summen und bleiben davon unberührt.
• Nichts außerhalb der Rechte der ausstellenden Person: Werte von Konfigurationselementen folgen ihren Rechten für Kosten, Personenbezug, Sicherheit und Verträge.

Wenn etwas nicht klappt

• „Ungültiger oder fehlender API-Schlüssel.“ (Status 401). Der Schlüssel ist falsch kopiert, abgelaufen oder widerrufen. Prüfen Sie das Kopffeld X-API-Key und den Status des Schlüssels in der Liste.
• Status 404 mit „Cannot GET …“. Das Kopffeld X-API-Key fehlt ganz, oder der Pfad ist falsch geschrieben. Senden Sie den Schlüssel bei jedem Abruf mit.
• „Dem Schlüssel fehlt die Berechtigung "history:read".“ (Status 403). Dem Schlüssel fehlt Verläufe lesen, bei den Kennzahlen entsprechend Kennzahlen je Monat lesen (kpis:read). Legen Sie einen Schlüssel mit der Berechtigung an.
• „Für Verläufe von Vorgängen braucht der Schlüssel zusätzlich mindestens eine Berechtigung …“ Dem Schlüssel fehlt die Lese-Berechtigung einer Vorgangsart, etwa Störungen lesen.
• „Für Änderungen der Konfigurationselemente braucht der Schlüssel zusätzlich die Berechtigung "cmdb:read".“ Dem Schlüssel fehlt CMDB lesen.
• „cursor ist ungültig. Verwenden Sie den Wert nextCursor der letzten Antwort desselben Abrufs.“ Der Cursor ist unvollständig kopiert oder stammt von einem anderen Abruf. Nehmen Sie den nextCursor der letzten Antwort genau dieses Abrufs.
• „limit muss zwischen 1 und 500 liegen.“ Wählen Sie eine Seitengröße bis 500 und lesen Sie mit dem Cursor weiter.
• „domain muss aus itsm, cmdb, itam, incidents bestehen (kommagetrennt).“ Prüfen Sie die Schreibweise der Bereiche.
• „Für incidents fehlt dem Dienstkonto dieses Schlüssels das Leserecht.“ Die Person, die den Schlüssel ausgestellt hat, darf diesen Bereich nicht lesen. Lassen Sie domain weg oder den Schlüssel von einer Person mit dem Recht ausstellen.
• Ein Vorgang oder System fehlt in den Verläufen. Er liegt über der Grenze des Schlüssels, ist als Sicherheitsvorfall gekennzeichnet oder für die ausstellende Person nicht sichtbar. Prüfen Sie die Angabe Vertraulichkeit bis … in der Liste der Schlüssel.