Was die TOPdesk-API liefert – und was nicht

Die TOPdesk-API ist ordentlich dokumentiert und tut, was man erwartet. Es stecken aber ein paar Dinge darin, die man erst entdeckt, wenn man eine Weile damit gearbeitet hat, und die Ihre Berichtspläne über den Haufen werfen können. Das ist beim Bau eines Dashboards darauf zutage getreten.

Was ohne Umstände herauskommt

Incidents sind der einfache Teil. Sie bekommen sie mit Kategorie und Unterkategorie, Status, Priorität, Linie, Bearbeitergruppe, Bearbeiter, Erstellungsdatum, Abschlussdatum und den SLA-Feldern. Genug für Eingang, Lösungszeit, SLA-Einhaltung pro Priorität und die Frage, wie lange das älteste offene Ticket schon liegt.

Changes und die zugehörigen Aktivitäten kommen ebenfalls heraus, genau wie Assets mit Typ, Standort und Status sowie Wissenseinträge mit ihrem Status und der Angabe, ob sie im Self-Service Portal sichtbar sind. Bearbeiter lassen sich einschließlich ihrer Berechtigungsgruppen abrufen, was praktischer ist, als es klingt: So entdecken Sie kostenpflichtige Konten, die seit Monaten nichts getan haben.

Was nicht herauskommt: der Verlauf

Das ist der wichtige Punkt, und der, an dem die meisten Pläne scheitern. Die API liefert Ihnen den aktuellen Zustand eines Incidents. Welche Bearbeitergruppe er jetzt hat, welchen Status er jetzt hat, bei wem er jetzt liegt.

Was Sie nicht bekommen, ist die Route, die er genommen hat. Sie können die API nicht fragen, ob Incident 4711 zuerst beim 1st Level lag, dann elf Tage beim Netzwerkmanagement und dann wieder zurückkam. Diese Übergaben stecken in TOPdesk selbst, aber die API gibt sie nicht heraus.

Das hat eine ärgerliche Folge für Ihre Berichte: Die Frage „Wo bleibt Arbeit hängen?“ lässt sich mit einer API-Anbindung allein nicht beantworten. Und es ist meist genau die Frage, auf die das Management eigentlich wartet, denn dort versteckt sich die Lösungszeit.

Der einzige Ausweg ist, es selbst nachzuhalten. Sie holen den aktuellen Zustand regelmäßig ab, vergleichen ihn mit dem, was Sie beim letzten Mal gesehen haben, und notieren die Differenz. Ab diesem Moment bauen Sie eine Zeitleiste auf. Der Nachteil liegt auf der Hand: Über die Zeit vor der Anbindung wissen Sie nichts, und das lässt sich nicht nachholen. Wer das will, sollte also früh anfangen — der Wert wächst mit der Zeit.

Pfade unterscheiden sich je nach Lizenz und Version

Die Incident-API ist überall dieselbe. Bei allem anderen wird es unübersichtlicher. Welche Endpunkte für Changes, Assets und Wissenseinträge verfügbar sind, hängt davon ab, welche Module in Ihrer Lizenz enthalten sind, und von Ihrer TOPdesk-Version.

In der Praxis heißt das: Sie können nicht auf Annahmen bauen. Hat eine Umgebung kein Assetmanagement, ist dieser Pfad schlicht nicht da, und Sie bekommen einen Fehler statt einer sauberen leeren Liste. Prüfen Sie deshalb immer die API-Referenz der Umgebung selbst, nicht die allgemeine Dokumentation.

401 und 403 bedeuten wirklich Unterschiedliches

Ein Detail, das Ihnen Stunden sparen kann. Ein 401 bedeutet, dass Ihre Zugangsdaten falsch sind: falscher Benutzername oder ein widerrufenes Anwendungspasswort. Ein 403 bedeutet, dass Ihre Zugangsdaten in Ordnung sind, Sie das aber nicht dürfen: Der Bearbeiter hat keine Leserechte auf dieses Modul.

Bei einem 403 also nicht am Passwort herumdoktern. Gehen Sie zu den Berechtigungen dieses Bearbeiters und schauen Sie, welches Modul fehlt. Diese beiden wurden beim Bau von AureaDesk einmal verwechselt — das hat einen ganzen Nachmittag gekostet.

Paginierung in großen Umgebungen

In einer Umgebung mit ein paar tausend Incidents merken Sie nichts. In einer mit sechzigtausend schon. Große, stark genutzte Umgebungen können auf Paginierung anders reagieren, als ein kleiner Test vermuten lässt, und wenn Ihr Code davon ausgeht, dass jede Seite bis zur letzten sauber voll ist, bleibt er entweder hängen oder lässt stillschweigend Datensätze aus.

Die Lehre: Testen Sie nicht nur in Ihrer eigenen Umgebung. Was bei ein paar hundert Incidents funktioniert, kann sich bei Zehntausenden anders verhalten, und Sie merken es genau im falschen Moment.

Rechnen Sie auch damit, dass ein erster vollständiger Abruf aufwendiger ist als erwartet. Sechzigtausend Incidents auf einem kleinen Server abzuholen stößt an Speichergrenzen. Bauen Sie das also nicht als einen einzigen großen Vorgang.

Was Sie für die Anbindung brauchen

Sie brauchen keine spezielle Integrationslizenz. Was Sie anlegen, ist ein Bearbeiter, der ausschließlich für die Verbindung existiert, mit API-Zugriff und Leserechten auf die Module, die Sie lesen möchten. Dafür erzeugen Sie ein Anwendungspasswort, und das nutzt Ihre Verbindung.

Tun Sie das mit einem separaten Bearbeiter, nicht mit dem Konto einer Kollegin oder eines Kollegen. Aus zwei Gründen. In den Logs sehen Sie sofort, dass es die Verbindung war und keine Person. Und Sie können sie jederzeit abschalten, ohne dass jemand den eigenen Zugang verliert.

Halten Sie die Rechte so eng wie möglich. Berichte brauchen nie Schreibzugriff, und eine Verbindung, die nur liest, kann in Ihrem Prozess per Definition nichts kaputt machen.

Worauf es hinausläuft

Die API ist gut genug, um ein ordentliches Dashboard darauf zu bauen, solange Sie zwei Dinge akzeptieren. Sie müssen den Verlauf selbst nachhalten, wenn Sie wissen wollen, wo Arbeit hängen bleibt, und Sie müssen pro Umgebung prüfen, was verfügbar ist, statt der Dokumentation zu vertrauen.

Der erste Punkt ist der Grund, nicht zu warten. Jeder Monat, in dem Sie nicht angebunden sind, ist ein Monat, auf den Sie später nicht zurückblicken können.