HaloPSA-Anbindung einrichten

Die Anbindung HaloPSA verbindet octoja mit deiner HaloPSA-Instanz, sodass aus Monitoring-Alarmen Tickets werden, in denen dein Team ohnehin schon arbeitet. Für die Einrichtung brauchst du drei Dinge: die Verbindung selbst, die Ticket-Einstellungen und eine Alarmierungsregel, die Alarme an HaloPSA leitet.

Was die Anbindung leistet

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

• Erstellt ein Ticket aus einem Alarm — wenn ein Monitoring-Check einen Alarm auslöst und eine Alarmierungsregel ihn an den HaloPSA-Kanal leitet, öffnet octoja ein Ticket beim zugeordneten HaloPSA-Client.
• Behandelt die Entwarnung — ist der Check wieder in Ordnung, ergänzt octoja immer eine Notiz an diesem Ticket und schließt das Ticket, solange es noch niemand übernommen hat.
• Synchronisiert Geräte als Assets — optional legt octoja einmal pro Stunde für die Geräte jedes Kunden, den du einem HaloPSA-Client zugeordnet hast, ein HaloPSA-Asset an oder aktualisiert es.

Alarmbehandlung und Asset-Sync laufen ausgehend, von octoja nach HaloPSA. octoja fasst ausschließlich die Tickets an, die es selbst erstellt hat, und löscht in HaloPSA niemals etwas. Es liest sehr wohl aus HaloPSA, wo es das braucht: die Listen, die seine Auswahllisten füllen, die Assets eines zugeordneten Clients, damit ein Ticket oder ein Sync das richtige findet, den zugewiesenen Agenten an einem Ticket, das es gerade schließen will, und — falls du den Kundenimport weiter unten nutzt — die Clients und Sites, die es nach octoja kopiert.

Das Verbinden allein erstellt nichts. Eine verbundene Anbindung mit allen ausgefüllten Einstellungen erzeugt weiterhin null Tickets, solange keine Alarmierungsregel auf den HaloPSA-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.
• Die Berechtigung Alarmierungsverwaltung, damit du die Alarmierungsregel aus Schritt 5 anlegen kannst.
• Zusätzlich die Berechtigung Kundenverwaltung, falls du auch Kunden aus HaloPSA importieren möchtest.
• Eine HaloPSA-Instanz, die über HTTPS erreichbar ist. Eine Instanz-URL mit http:// wird beim Verbinden abgelehnt.
• Eine in HaloPSA registrierte API-Anwendung, die den OAuth-Client-Credentials-Flow nutzt, sowie deren Client-ID und Client-Secret. HaloPSA erzeugt beide Werte; octoja legt sie nie selbst an. Wo API-Anwendungen im HaloPSA-Menü liegen und welche HaloPSA-Edition oder Berechtigungsstufe sie brauchen, entscheidet sich auf der HaloPSA-Seite — sieh im Zweifel in der HaloPSA-Dokumentation nach.
• Mindestens einen Asset-Typ, eine Priorität, einen Ticket-Status und einen Tickettyp in HaloPSA. octoja befüllt seine Auswahllisten live aus deiner Instanz und legt keine eigenen Standardwerte an.
• Einen Monitoring-Check, der bereits läuft, damit es überhaupt einen Alarm gibt, aus dem ein Ticket werden kann.

Schritt 1 — HaloPSA-Zugangsdaten zusammenstellen

Sammle drei Werte: die URL deiner HaloPSA-Instanz sowie die Client-ID und das Client-Secret der dort registrierten API-Anwendung. octoja tauscht sie gegen ein kurzlebiges API-Token mit dem Scope all ein; ein Benutzername oder Passwort wird nicht gebraucht.

Kopiere das Client-Secret sorgfältig. octoja speichert es genau so, wie du es einfügst, samt eines versehentlichen Leerzeichens am Anfang oder Ende — ein Secret mit unsichtbaren Leerzeichen lässt sich klaglos verbinden, authentifiziert sich aber nie.

Schritt 2 — octoja mit HaloPSA verbinden

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

4. Klicke auf Verbindung testen. octoja holt sich mit den eingegebenen Zugangsdaten ein Token von HaloPSA und meldet Verbindung erfolgreich. oder den Fehler, den HaloPSA zurückgegeben hat.
5. Klicke auf Verbinden. octoja speichert die Zugangsdaten und öffnet die HaloPSA-Integrationsseite auf dem Reiter Konfiguration.

Verbindung testen ist optional — nutze es trotzdem. Verbinden prüft deine Zugangsdaten nicht: octoja speichert, was du eintippst, ohne bei HaloPSA nachzufragen, ob es funktioniert. Falsche Zugangsdaten lassen sich völlig problemlos verbinden, und der Fehler zeigt sich erst danach — als Auswahllisten auf der Konfigurationsseite, die hartnäckig leer bleiben. Ein Fehler-Banner gibt es dafür nicht: Die Abfragen scheitern bewusst leise, damit die Seite weiterhin lädt und die Verbindung entfernt werden kann. Ein Klick auf Verbindung testen vor dem Verbinden macht aus einer Stunde Fehlersuche eine klare Fehlermeldung.

Schritt 3 — Kunden HaloPSA-Clients zuordnen

octoja muss wissen, welcher HaloPSA-Client zu welchem deiner Kunden gehört, damit Tickets beim richtigen landen.

1. Suche auf dem Reiter Konfiguration den Bereich Client-Zuordnung.
2. Klicke auf Clients zuordnen und ordne jedem octoja-Kunden seinen HaloPSA-Client zu. Speichere den Dialog.
3. Klicke auf Standorte zuordnen, um die octoja-Standorte eines Kunden HaloPSA-Sites zuzuordnen. Diese Schaltfläche bleibt deaktiviert, bis mindestens ein Client zugeordnet ist — ordne also zuerst die Clients zu.

Im Standortdialog ergänzt … → Automatisch nach Name zuordnen eindeutige Namenszuordnungen innerhalb des jeweiligen Kunden. Bestehende Zuordnungen bleiben erhalten, mehrdeutige Treffer bleiben offen. Prüfe die Vorschläge und speichere den Dialog.

Ein nicht zugeordneter Kunde bekommt trotzdem ein Ticket. Anders als bei manchen anderen Anbindungen überspringt octoja den Alarm nicht — es öffnet das Ticket ohne Client, ohne Site und ohne Asset-Verknüpfung. Das Ergebnis ist ein verwaistes Ticket in HaloPSA statt gar keinem, was leicht übersehen wird, bis sich jemand wundert, woher diese nicht zugeordneten Tickets kommen.

Zuordnungen speichert jeweils der Dialog, in dem du gerade bist. Die Schaltfläche Einstellungen speichern oben auf der Seite deckt nur die Ticket-Einstellungen ab — Client- und Standortzuordnungen speichert sie nicht.

Schritt 4 — Ticket-Einstellungen wählen

Der Bereich Ticket-Zuordnung bestimmt, wie ein Ticket aussieht. Mehrere dieser Einstellungen sind harte Voraussetzungen: Fehlt eine davon, überspringt octoja das Ticket vollständig.

Setze mindestens den Status für neue Tickets, den Tickettyp und die Priorität für die Schwere, auf die du alarmiert werden willst. Setze beide Prioritäten, wenn du Tickets für Warnung und Kritisch gleichermaßen möchtest.

Ein übersprungenes Ticket hinterlässt keine Spur. Fehlt eine der Pflichteinstellungen, bricht octoja ab, bevor es HaloPSA überhaupt kontaktiert, und auf dem Reiter Historie erscheint nichts — eine unvollständige Konfiguration sieht damit genauso aus wie ein Alarm, der nie ausgelöst hat. Fehlen Tickets und ist die Historie leer, prüfe zuerst diesen Bereich.

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.

Die Prioritätsliste ist kürzer als die eigene Prioritätsliste in HaloPSA, und das ist Absicht. HaloPSA liefert eine Zeile je SLA, dieselbe Prioritätsstufe taucht dort also mehrfach auf; octoja fasst sie zu je einem Eintrag zusammen.

Schritt 5 — Alarme an den HaloPSA-Kanal leiten

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

1. Öffne das Konfigurationspaket mit dem Check, für den du Tickets 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 HaloPSA-Ticket hinzu.
4. Lege die Regel für den Kanal fest — den Anteil der fehlgeschlagenen Ergebnisse, gezählt entweder über eine Anzahl jüngster Läufe oder über einen Zeitraum, und die Mindest-Schwere, die erreicht sein muss — und speichere den Check.

HaloPSA ist ein einzelner, mandantenweiter Kanal: Hast du HaloPSA-Ticket gewählt, gibt es nichts weiter auszuwählen, kein Ziel und keine erneute Warteschlange. Der Kanal erscheint in der Auswahl nur, solange die Anbindung verbunden ist.

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

Ein Ticket, das octoja öffnet, trägt die Zusammenfassung octoja: check "<Check>" reported <Status> on <Gerät>. Die Details nennen 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 die Check-Seite des Geräts in octoja. Der Ticket-Text ist immer englisch, unabhängig davon, welche Sprache in octoja eingestellt ist.

Die Platzierung folgt deinen Zuordnungen. Das Ticket geht an den zugeordneten Client, übernimmt die HaloPSA-Site, wenn der octoja-Standort des Geräts zugeordnet ist, und wird mit einem HaloPSA-Asset verknüpft, wenn dieser Client eines hat, dessen Inventarnummer dem Hostnamen des Geräts entspricht — bevorzugt das Asset an der zugeordneten Site. octoja sucht nur innerhalb des zugeordneten Clients, nie über die ganze Instanz, gleiche Hostnamen bei verschiedenen Clients können also nicht kollidieren.

Was bei einer Entwarnung passiert

Die Entwarnung besteht aus zwei Schritten; die Notiz wird immer ergänzt.

Die Erholungsnotiz ist nicht privat. octoja legt sie als HaloPSA-Aktion mit dem Ergebnis Internal Note ab, lässt sie aber für den Endanwender sichtbar — ein Kunde, der das Ticket in deinem HaloPSA-Portal liest, sieht sie also ebenfalls.

Angefasst wird nur das Ticket, das octoja für diesen Alarm erstellt hat. Wurde das ursprüngliche Ticket übersprungen — weil eine Pflichteinstellung fehlte —, gibt es nichts zu kommentieren, und die Erholung geht in HaloPSA spurlos vorüber.

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

Der Asset-Sync gleicht die Assets in HaloPSA stündlich mit deinen octoja-Geräten ab. Standardmäßig ist er aus, und er braucht zwei Einstellungen statt einer.

1. Wähle unter Geräte-Asset-Typen für jede Geräteklasse, die du synchronisieren möchtest, einen HaloPSA-Asset-Typ — Windows Server, Windows Workstation, Linux Server, macOS, Switch, Firewall und so weiter. Nicht zugeordnete Klassen werden übersprungen, und keine davon ist voreingestellt.
2. Schalte im Bereich Asset-Sync die Option Geräte automatisch stündlich synchronisieren ein.
3. Klicke auf Einstellungen speichern.

Die Synchronisierung läuft nach einem stündlichen Zeitplan statt auf Zuruf, und einen Lauf von Hand auszulösen ist nicht möglich — der erste Lauf folgt also innerhalb einer Stunde nach dem Speichern. Für jeden zugeordneten Client legt octoja je Gerät ein Asset an oder aktualisiert es und schreibt den Client, den zugeordneten Asset-Typ, den Hostnamen als Inventarnummer des Assets und die zugeordnete HaloPSA-Site.

Das ist der gesamte Inhalt. Betriebssystem, IP-Adresse, MAC-Adresse und Seriennummer werden nicht geschrieben, weil sie in instanzspezifischen HaloPSA-Zusatzfeldern liegen, die keine übertragbaren Namen haben.

Vorhandene Assets werden über den Hostnamen innerhalb des Clients erkannt, bevorzugt eines an derselben Site. Geräte ohne Namen sowie Geräte, deren Klasse keinen Asset-Typ zugeordnet hat, werden übersprungen. Assets werden nie gelöscht — nimmst du ein Gerät in octoja außer Betrieb, räume sein HaloPSA-Asset selbst auf. Zwei Geräte mit gleichem Hostnamen im selben Client und an derselben Site fallen auf ein einziges Asset zusammen.

Jeder Lauf wird auf dem Reiter Historie als Eintrag Geräte-Sync mit den Zählern für angelegt, aktualisiert und übersprungen festgehalten, und der Bereich Asset-Sync zeigt, wann der letzte Lauf beendet wurde. Ein Lauf, in dem jedes Gerät übersprungen wurde, gilt trotzdem als Erfolg — lies also die Zähler statt des Ergebnis-Badges.

Kunden aus HaloPSA importieren

Existieren deine Kunden in octoja noch nicht, kannst du sie aus deinen HaloPSA-Clients ü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 HaloPSA-Clients und bestätige den Import.

Jeder ausgewählte Client wird zu einem octoja-Kunden, seine HaloPSA-Sites werden zu octoja-Standorten, und sowohl die Client- als auch die Standortzuordnungen werden automatisch angelegt — ein importierter Kunde braucht damit keine Zuordnung von Hand aus Schritt 3. Bereits importierte Clients werden markiert und übersprungen.

Der Menüpunkt öffnet das erste verbundene Ticketsystem in einer festen Reihenfolge: DocBee, HaloPSA, Inserve, Autotask, Codemeta OS, Odoo, Jira, TOPdesk, TANSS, c-entron Service-Board, Freshservice, Zammad. HaloPSA steht an zweiter Stelle, nur ein verbundenes DocBee hat also Vorrang.

Die Bestätigung zählt die tatsächlich angelegten Kunden, nicht die angehakten Clients. Zehn ausgewählte Clients, von denen sieben schon importiert waren, melden also völlig korrekt drei.

Wenn keine Tickets mehr ankommen

Der Reiter Historie listet die jüngsten Ticket-, Erholungs- und Geräte-Sync-Versuche mit Ergebnis und Antwort auf und ist die Anlaufstelle, wenn ein erwartetes Ticket fehlt.

• Alle Auswahllisten sind leer. Die hinterlegten Zugangsdaten funktionieren nicht mehr, daher können die Live-Abfragen nicht laden. Ein Banner gibt es dafür nicht — die leeren Listen sind das Symptom. Trenne die Verbindung und verbinde erneut mit funktionierenden Zugangsdaten, diesmal mit einem Klick auf Verbindung testen vorab.
• Verbindung testen meldet einen ungültigen Client. octoja hält das API-Token stundenlang vor, gerade weil HaloPSA einen OAuth-Client sperrt, der zu oft nach Tokens gefragt wird. Warte ein paar Minuten, statt wiederholt zu klicken.
• Eine Zustellung ist fehlgeschlagen. octoja wiederholt eine fehlgeschlagene Ticket-Erstellung oder Erholung nach 1 Minute, 5 Minuten, 30 Minuten, 2 Stunden, 12 Stunden und 24 Stunden. Fehler, die HaloPSA als Fehler des Aufrufers meldet, werden nicht wiederholt, weil eine Wiederholung nichts an der Antwort ändern würde. Ein fehlgeschlagener Asset-Sync wird ebenfalls nicht wiederholt — der nächste stündliche Lauf fängt ihn auf.
• Die Karte zeigt den Status Pausiert. Nach 20 aufeinanderfolgenden fehlgeschlagenen Zustellungen öffnet octoja keine Tickets mehr, damit eine kaputte Verbindung nicht dauerhaft gegen HaloPSA läuft. Fehlgeschlagene Asset-Syncs zählen ebenfalls mit, ein kaputter Sync kann also die Ticketerstellung stoppen. Erholungen an bereits offenen Tickets funktionieren weiter. Eine Schaltfläche zum Fortsetzen gibt es nicht: Nutze HaloPSA trennen und verbinde erneut, wobei du das Client-Secret noch einmal einträgst. Zuordnungen und Einstellungen überleben diesen Umweg, nur die Zugangsdaten musst du erneut liefern.
• Tickets kommen in HaloPSA ohne Client an. Der octoja-Kunde dahinter hat keine Client-Zuordnung. Ordne ihn wie in Schritt 3 beschrieben zu — die bereits entstandenen verwaisten Tickets bleiben, wie sie sind.
• Gar keine Tickets, und die Historie ist leer. Prüfe, ob Status für neue Tickets, Tickettyp und die Priorität für die jeweilige Schwere gesetzt sind und ob eine Alarmierungskonfiguration am Check den Kanal HaloPSA-Ticket wirklich enthält.

HaloPSA trennen

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

Entfernt werden nur die Zugangsdaten. Deine Client- und Standortzuordnungen, sämtliche Ticket- und Sync-Einstellungen sowie die Zustellhistorie bleiben genau so erhalten, wie sie waren, und jedes bereits erstellte Ticket und Asset bleibt in HaloPSA. Ein späteres erneutes Verbinden bedeutet, den Einrichtungsdialog komplett neu auszufüllen — halte das Client-Secret also bereit, bevor du trennst.

Tipps

• Klicke jedes Mal auf Verbindung testen, bevor du auf Verbinden klickst. Das ist die einzige Live-Prüfung, die octoja bei der Einrichtung gegen HaloPSA macht.
• Füge das Client-Secret ohne führende oder abschließende Leerzeichen ein — octoja behält sie genau so bei, und die Token-Anfrage schlägt dann fehl.
• Klicke nach jeder Änderung auf Einstellungen speichern — eine geänderte, aber nicht gespeicherte Auswahl wirkt sich auf den nächsten Alarm nicht aus.
• Setze sowohl Priorität für Warnung als auch Priorität für Kritisch, außer du willst bewusst nur für eine Schwere Tickets.
• Ordne deine Clients zu, bevor du dich auf Tickets verlässt. Ein nicht zugeordneter Kunde erzeugt verwaiste Tickets statt gar keiner, und das übersieht man leicht.
• Lass Status beim Schließen nach Erholung leer, wenn dein Team Tickets lieber von Hand schließt — die Erholung wird trotzdem am Ticket vermerkt.