BRAINAVO

Skip to main content
< Alle Themen

Aufsetzen von Talaxie für die Kommunikation mit Znuny

Inhaltsverzeichnis

0) Zielbild und Voraussetzungen

Zielbild

sipgate Front Desk Webhook → Talaxie ESB (HTTP Endpoint) → Znuny GenericInterface REST

Voraussetzungen (minimal)

  • 1 Linux-VM für ESB (empfohlen): 2 vCPU / 4–8 GB RAM / 20+ GB Disk
  • DNS-Name + TLS Zertifikat (Let’s Encrypt oder interne PKI)
  • Reverse Proxy (nginx/Apache) vor der Runtime (empfohlen)
  • Zugriff auf Znuny GenericInterface REST (Adminrechte zum Einrichten/Testen)

1) Komponentenübersicht (was ihr installiert)

  1. Talaxie Studio (ESB/DI) – zum Entwickeln der Route (Mapping/HTTP Endpoint/Call zu Znuny).
  2. Talend Runtime / Karaf-Container – die Laufzeitumgebung, in die ihr die Route deployt (KAR-Datei).

In der Talend-Welt ist das Standard: Route bauen → KAR exportieren → in Runtime deployen.

2) Installation: Talaxie Studio (Build-System)

Das macht ihr idealerweise auf einer Admin-Workstation oder Build-VM, nicht auf dem Runtime-Server.

2.1 Download & Start

  • Talaxie ist der Community-Fork von Talend Open Studio (DI/ESB/BD).
  • Installiert passend Java (je nach Talaxie-Version; hier müsst ihr euch an die Release-Hinweise halten – Talend/Talaxie sind bei Java-Versionen empfindlich).
  • Startet Studio einmal, legt ein Projekt an (z. B. ESB_SIPGATE_ZNUNY).

Praxis-Tipp: Plant direkt ein kleines Git-Repo (Projekt + Route) ein.

3) Installation: Runtime (Karaf/Talend Runtime)

3.1 Runtime installieren

  • Runtime/Container auf dem ESB-Server installieren (klassisch: entpacken nach /opt/talend-runtime oder ähnlich).
  • Ziel: Ihr habt ein Verzeichnis mit bin/, etc/, deploy/, data/ usw.
  • Viele Deploy-Anleitungen nutzen: Route exportieren und direkt in den deploy/-Ordner legen, dann startet sie automatisch.

3.2 Benutzer & Rechte

sudo useradd --system --home /opt/talend-runtime --shell /usr/sbin/nologin talend
sudo chown -R talend:talend /opt/talend-runtime

3.3 Systemd Service (Start/Stop sauber)

Beispiel /etc/systemd/system/talend-runtime.service:

[Unit]
Description=Talend Runtime (Karaf) for Talaxie ESB Routes
After=network.target
[Service]
Type=simple
User=talend
Group=talend
WorkingDirectory=/opt/talend-runtime
ExecStart=/opt/talend-runtime/bin/karaf run
Restart=on-failure
RestartSec=10
LimitNOFILE=65535
[Install]
WantedBy=multi-user.target

Dann:

sudo systemctl daemon-reload
sudo systemctl enable --now talend-runtime
sudo systemctl status talend-runtime

4) Route bauen: “sipgate webhook rein → canonical json → Znuny raus”

4.1 Route anlegen (im Talaxie Studio)

  • Neues Route-Artefakt (Camel / cREST / CXF je nach Komponenten).
  • Inbound: HTTP POST Endpoint (z. B. /webhook/sipgate/frontdesk)
  • Parser: Form-Encoded Body in Felder umwandeln (sipgate sendet typischerweise application/x-www-form-urlencoded).
  • Normalisierung auf internes Objekt (Canonical Model): callId, from, to, event, timestamp, optional summary.

Warum so? sipgate schickt mehrere Events pro Call (newCall, answer, hangup etc.). Das ist in ihren Beispielen so gedacht.

4.2 Ticket-Strategie (sehr empfohlen)

  • 1 Ticket pro callId
  • Folge-Events werden als Artikel ans Ticket gehängt (oder TicketUpdate)

Damit vermeidet ihr Ticket-Spam.

4.3 Znuny REST Provider vorbereiten

In Znuny richtet ihr einen GenericInterface REST Webservice ein, der mindestens kann:

  • TicketCreate
  • TicketUpdate / ArticleCreate (je nach Mapping)

Die GenericInterface-Mechanik ist bei Znuny/OTRS seit Jahren der Standardweg.
(Bei OTOBO/Znuny-REST gibt’s sehr ähnliche Admin-Schritte: aktivieren, Webservice anlegen, Operationen konfigurieren.)

5) Build & Deploy (KAR)

5.1 Route als KAR bauen

Im Studio: Rechtsklick auf Route → Build Route / Build Route to ESB Runtime KAR file.

5.2 Deployment

  • Kopiert die erzeugte *.kar nach:
    • /opt/talend-runtime/deploy/

Viele Guides nutzen genau das: build → in deploy/ legen → Runtime lädt es automatisch.

5.3 Verifikation

  • Karaf-Konsole: prüfen ob Bundle/Route aktiv ist (z. B. osgi:list).
  • HTTP Endpoint testweise mit curl ansprechen.

6) Reverse Proxy + TLS (dringend empfohlen)

sipgate Webhooks müssen aus dem Internet erreichbar sein.
Setzt daher unbedingt davor einen Reverse Proxy, der:

  • TLS terminiert
  • Rate-Limit / Basic WAF Regeln kann
  • optional ein Secret prüft (Header/Query)

Beispiel nginx (Sketch)

Zusätzlich:

  • limit_req für Rate-Limit
  • allow/deny wenn sipgate feste IPs bietet (oft nicht garantiert)

7) sipgate Front Desk / Webhooks konfigurieren

sipgate bietet im Webhooks-Bereich:

  • Ziel-URL setzen
  • Incoming/Outgoing unterscheiden
  • Debug-Log aktivieren, um Requests/Responses zu sehen

Wichtig: Webhooks kommen als POST und enthalten Felder in form-encoded.

8) Observability & Betrieb

8.1 Correlation-ID

Nutzt callId als Correlation-ID und schreibt sie in jeden Log-Eintrag (und als DynamicField im Ticket).

8.2 Fehlerpfad

  • Wenn Znuny REST nicht erreichbar: Retry (mit Backoff)
  • Wenn Payload unvollständig: 4xx zurückgeben, im Log markieren
  • Dead-Letter: optional separates Log/File oder Queue

8.3 Debugging sipgate

sipgate kann Webhook-Requests und Responses im Debug-Log anzeigen.
Das ist extrem hilfreich, wenn ihr 200 OK vs. 500 seht.

9) “Admin-Checkliste” zum Abhaken

Server

  • [ ] Runtime läuft als systemd service
  • [ ] Endpoint intern erreichbar (curl localhost)
  • [ ] Reverse Proxy + TLS aktiv
  • [ ] Firewall nur 443 offen
  • [ ] Logging & Rotation eingerichtet

sipgate

  • [ ] Webhook URL gesetzt
  • [ ] Debug Log testweise aktiviert
  • [ ] Testcall löst Webhook aus

Znuny

  • [ ] GenericInterface REST Webservice vorhanden
  • [ ] Test-Call legt Ticket an / hängt Artikel an

Veröffentlicht
Aktualisiert