TOPdesk-Anbindung einrichten

Die Anbindung TOPdesk verbindet octoja mit deiner TOPdesk-Umgebung, sodass aus Monitoring-Alarmen Incidents werden, in denen dein Service-Desk ohnehin schon arbeitet. Für die Einrichtung brauchst du drei Dinge: die Verbindung selbst, die Incident-Einstellungen und eine Alarmierungsregel, die Alarme an den TOPdesk-Kanal leitet.

Was die Anbindung leistet

Sobald verbunden und konfiguriert, erledigt die Anbindung drei getrennte Aufgaben:

• Erstellt einen Incident aus einem Alarm — wenn ein Monitoring-Check einen Alarm auslöst und eine Alarmierungsregel ihn an den TOPdesk-Kanal leitet, öffnet octoja einen Incident bei der zugeordneten TOPdesk-Niederlassung.
• Behandelt die Entwarnung — ist der Check wieder in Ordnung, kommentiert octoja diesen Incident immer und schließt ihn, wenn ihn noch niemand übernommen hat.
• Synchronisiert Geräte als TOPdesk-Assets — optional legt octoja einmal pro Stunde für jedes deiner Geräte ein Asset in TOPdesk Asset Management an oder aktualisiert es.

TOPdesk nennt seine Tickets Incidents, und octoja tut das in dieser Anbindung durchgehend genauso. Alarm- und Gerätedaten fließen ausschließlich ausgehend, von octoja nach TOPdesk: octoja ändert ausschließlich die Incidents, die es selbst erstellt hat, überträgt keine Änderungen aus TOPdesk zurück nach octoja und löscht dort niemals etwas.

Das Verbinden allein erstellt nichts. Eine verbundene Anbindung mit allen ausgefüllten Einstellungen erzeugt weiterhin null Incidents, solange keine Alarmierungsregel auf den TOPdesk-Kanal zeigt. Dieser Schritt ist Schritt 5 weiter unten — und derjenige, den man am häufigsten übersieht.

Voraussetzungen

• Die Berechtigung Integrationsverwaltung in octoja. Berechtigungen werden unter Administration → Gruppen zugewiesen.
• Zusätzlich die Berechtigung Kundenverwaltung, falls du auch Kunden aus TOPdesk importieren möchtest.
• Ein TOPdesk-Operator-Konto, unter dem octoja arbeitet, und ein dafür ausgestelltes Anwendungs-Passwort. Das Anwendungs-Passwort ist nicht das normale Login-Passwort dieses Operators — octoja braucht genau das Anwendungs-Passwort.
• Eine über HTTPS erreichbare TOPdesk-Umgebung. Reine http://-Adressen werden abgelehnt, im Dialog und noch einmal serverseitig.
• Zugriff auf die TOPdesk-Asset-Management-API, aber nur für die Gerätesynchronisierung. Asset Management ist getrennt von der Incident-API berechtigt.
• Einen Monitoring-Check, der bereits läuft, damit es überhaupt einen Alarm gibt, aus dem ein Incident werden kann.

Schritt 1 — TOPdesk-Zugangsdaten zusammenstellen

Sammle vorab drei Werte: den Login-Namen des TOPdesk-Operators, unter dem octoja arbeiten soll, das für diesen Operator ausgestellte Anwendungs-Passwort und die URL deiner TOPdesk-Umgebung.

Die Umgebungs-URL ist die Adresse, unter der du TOPdesk im Browser erreichst, in der Form https://firma.topdesk.net. Es gibt weder eine Vorgabe noch eine Regionsauswahl: TOPdesk hat keinen einheitlichen Host, octoja braucht also die Adresse deiner eigenen Instanz. Wo TOPdesk Anwendungs-Passwörter ausstellt und welche Lizenz die APIs abdeckt, beantwortet die TOPdesk-Dokumentation.

Schritt 2 — octoja mit TOPdesk verbinden

1. Öffne in octoja Administration → Integrationen und suche die Karte TOPdesk.
2. Klicke auf Einrichten. Der Dialog TOPdesk einrichten öffnet sich.
3. Fülle die drei Felder aus:

4. Klicke auf Verbindung testen. octoja ruft deine Umgebung mit den eingegebenen Zugangsdaten auf und meldet Verbindung erfolgreich. oder Verbindung fehlgeschlagen. mit dem Grund, den TOPdesk genannt hat.
5. Klicke auf Verbinden. octoja speichert die Zugangsdaten und öffnet die TOPdesk-Integrationsseite auf dem Reiter Konfiguration.

Verbindung testen ist optional — nutze es trotzdem. Verbinden speichert, was du eintippst, ohne bei TOPdesk nachzufragen, ob es funktioniert. Falsche Zugangsdaten lassen sich also völlig problemlos verbinden, und der Fehler zeigt sich erst später — als Auswahllisten, die leer bleiben, und Incidents, die nie ankommen. Eine Eigenheit dazu: Die Test-Schaltfläche tut gar nichts, solange eines der drei Felder noch leer ist, fülle also erst alle drei aus.

Der Test fragt deine Umgebung nach ihrer Version. Das belegt, dass URL und Zugangsdaten akzeptiert werden; es belegt nicht, dass die Incident-API oder Asset Management für diesen Operator offen sind.

Schritt 3 — Kunden TOPdesk-Niederlassungen zuordnen

In TOPdesk ist eine Niederlassung Kunde und Standort in einem: Ein octoja-Kunde wird also einer Niederlassung zugeordnet, und jeder octoja-Standort dieses Kunden kann eine eigene Niederlassung bekommen.

1. Suche auf dem Reiter Konfiguration den Bereich Kunden-Mapping.
2. Klicke auf Kunden zuordnen und ordne jedem octoja-Kunden seine TOPdesk-Niederlassung zu. Speichere den Dialog.
3. Klicke auf Standorte zuordnen, um den Standorten eines zugeordneten Kunden eigene Niederlassungen zu geben. Diese Schaltfläche bleibt deaktiviert, bis mindestens ein Kunde zugeordnet ist — ordne also zuerst die Kunden zu.

Im Standortdialog ergänzt … → Automatisch nach Name zuordnen eindeutige Namenszuordnungen aus der gesamten verfügbaren Niederlassungsliste. Bestehende Zuordnungen bleiben erhalten, mehrdeutige Treffer bleiben offen. Prüfe besonders gleichnamige Niederlassungen und speichere die Vorschläge erst nach der Kontrolle.

Die Zuordnung entscheidet, wo ein Incident landet, nicht ob er entsteht. Ein Gerät, dessen Kunde keine zugeordnete Niederlassung hat, erzeugt trotzdem einen Incident — er wird ohne Zuordnung angelegt, ohne Niederlassung und ohne Verknüpfung zu einem TOPdesk-Asset. Gehört das Gerät zu einem Standort mit eigener zugeordneter Niederlassung, landet der Incident bei dieser Standort-Niederlassung, sonst bei der Niederlassung des Kunden.

Die Gerätesynchronisierung ist an dieser Stelle strenger als die Incidents: Ein Kunde ohne zugeordnete Niederlassung wird dort komplett übersprungen.

Schritt 4 — Incident-Einstellungen wählen

Der Bereich Incident-Mapping bestimmt, wie ein Incident aussieht. Seine Einstellungen zerfallen in zwei Gruppen: wie der Incident priorisiert wird und wie er abgelegt wird.

Priorität und Dringlichkeit. Diese Einstellungen entscheiden darüber, ob überhaupt ein Incident entsteht.

Ist für eine Schwere weder eine Priorität noch eine Dringlichkeit gesetzt, entsteht aus Alarmen dieser Schwere nichts. Solche Alarme werden stillschweigend verworfen, ohne Meldung an irgendeiner Stelle außer dem fehlenden Eintrag auf dem Reiter Historie. Bleiben beide Warnungs-Felder leer, verschwinden Warnungs-Alarme, während kritische Alarme weiterhin funktionieren — und umgekehrt.

TOPdesk-Umgebungen mit einer Matrix aus Auswirkung und Dringlichkeit ermitteln die Priorität selbst, und octoja folgt dem: Sobald für die ausgelöste Schwere eine Dringlichkeit gesetzt ist, sendet octoja Auswirkung und Dringlichkeit und überhaupt keine Priorität — die gewählte Priorität wird dann ignoriert. Nur ohne gesetzte Dringlichkeit sendet octoja die Priorität direkt. Wähle die Prioritäten, wenn deine Umgebung keine Matrix hat, und die Dringlichkeiten, wenn sie eine hat.

Kategorie, Status und Sprache. Die ersten drei sind optional, und zwei davon ändern spürbar das Verhalten. Die Incident-Sprache hat immer einen Wert — sie startet auf English und lässt sich nicht leeren.

Einstellungen werden nicht automatisch gespeichert. Jede geänderte Auswahlliste bleibt lokal, bis du oben auf der Seite auf Einstellungen speichern klickst oder Strg+S drückst.

Gespeichert werden immer alle diese Felder auf einmal, auch die, die du nie angefasst hast. Eine Auswahlliste, deren Werte nicht aus TOPdesk geladen werden konnten, behält den bereits gespeicherten Wert — octoja sendet die hinterlegte ID erneut, Speichern löscht sie also nie; nur die Beschriftung fehlt, bis die Liste wieder geladen wird.

Schritt 5 — Alarme an den TOPdesk-Kanal leiten

Dieser Schritt sorgt dafür, dass Incidents entstehen. Alles bisherige hat nur octoja vorbereitet; kein Alarm erreicht TOPdesk, bevor ihn eine Alarmierungsregel dorthin schickt.

1. Öffne das Konfigurationspaket mit dem Check, für den du Incidents willst, wechsle zu seinem Reiter Checks und öffne den Check.
2. Wechsle zum Reiter Alarmierung des Checks und wähle oder erstelle eine Alarmierungskonfiguration.
3. Füge in dieser Konfiguration den Kanal TOPdesk-Incident hinzu.
4. Lege die Regel für den Kanal fest — den Anteil der jüngsten Ergebnisse und die Mindest-Schwere, die erreicht sein muss — und speichere den Check.

TOPdesk ist ein einzelner, mandantenweiter Kanal: Hast du TOPdesk-Incident gewählt, gibt es nichts weiter auszuwählen, kein Ziel und keine erneute Niederlassung. Der Kanal erscheint in der Auswahl nur, solange die Anbindung verbunden ist — verbinde also zuerst und öffne die Alarmierungskonfiguration danach, sonst fehlt der Eintrag in der Liste, ohne dass auf dem Bildschirm erklärt wird, warum.

Die vollständige Anleitung zu Alarmierungskonfigurationen, Regeln und Zeitplänen findest du unter Alarmierung für einen Check einrichten.

Ein Incident, den octoja erstellt, trägt den Titel octoja: check "<Check>" on <Gerät> reported <Status>. Der Anfragetext nennt den Check, das Gerät, den gemeldeten Status und wie viele der letzten Läufe fehlgeschlagen sind, gefolgt von der Ausgabe des Checks und einem Link zurück auf das Gerät in octoja — beides in der eingestellten Incident-Sprache. Hält TOPdesk Asset Management bereits ein Asset für dieses Gerät — gefunden zuerst über die Seriennummer, dann über den Hostnamen, und zwar irgendwo in TOPdesk statt nur in dieser Niederlassung —, verknüpft octoja den Incident damit; gibt es keines, entsteht der Incident ohne Verknüpfung, statt fehlzuschlagen.

Was bei einer Entwarnung passiert

Die Entwarnung besteht aus zwei Schritten; der Kommentar wird immer ergänzt.

Angefasst werden nur Incidents, die octoja für diesen Alarm erstellt hat. Entstand gar kein Incident — weil für diese Schwere weder Priorität noch Dringlichkeit gesetzt war —, gibt es nichts zu kommentieren, und die Erholung geht in TOPdesk spurlos vorüber.

Erholungen funktionieren auch dann weiter, wenn octoja wegen wiederholter Fehler keine neuen Incidents mehr erstellt. Offene Incidents bekommen weiterhin ihren Kommentar und werden weiterhin geschlossen, solange die Verbindung steht.

Der Erholungs-Kommentar wird immer auf Englisch geschrieben, unabhängig davon, was du unter Incident-Sprache gewählt hast. Diese Einstellung gilt nur für Titel und Text des Incidents.

Schritt 6 — Geräte als TOPdesk-Assets synchronisieren (optional)

Die Gerätesynchronisierung legt fehlende Assets in TOPdesk Asset Management aus deinen octoja-Geräten an. Standardmäßig ist sie aus, und sie braucht drei Dinge statt einem.

1. Wähle unter Gerätevorlagen für jede Geräteklasse, die du synchronisieren möchtest, eine TOPdesk-Asset-Vorlage. Aufgeführt sind alle fünfzehn Klassen, von Windows Server, Windows Workstation und Linux Server über macOS, Switch und Firewall bis NAS, ESXi und IP-Kamera. Neue Assets werden aus der zugeordneten Vorlage angelegt, nicht gesetzte Klassen werden übersprungen.
2. Schalte im Bereich Geräte-Sync die Option Geräte stündlich automatisch synchronisieren ein.
3. Klicke auf Einstellungen speichern.

Der Schalter allein bewirkt nichts: Ist für keine Geräteklasse eine Vorlage gesetzt, bricht der ganze Lauf ab, bevor er beginnt.

Die Synchronisierung läuft nach einem stündlichen Zeitplan statt auf Zuruf, der erste Lauf folgt also innerhalb einer Stunde nach dem Speichern. Für jeden zugeordneten Kunden legt octoja je Gerät ein Asset an oder aktualisiert es und schreibt Hostname, Seriennummer, primäre IP-Adresse und Betriebssystem. Werte, die ein Gerät nicht hat, bleiben weg.

Ein vorhandenes Asset wird zuerst über die Seriennummer und dann über den Hostnamen erkannt. Ein Treffer allein über den Hostnamen — der auftritt, wenn das octoja-Gerät selbst keine Seriennummer hat — zählt nur, wenn dieses TOPdesk-Asset bereits in der Niederlassung des Kunden liegt; sonst behandelt octoja es als anderes Gerät und legt ein neues Asset an. Neue Assets entstehen aus der zugeordneten Vorlage und werden anschließend der Niederlassung zugewiesen, während bereits vorhandene Assets ihre Niederlassung behalten und nur ihre Hardware-Felder aufgefrischt bekommen. Assets werden nie gelöscht — entfernst du ein Gerät in octoja, räume sein Asset in TOPdesk selbst auf.

Geräte ohne Namen werden übersprungen, ebenso Geräte, deren Klasse keine Vorlage hat. Ein einzelnes fehlschlagendes Gerät stoppt den Lauf nicht: Die übrigen werden weiterhin übertragen, und der Lauf gilt trotzdem als erfolgreich.

Jeder Lauf erscheint auf dem Reiter Historie als Eintrag Geräte-Sync, und der Bereich Geräte-Sync zeigt, wann der letzte beendet wurde.

Kunden aus TOPdesk importieren

Existieren deine Kunden in octoja noch nicht, kannst du sie aus deinen TOPdesk-Niederlassungen übernehmen. Das liegt auf der Seite Kunden, nicht auf der Integrationsseite.

1. Öffne Kunden und wähle Aus Ticketsystem importieren.
2. Markiere die gewünschten TOPdesk-Niederlassungen und bestätige den Import.

Jede ausgewählte Niederlassung wird zu einem octoja-Kunden, und ihre Zuordnung wird automatisch angelegt — ein importierter Kunde braucht damit keine Zuordnung von Hand aus Schritt 3. Bereits importierte Niederlassungen werden markiert und übersprungen, ebenso Niederlassungen, die es in TOPdesk nicht mehr gibt.

Der Menüpunkt öffnet das erste verbundene Ticketsystem in einer festen Reihenfolge: DocBee, HaloPSA, Inserve, Autotask PSA, Codemeta OS, Odoo, Jira, TOPdesk, TANSS, c-entron Service-Board, Freshservice, Zammad. TOPdesk steht an achter Stelle: Ist eines der sieben davor ebenfalls verbunden, öffnet sich dessen Import-Dialog, und TOPdesk-Niederlassungen tauchen nie auf. Eine Auswahl dafür gibt es nicht.

Wenn keine Incidents mehr ankommen

Der Reiter Historie listet die jüngsten Incident-, Erholungs- und Geräte-Sync-Versuche mit Ergebnis, Statuscode und Antwort auf und ist die Anlaufstelle, wenn ein erwarteter Incident fehlt. Zustellungen lassen sich von dort nicht wiederholen, eine Zustellung ohne verbleibende Versuche ist also endgültig.

• Gar keine Incidents. Prüfe, ob eine Alarmierungskonfiguration am Check den Kanal TOPdesk-Incident wirklich enthält und ob für die ausgelöste Schwere eine Priorität oder eine Dringlichkeit gesetzt ist. Das sind mit Abstand die häufigsten Ursachen.
• Eine Zustellung ist fehlgeschlagen. octoja wiederholt eine fehlgeschlagene Incident-Erstellung oder Erholung nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 12 Stunden und 24 Stunden. Fehler, die TOPdesk als Fehler des Aufrufers meldet, werden nicht wiederholt, weil eine Wiederholung nichts an der Antwort ändern würde. Eine fehlgeschlagene Gerätesynchronisierung wird ebenfalls nicht wiederholt — der nächste stündliche Lauf fängt sie auf.
• Die Karte zeigt den Status Pausiert. Nach 20 aufeinanderfolgenden fehlgeschlagenen Zustellungen erstellt octoja keine Incidents mehr, damit eine kaputte Verbindung nicht dauerhaft gegen TOPdesk läuft. Eine Schaltfläche zum Fortsetzen gibt es nicht: Nutze TOPdesk trennen und verbinde erneut mit funktionierenden Zugangsdaten. Zuordnungen und Einstellungen überleben diesen Umweg, es muss also nichts doppelt eingerichtet werden.
• Alle Auswahllisten sind leer. Die Listen werden live aus TOPdesk geholt, eine leere Seite heißt also, dass die hinterlegten Zugangsdaten nicht mehr akzeptiert werden. Trenne die Verbindung, verbinde erneut und teste diesmal vorab.
• Nur die Gerätevorlagen sind leer. Die Verbindung ist in Ordnung, und die Asset-Management-API ist für diesen Operator nicht offen — sie ist in TOPdesk getrennt berechtigt.
• Incidents kommen ohne Niederlassung an. Der Kunde des Geräts hat keine zugeordnete Niederlassung. Ordne ihn in Schritt 3 zu.

TOPdesk trennen

Um die Verbindung zu entfernen, öffne die TOPdesk-Integrationsseite, scrolle zur Gefahrenzone und klicke auf TOPdesk trennen, dann bestätige mit Trennen.

Entfernt werden nur die Zugangsdaten. Deine Kunden- und Standortzuordnungen, die Gerätevorlagen, sämtliche Incident-Einstellungen und die Zustellhistorie bleiben genau so erhalten, wie sie waren, und jeder bereits erstellte Incident und jedes Asset bleibt in TOPdesk. Ein späteres erneutes Verbinden bedeutet nur, Login-Namen, Anwendungs-Passwort und Umgebungs-URL noch einmal einzutragen.

Tipps

• Decke beide Schweren ab — zwei Prioritäten oder zwei Dringlichkeiten — außer du willst bewusst nur für eine Schwere Incidents.
• Trage Prioritäten und Dringlichkeiten nicht gemeinsam ein in der Erwartung, dass beides greift. Die Dringlichkeit gewinnt, die Priorität entfällt.
• Klicke nach jeder Änderung auf Einstellungen speichern — eine geänderte, aber nicht gespeicherte Auswahl wirkt sich auf den nächsten Alarm nicht aus.
• Lass Status beim Schließen bei Erholung leer, wenn dein Team Incidents lieber von Hand schließt; die Erholung wird trotzdem am Incident kommentiert.
• Ordne Kunden zu, bevor du Standorte zuordnest — die Standort-Schaltfläche ist deaktiviert, bis der erste Kunde zugeordnet ist.
• Namen von Niederlassungen, Prioritäten, Kategorien und Status kommen direkt aus TOPdesk und lesen sich daher genau so, wie sie dort heißen. Die Einstellung Incident-Sprache übersetzt sie nicht.