Read tickets, CMDB and assets through the interface

Andere Systeme brauchen oft Daten aus knooing: ein Inventarwerkzeug den Bestand der CMDB, ein Leitstand die offenen Störungen, ein Skript der Buchhaltung die Assets mit ihren Anschaffungsdaten. Statt Listen von Hand zu exportieren, holt sich das Fremdsystem die Daten selbst über die Schnittstelle von knooing. Dafür bekommt es einen eigenen Schlüssel, der genau das lesen darf, was Sie freigeben.

Julia Beispiel richtet in dieser Anleitung den Zugang für ein Inventarwerkzeug im Lager ein. Es soll Störungen und Changes lesen, dazu Konfigurationselemente und Assets. Die Schritte 1 bis 4 erledigen Sie in knooing. Die Schritte 5 und 6 richtet die Person ein, die das Fremdsystem betreut; geben Sie ihr diese Anleitung weiter. Ob die Aufrufe ankommen, sehen Sie danach selbst im Aufrufprotokoll eines Schlüssels.

Die wichtigsten Begriffe

• Schnittstelle (REST-API): der Weg, über den andere Systeme Daten mit knooing austauschen. Jeder Aufruf geht an eine Webadresse, etwa /api/v1/tickets.
• Aufruf: eine einzelne Anfrage des Fremdsystems an knooing. Ein lesender Aufruf heißt technisch GET: GET /api/v1/tickets heißt „Gib mir die Vorgänge.“
• Schlüssel: das Passwort eines Fremdsystems. Es schickt den Schlüssel bei jedem Aufruf in einer Zusatzangabe der Anfrage mit, dem Kopfeintrag (Header) X-API-Key.
• Berechtigung: was ein Schlüssel darf. Im Dialog steht sie als Haken, in der technischen Beschreibung als Scope. CMDB lesen heißt dort cmdb:read, Assets lesen assets:read, Störungen lesen tickets.incident:read, Changes lesen tickets.change:read.
• Höchste Vertraulichkeit: eine Obergrenze für den Schutzbedarf Vertraulichkeit. Mit Bis hoch liefert die Schnittstelle Daten mit dem Schutzbedarf sehr hoch nicht aus, weder in Listen noch in Verläufen. Ein Datensatz ohne Einstufung gilt als normal.
• Vorgangsart: Störung, Service Request (Anfrage), Problem oder Change (geplante Änderung). Jede Art hat eine eigene Lese-Berechtigung.
• Konfigurationselement: ein Eintrag in der CMDB, etwa ein Server. Assets sind Konfigurationselemente mit Anschaffungs- und Garantiedaten.
• Seite: Listen kommen in Portionen. limit sagt, wie viele Einträge eine Seite hat (1 bis 200, Standard 50), offset, ab welchem Eintrag sie beginnt. Beispiel: 120 Störungen, limit=50: Seite 1 mit offset=0, Seite 2 mit offset=50, Seite 3 mit offset=100.
• curl und JSON: curl ist ein Befehl, mit dem man einen Aufruf von Hand testet. JSON ist das Textformat, in dem knooing antwortet.

Schritt 1: Den Dialog Schlüssel anlegen öffnen

Klicken Sie unten in der Seitenleiste auf Einstellungen, links auf Integrationen und daneben auf Schnittstellen. Im Reiter Schlüssel klicken Sie rechts auf Schlüssel anlegen (1). Der Hinweis über der Liste spricht nur vom Melden; derselbe Dialog legt auch Schlüssel zum Lesen an.

1

Danach öffnet sich der Dialog Schlüssel anlegen. Tragen Sie bei Name ein, wer den Schlüssel nutzt, im Beispiel „Inventarabgleich Lager“. Den Kanal lassen Sie auf Schnittstelle/Provider; er gilt nur für Meldungen und spielt beim Lesen keine Rolle.

Warum ein eigener Schlüssel je System? Endet die Nutzung oder wird der Schlüssel bekannt, widerrufen Sie genau diesen einen, ohne andere Anbindungen zu stören.

Beispiel: Das Inventarwerkzeug im Lager gleicht die Server mit der CMDB ab und zeigt dazu offene Störungen und geplante Changes.

Schritt 2: Berechtigungen und Schutz wählen

Unter Berechtigungen sind zu Beginn die beiden obersten Haken gesetzt: Störungen melden und Status eigener Meldungen abfragen. Nehmen Sie beide weg. Das Werkzeug soll nichts melden. Scrollen Sie dann weiter und haken Sie an:

• CMDB lesen (1): Konfigurationselemente und ihre Beziehungen.
• Assets lesen (2): Assets mit Anschaffungs- und Garantiedaten.
• Störungen lesen (3) und Changes lesen (4). Service Requests lesen und Probleme lesen haken Sie nur an, wenn das Werkzeug sie braucht.

1234

Ganz unten im Dialog steht der Abschnitt Gültigkeit und Schutz:

• Ablaufdatum - optional (1): Der Schlüssel gilt bis zum Ende dieses Tages. Ohne Angabe läuft er nicht ab. Für einen Schlüssel, der nur liest, empfiehlt sich höchstens ein Jahr, im Beispiel der 15.10.2027.
• Anfragen je Minute: steht auf 60. Weitere Anfragen in derselben Minute lehnt die Schnittstelle ab. Mehr braucht ein Werkzeug selten; lassen Sie den Wert stehen.
• Höchste Vertraulichkeit (2): Wählen Sie die Stufe, bis zu der das Werkzeug Daten sehen darf. Zur Wahl stehen Keine Begrenzung, Bis normal, Bis hoch und Bis sehr hoch. Im Beispiel Bis hoch.
• Erlaubte IP-Adressen - optional: einzelne Adressen wie 203.0.113.10 oder Netze wie 198.51.100.0/24, getrennt durch Komma oder Zeilenumbruch. Ohne Angabe gilt der Schlüssel von überall. Hat das Fremdsystem eine feste Adresse, tragen Sie sie ein.

Klicken Sie unten auf Anlegen (3).

123

Warum nur Lese-Berechtigungen und eine Obergrenze? Ein Schlüssel liegt im Fremdsystem, also außerhalb Ihrer Kontrolle. Darf er nur lesen, kann auch ein entwendeter Schlüssel nichts ändern. Die Obergrenze hält besonders vertrauliche Daten zusätzlich heraus.

Beispiel: Das Inventarwerkzeug läuft auf wechselnden Rechnern im Lager. Julia Beispiel lässt deshalb die IP-Adressen leer und setzt dafür ein Ablaufdatum in einem Jahr.

Schritt 3: Den Schlüssel kopieren

Danach erscheint der Dialog Schlüssel angelegt. Der Schlüssel steht im Feld darunter. Klicken Sie auf Kopieren (1); das übernimmt den ganzen Schlüssel, und der Knopf heißt danach Kopiert. Geben Sie ihn sicher an die Person weiter, die das Fremdsystem einrichtet, etwa über einen Passwort-Tresor. Klicken Sie dann auf Fertig.

1

Danach steht der Schlüssel in der Liste (i), mit seinen Berechtigungen, unter dem Namen Vertraulichkeit bis hoch, bei Läuft ab 15.10.2027 und Status aktiv. Bei Zuletzt benutzt steht „noch nie“, bis das Werkzeug den ersten Aufruf macht; danach stehen dort Datum und Uhrzeit.

i

Warum sofort kopieren? knooing zeigt den Schlüssel nur jetzt. Geht er verloren, widerrufen Sie ihn und legen einen neuen an.

Beispiel: Julia Beispiel legt den Schlüssel im Passwort-Tresor der IT ab. Tobias Beispiel, der das Inventarwerkzeug betreut, trägt ihn dort ein.

Schritt 4: Den Reiter Dokumentation lesen

Klicken Sie oben auf den Reiter Dokumentation. Im Kasten Anmeldung steht die Basisadresse, im Beispiel https://knooing.beispiel-gmbh.test. An diese Adresse gehen alle Aufrufe. Nehmen Sie sie von hier und nicht aus der Adresszeile Ihres Browsers; die beiden können sich unterscheiden. Daneben öffnet der Link OpenAPI-Beschreibung die vollständige technische Beschreibung aller Pfade, Filter und Antworten.

Darunter beschreibt knooing jeden Aufruf in einem eigenen Kasten: oben Methode, Pfad und nötige Berechtigung, darunter ein Beispiel. Mit Kopieren (1) unter dem Beispiel übernehmen Sie es. Weiter unten stehen die Regeln, die für alle Aufrufe gelten, etwa zum seitenweisen Lesen.

1

$KNOOING_API_KEY steht für Ihren Schlüssel; die Person, die das Fremdsystem einrichtet, ersetzt es durch den kopierten Schlüssel. status=open im Beispiel liefert alle offenen Vorgänge.

Warum die Beschreibung in knooing? Sie passt immer zu Ihrer Version, und die Beispiele tragen schon Ihre Adresse.

Beispiel: Tobias Beispiel übernimmt das Beispiel für Konfigurationselemente in das Inventarwerkzeug und ersetzt nur den Schlüssel.

Schritt 5: Vorgänge abrufen lassen

Diesen und den nächsten Schritt richtet die Person ein, die das Fremdsystem betreut. In den Beispielen steht https://knooing.beispiel-gmbh.test für Ihre Basisadresse aus Schritt 4 und $KNOOING_API_KEY für den Schlüssel; beides ersetzt sie.

Vorgänge holt das Fremdsystem mit GET /api/v1/tickets. Die Vorgangsart steht in type: incident, service_request, problem oder change. So holt es die ersten 50 Störungen:

curl 'https://knooing.beispiel-gmbh.test/api/v1/tickets?type=incident&limit=50' \
  -H "X-API-Key: $KNOOING_API_KEY"

Die Antwort ist eine Liste in items, dazu Angaben zum Weiterblättern. Gekürzt sieht sie so aus:

{
  "items": [
    {
      "id": "cmv9eqybo005aex4ifu8dnh0m",
      "number": "INC-2026-000005",
      "type": "incident",
      "status": "new",
      "title": "Lieferscheine erscheinen doppelt",
      "priority": "Mittel - Arbeit ist möglich",
      "service": { "name": "Warenwirtschaft" }
    }
  ],
  "limit": 50,
  "offset": 0,
  "hasMore": false,
  "nextOffset": null
}

Steht hasMore auf true, gibt es weitere Einträge. Dann ruft das Fremdsystem dieselbe Adresse noch einmal auf und setzt offset auf den Wert aus nextOffset. Weitere Filter sind status, serviceId, search und updatedSince. Ohne status kommen Vorgänge in jedem Zustand; status=open liefert alle offenen, mehrere Zustände trennt ein Komma. Mit updatedSince=2026-10-15T08:00:00Z holt es nur, was sich seit diesem Zeitpunkt geändert hat. Einen einzelnen Vorgang samt öffentlicher Kommentare liest es mit GET /api/v1/tickets/<id>, mit dem Wert aus id.

Die Werte stehen in technischer Form: new heißt neu, in_progress in Arbeit, resolved gelöst. Ob die Aufrufe klappen, sehen Sie in knooing im Aufrufprotokoll des Schlüssels. Ein erfolgreicher Aufruf steht dort mit 200.

Warum je Vorgangsart eine Berechtigung? Störungen brauchen viele Systeme, Probleme oder Changes nur wenige. Getrennte Berechtigungen halten jeden Schlüssel so klein wie möglich.

Beispiel: Das Inventarwerkzeug fragt alle zehn Minuten mit updatedSince nach Störungen, die sich seit dem letzten Aufruf geändert haben.

Schritt 6: Konfigurationselemente und Assets abrufen lassen

Konfigurationselemente holt das Fremdsystem mit GET /api/v1/configuration-items, Assets mit GET /api/v1/assets. So holt es die ersten 50 Server:

curl 'https://knooing.beispiel-gmbh.test/api/v1/configuration-items?classKey=server&limit=50' \
  -H "X-API-Key: $KNOOING_API_KEY"

Jeder Eintrag nennt unter anderem Name, Klasse, Lebenszyklus, Umgebung, Kritikalität, Standort und Abteilung:

{
  "id": "cmv9gadr800a6exs8ot4jd3sf",
  "name": "srv-etikettendruck",
  "class": { "key": "server", "name": "Server" },
  "lifecycle": "active",
  "environment": "prod",
  "criticality": "medium",
  "location": { "name": "Lager Nord" },
  "department": { "name": "Versand" }
}

active heißt aktiv, prod Produktiv, medium mittel. Den Klassenschlüssel für classKey liefert jeder Eintrag unter class.key, hier server. Weitere Filter sind q für einen Suchbegriff, lifecycle, environment und updatedSince.

Die Antwort von /api/v1/assets enthält dieselben Angaben und zusätzlich Anschaffungs- und Garantiedaten wie purchaseDate, warrantyUntil und purchasePrice. Beziehungen zwischen Elementen, etwa „läuft auf“, liest das Fremdsystem mit GET /api/v1/ci-relations. Alle Listen blättern wie in Schritt 5 mit limit und offset.

Warum Assets getrennt? Anschaffungspreise und Restwerte sind vertraulicher als Name und Standort. Mit einer eigenen Berechtigung geben Sie sie nur Systemen, die sie wirklich brauchen.

Beispiel: Das Inventarwerkzeug vergleicht die Server im Lager Nord mit seiner eigenen Liste und meldet Abweichungen an Tobias Beispiel.

Wenn etwas nicht klappt

Die Schnittstelle antwortet bei Fehlern mit einem Statuscode und einer Meldung in error:

• 401 „Ungültiger oder fehlender API-Schlüssel.“ Der Kopfeintrag X-API-Key fehlt, oder der Schlüssel ist falsch abgeschrieben, widerrufen oder abgelaufen. Prüfen Sie den Schlüssel und seinen Status in der Liste.
• 403 „Dem Schlüssel fehlt die Berechtigung "tickets.problem:read".“ Der Schlüssel darf diese Vorgangsart nicht lesen; tickets.problem:read heißt im Dialog Probleme lesen. Die Berechtigungen eines bestehenden Schlüssels lassen sich nicht erweitern. Legen Sie einen neuen Schlüssel mit der fehlenden Berechtigung an, geben Sie ihn weiter und widerrufen Sie danach den alten.
• 403 „Die Absenderadresse ist für diesen Schlüssel nicht freigegeben.“ Das Fremdsystem ruft von einer Adresse, die nicht unter Erlaubte IP-Adressen steht. Legen Sie einen Schlüssel mit der richtigen Adresse an, geben Sie ihn weiter und widerrufen Sie den alten.
• 429 „Zu viele Anfragen mit diesem Schlüssel. Bitte später erneut versuchen.“ Das Fremdsystem ruft öfter auf, als Anfragen je Minute erlaubt. Lassen Sie seltener abrufen.
• 404 „Konfigurationselement nicht gefunden.“ Die Kennung in der Adresse gibt es nicht, oder der Schlüssel darf das Element nicht sehen. Prüfen Sie die Kennung aus der Liste.
• Sie haben den Dialog geschlossen, ohne zu kopieren. Der Schlüssel lässt sich nicht erneut anzeigen. Widerrufen Sie ihn in der Liste mit Widerrufen und legen Sie einen neuen an.
• Bei Zuletzt benutzt bleibt „noch nie“ stehen. Das Fremdsystem ruft nicht auf, oder es schickt einen falschen Schlüssel oder eine falsche Adresse. Lassen Sie Schlüssel und Basisadresse im Fremdsystem prüfen; Fehler mit einem gültigen Schlüssel sehen Sie im Aufrufprotokoll.
• Die Liste ist leer oder Einträge fehlen. Der Schlüssel sieht nie mehr als die Person, die ihn angelegt hat. Fehlt ihr ein Recht oder schränken Sichtregeln sie ein, fehlen die Einträge auch hier. Verliert diese Person später Rechte, verliert sie auch der Schlüssel. Lassen Sie den Schlüssel von einer Person mit passenden Rechten anlegen. Auch die Obergrenze bei Höchste Vertraulichkeit hält Einträge zurück.
• Bei Assets fehlen die Beträge. Die Person, die den Schlüssel angelegt hat, darf die Feldgruppe Kosten nicht sehen. Lassen Sie den Schlüssel von einer Person mit diesem Recht anlegen.
• Der Punkt Schnittstellen oder der Knopf Schlüssel anlegen fehlt. Ihnen fehlt die Befugnis Integrationen verwalten. Bitten Sie Ihre Administration darum.