PKR-Lab

ALAMOS-Einsatzalarm → Zammad-Ticket (n8n)

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/3-apps-workloads/300h0-alamos-einsatz-zammad.md

ALAMOS-Einsatzalarm → Zammad-Ticket (n8n)

Cluster: TECH · Ordner argocd/apps/tech/n8n/workflows/ · Zugang: n8n-Workflow, Webhook über alamos-relay. kubectl-Befehle in diesem Doc gelten für den TECH-Cluster (Zugriff je Cluster).

Erweitert die reine Kiosk-Anzeige aus
30010-alamos-apager.md um eine
Push-Benachrichtigung: Kommt in ALAMOS AMweb ein echter Einsatz rein, legt
ein n8n-Workflow automatisch ein Zammad-Ticket mit den mitgelieferten
Einsatzdaten an — die Mail-Benachrichtigung übernimmt danach Zammads
eigene Agenten-Benachrichtigung, wie bei den anderen n8n→Zammad-Workflows
in diesem Repo (siehe 30070-n8n.md).

Wichtige Einschränkung, bevor ihr das aufsetzt: Welche Felder ALAMOS
AMweb im Webhook tatsächlich mitliefert (Adresse, Fahrzeuge, Meldebild,
...), war ohne einen eingeloggten Alamos-Account nicht zu ermitteln — nur
keyword (Einsatzstichwort) und unit (Einheit) sind laut öffentlichem
Handbuch als Standard-Platzhalter dokumentiert. Der Workflow ist deshalb
bewusst datenoffen gebaut: er gibt alle Felder aus, die der Webhook
mitliefert, unabhängig davon, wie sie heißen. Die vollständige Recherche
inkl. offener Fragen steht in
capulus-core/4-planung/40060-alamos-einsatz-email-benachrichtigung.md.

Architektur

Der einzige Auslöser dieses Workflows ist der ALAMOS-Webhook selbst —
kein Polling.
Ohne die Ziel-URL im Alamos-Account einzutragen (siehe
Einrichtung, Schritt 5) läuft der Workflow nie an und es
entsteht nie ein Ticket, egal wie viele echte Einsätze reinkommen.

Update — direkter Aufruf hat sich als nicht zuverlässig erwiesen, Fix:
alamos-relay.
Der ursprünglich hier
empfohlene direkte Aufruf von n8n.prod.homeserver aus AMweb heraus hat in
der Praxis nicht funktioniert (vermutlich genau das unten beschriebene
Private-Network-Access-Problem, ggf. auch weil "Allgemeine Webhooks"
serverseitig von Alamos' Cloud statt aus dem Browser-Tab feuert). Statt n8n
selbst öffentlich zu machen — was die bewusste Entscheidung „n8n nicht aus dem Internet erreichbar“ aufheben würde
(c0030: aus dem Cloudflare-Tunnel entfernt, Security) — steht jetzt ein eigener, minimaler Proxy dazwischen:
alamos-relay. Die Ziel-URL in der
Alamos-Webhook-Konfiguration zeigt seitdem auf das Relay, nicht mehr auf
n8n.prod.homeserver direkt
(siehe Einrichtung unten,
Schritt 4). Der Rest dieses Abschnitts (welche Webhook-Variante, warum,
das PNA-Risiko) bleibt als Hintergrund stehen — er erklärt, warum das
Relay überhaupt nötig wurde.

Empfehlung: AMweb-Seiteneinstellung-Webhook nutzen, nicht "Allgemeine
Webhooks"
— nur für Ersteren ist öffentlich dokumentiert, dass der Aufruf
aus dem Browser-Tab heraus feuert, also von der Kiosk-Chromium-Session
selbst, die ohnehin schon im LAN/Tailscale hängt und *.homeserver
auflöst (identisch dazu, wie der Kiosk die echte AMweb-Seite lädt). Bei
"Allgemeine Webhooks" (Account-Ebene) war öffentlich nicht zu klären, ob
der Call stattdessen von Alamos' Cloud-Servern selbst kommt (also wirklich
aus dem öffentlichen Internet) — seit dem Umweg über
alamos-relay ist das allerdings für beide
Varianten egal: die Ziel-URL ist so oder so öffentlich erreichbar, ohne
dass n8n selbst öffentlich wird.

Zusätzliches Risiko, unabhängig von der Webhook-Variante — Private
Network Access:
Die AMweb-Seite selbst wird von einer öffentlichen
Origin (amweb.alamos.cloud o. ä.) geladen. Moderne Chromium-Versionen
blockieren per Private Network Access standardmäßig JS-Requests
(fetch/XHR) von einer öffentlichen Seite zu einer privaten
Netzwerk-Adresse — und n8n.prod.homeserver löst intern auf eine private
IP auf. Das deckt sich vermutlich mit der Handbuch-Warnung "Aufruf lokaler
URLs... wird i. d. R. vom Browser aus Sicherheitsgründen blockiert" (die
könnte mehr meinen als nur localhost). Genau dieses Problem löst
alamos-relay:
dessen öffentlicher Hostname
löst auf eine Cloudflare-IP auf, PNA greift also nicht mehr, unabhängig
davon, ob der Call aus dem Kiosk-Browser-Tab oder direkt von Alamos'
Cloud-Servern kommt.

ALAMOS AMweb (Cloud-Dienst)
   │  Webhook, GET oder POST, nur bei echten Alarmen
   │  (AMweb-Seiteneinstellung ODER "Allgemeine Webhooks" im Alamos-Admin)
   │  Ziel-URL MUSS dort eingetragen sein, siehe Einrichtung Schritt 4-5
   ▼
https://alamos-relay-prod.pke-lab.de/relay/<TOKEN>
   │  alamos-relay (öffentlich erreichbarer Proxy, siehe 300i0) —
   │  Server-zu-Server-Forward, kein Browser/PNA mehr im Spiel
   ▼
http://n8n.prod.homeserver/webhook/alamos-einsatz
   │
   ├─ Webhook (GET)  ─┐
   ├─ Webhook (POST) ─┤  beide Trigger teilen sich denselben Pfad
   │                   ▼
   │        Code-Node "Einsatzdaten aufbereiten"
   │          - führt Query-Parameter (GET) und JSON-Body (POST) zusammen
   │          - baut Ticket-Titel aus keyword/unit, falls vorhanden
   │          - gibt ALLE empfangenen Felder unverändert im Ticket-Text aus
   │          - filtert Mehrfach-Auslösungen desselben Alarms innerhalb von
   │            2 Minuten (Workflow-Static-Data, siehe unten)
   ▼
Zammad-Ticket erstellen (nativer n8n-nodes-base.zammad-Node, Ticket→Create,
                          Gruppe Support::Administration)
   │
   ▼
Zammads Agenten-Benachrichtigung → Mail an [email protected]

Workflow-Datei:
argocd/apps/tech/n8n/workflows/alamos-einsatz-to-zammad.json.
Nutzt bewusst den nativen n8n-nodes-base.zammad-Node (wie
nightly-worker-update-to-zammad.json/yearly-secrets-rotation-reminder.json),
nicht den rohen HTTP-Request-Node wie im älteren
banana-pi-down-to-zammad.json — andere Credential (Typ „Zammad Token Auth
API“ statt Header-Auth), siehe Einrichtung.

Warum zwei Webhook-Trigger auf demselben Pfad

Ob eure Alamos-Konfiguration den Alarm per GET (Query-Parameter) oder POST
(JSON-Body) verschickt, hängt davon ab, welche der beiden
Webhook-Varianten ihr einrichtet (siehe Planungsdokument). Beide
Trigger-Nodes registrieren denselben Pfad alamos-einsatz, aber
unterschiedliche HTTP-Methoden — dadurch funktioniert der Workflow mit
beiden Varianten, ohne dass vorher geklärt sein muss, welche ihr nutzt.

Leere Test-Calls werden übersprungen, nicht geticketet

Fehlen sowohl keyword als auch unit im zusammengeführten Payload,
bricht der Code-Node ohne Ticket ab (return [], kein Fehler) — nur
eine console.log-Zeile mit den Rohdaten landet im Execution-Log. Das
deckt Verbindungstests ab, die keine echten Einsatzdaten mitschicken (z. B.
ein reiner curl gegen alamos-relay ohne
Query-Parameter, oder eine Alamos-"Webhook Test"-Funktion ohne konkrete
Alarmauswahl) — genau das ist beim ersten Verbindungstest des Relays
passiert (leerer GET-Call, alamos-relay antwortete 200, aber ohne
diesen Guard hätte der Code-Node trotzdem ein Ticket mit leerem Titel
erzeugt). Bewusst kein Error/Exception: ein console.log statt eines
harten Fehlers, damit ein Test-Call nicht wie ein defekter Workflow
aussieht, aber trotzdem im Execution-Log nachvollziehbar bleibt — falls
ein echter Alarm aus unerwarteten Gründen (z. B. andere Feldnamen als
keyword/unit) denselben Weg nimmt, ist das damit nicht komplett
unsichtbar, sondern zumindest im Log sichtbar, nur eben nicht per Ticket.

Duplikat-Schutz

Falls der Webhook pro geöffnetem Kiosk-Tab feuert (statt zentral einmal
pro Konto — auch das ist eine der offenen Fragen im Planungsdokument),
würden bei bis zu drei gleichzeitig laufenden Alarmmonitor-Standorten
(30010, 30020)
bis zu drei Tickets für denselben Einsatz entstehen. Der Code-Node merkt
sich deshalb Stichwort|Einheit (oder den kompletten Payload, falls
keyword/unit fehlen) für 2 Minuten in n8n-Workflow-Static-Data und
überspringt inhaltsgleiche Wiederholungen innerhalb dieses Fensters —
wichtig: Das ist reiner In-Memory-Zustand, ein n8n-Neustart löscht ihn
(unkritisch, da echte Mehrfach-Auslösungen desselben Alarms innerhalb von
Sekunden eintreffen, nicht nach einem Neustart).

Einrichtung

  1. Voraussetzung: Zammad-API-Token mit Berechtigung ticket.agent
    vorhanden. Achtung: Der native Zammad-Node braucht eine Credential
    vom Typ „Zammad Token Auth API" (zammadTokenAuthApi) — das ist
    ein anderer Credential-Typ als die Header-Auth-Credential "Zammad
    API Token", die banana-pi-down-to-zammad.json nutzt; die beiden lassen
    sich nicht wiederverwenden, auch wenn derselbe Zammad-Token dahinter
    stehen kann. Falls schon für nightly-worker-update-to-zammad.json oder
    yearly-secrets-rotation-reminder.json eine Credential dieses Typs
    angelegt wurde (z. B. "Zammad Token Auth (Rotation-Reminder)"), kann die
    wiederverwendet werden, sofern sie auf dieselbe Zammad-Instanz zeigt.
    Sonst Token neu erzeugen wie in
    f0040-github-release-watcher.md, Schritt 1
    beschrieben, Credential in n8n neu anlegen: Typ "Zammad Token Auth API",
    Base URL https://zammad.tech.homeserver (nicht http://: der TECH-Traefik antwortet auf HTTP mit 308, und der Zammad-Node folgt dem bei POST nicht), „Ignore SSL Issues“ aus. n8n vertraut der Homeserver-Root-CA über NODE_EXTRA_CA_CERTS, siehe 30070. Access Token aus Schritt 1.
  2. n8n: alamos-einsatz-to-zammad.json importieren, im Node
    "Zammad-Ticket erstellen" die Credential aus Schritt 1 zuweisen —
    Credential-IDs werden beim Import nicht übernommen, normaler
    Post-Import-Schritt.
    In den beiden Webhook-Nodes („Webhook (GET)“, „Webhook (POST)“) das
    Credential Webhook alamos-einsatz (Header Auth) zuweisen. Es enthält
    dasselbe Bearer-Token wie der Schlüssel n8nToken im Secret von
    alamos-relay, siehe
    30070. Ohne gültigen Header
    antwortet der Webhook mit 403.
  3. Workflow in n8n aktivieren (Import allein reicht nicht).
  4. alamos-relay ausrollen (eigener Chart, eigenes
    Token) und die öffentliche Relay-URL zusammensetzen:
    https://alamos-relay-prod.pke-lab.de/relay/<TOKEN> — nicht mehr
    http://n8n.prod.homeserver/webhook/alamos-einsatz direkt, siehe
    Architektur oben.
  5. Im Alamos-Account (mit eurem bestehenden Login) — dieser Schritt
    ist zwingend, ohne ihn feuert der Workflow nie
    : Webhook-Konfiguration
    der AMweb-Seiteneinstellung öffnen (nicht "Allgemeine Webhooks",
    siehe Begründung oben unter Architektur), obige Relay-URL als Ziel
    eintragen. Dabei gleich in der Vorschau/"Webhook Test" nachsehen, welche
    Platzhalter tatsächlich angeboten werden — das beantwortet die im
    Planungsdokument offene Frage nach den exakten Feldnamen.
  6. Zammad: Sicherstellen, dass [email protected] (oder die
    gewünschte Zieladresse) Agent in der Gruppe Support::Administration
    ist und unter Profil → Benachrichtigungen die Mail-Benachrichtigung
    für "Neues Ticket" aktiviert hat (Zammad-Standard: aktiviert).
  7. Testauslösung: entweder auf einen echten Einsatz warten, oder — falls
    Alamos eine "Webhook Test"-Funktion in der Konfiguration anbietet —
    darüber einen Testaufruf schicken.

Anpassungen

Fehlerbehebung

Symptom Check
Kein Zammad-Ticket bei echtem Einsatz Workflow in n8n aktiv? kubectl -n n8n logs deploy/n8n (bzw. n8n-UI → Executions) — kommt der Webhook überhaupt an? Execution-Log der "Einsatzdaten aufbereiten"-Node ansehen: falls dort Kein keyword/unit im Payload geloggt wird, obwohl es ein echter Alarm war, liefert eure Alamos-Instanz die Daten unter anderen Feldnamen als keyword/unit — Rohdaten aus dem Log in Anpassungen berücksichtigen
Test-Call (z. B. curl gegen alamos-relay ohne Query-Parameter) erzeugt kein Ticket Erwartetes Verhalten, siehe Leere Test-Calls werden übersprungen — kein Fehler, nur ein Log-Eintrag
Ticket wird unterdrückt, obwohl es ein neuer Einsatz war DEDUP_WINDOW_MS zu großzügig, oder keyword/unit fehlen und der Fallback-Payload-Vergleich trifft zufällig — Rohdaten in der n8n-Execution ansehen
Ticket erstellt, aber keine Mail Zammad-Agenten-Mitgliedschaft/Benachrichtigung prüfen (siehe oben), ausgehender E-Mail-Kanal in Zammad konfiguriert?
n8n-Workflow schlägt am Zammad-Node fehl Credential vom Typ "Zammad Token Auth API" zugewiesen (nicht die Header-Auth-Credential aus banana-pi-down-to-zammad.json)? Base URL korrekt (https://zammad.tech.homeserver; mit http:// kommt 308 Permanent Redirect)? Token gültig/ticket.agent-Berechtigung?
Webhook kommt gar nicht in n8n an Erst alamos-relay prüfen (kubectl -n alamos-relay logs deploy/alamos-relay, korrektes Token in der Alamos-Konfiguration?) — kommt der Call dort schon nicht an, liegt es an Alamos/DNS, nicht an n8n. Kommt er beim Relay an, aber nicht bei n8n: NetworkPolicy-Rollout aus 300i0, Rollout vollständig durchgelaufen?