Ausgehende Aktionen

Event-Handler von EventBridge führen je abonniertem Ereignis genau eine Aktion aus: einen HTTP-Aufruf (Webhook), eine E-Mail, eine Syslog-Nachricht, eine Ablage in Datei oder SQL-Datenbank, einen Modul-Logeintrag oder ein neues internes Ereignis. Diese Seite dokumentiert Konfiguration, Formate und Zustellverhalten der Aktionstypen sowie die vollständige Platzhalter-Syntax {{…}}. Die Bedienung der Handler (Ereignisauswahl, JsonPath-Extraktion, MVEL-Bedingungen) beschreibt die Dokumentation.

Verwendung durch Dritte

Die von diesen Aktionen erzeugten Formate sind für die Verarbeitung durch Drittsysteme freigegeben. Änderungen und Erweiterungen werden je Version in den Release Notes dokumentiert.

Grundlagen

• Auslöser: ein abonniertes Ereignis der STARFACE-Eventbusse, des Asterisk-AMI oder der Fluxpunkt-Module — siehe Ereignisliste.
• Ablauf je Handler: Ereignis → Zeitfenster-Prüfung → optionale Verzögerung → MVEL-Bedingung → Zustands-Speicherung → Aktion.
• Nebenläufigkeit: Aktionen laufen asynchron auf einem Worker-Pool mit 4 Threads; die Ereignisverarbeitung der Anlage wird nie blockiert.
• Verzögerung: je Handler in Millisekunden konfigurierbar (0 = sofort). Ein konfiguriertes Zeitfenster wird nach Ablauf der Verzögerung erneut geprüft.
• Zustellgarantien: Es gibt keine automatischen Wiederholungen. Eine fehlgeschlagene Aktion wird ausschließlich im Modul-Log protokolliert (fire-and-forget).
• Vorlagen: Die Ausgabefelder aller Aktionstypen unterstützen {{…}}-Platzhalter — vollständige Referenz unten.

Aktionstypen

Webhook (HTTP-Aufruf)

Ruft eine frei konfigurierbare URL auf.

Feld	Platzhalter	Beschreibung
URL	ja	Ziel-URL einschließlich Query-Parametern
Methode	–	GET oder POST
Kopfzeilen	ja (im Wert)	Name-Wert-Paare; nur Einträge im Modus „Wert" werden gesendet, Platzhalter im Wert werden ersetzt
Body	ja	frei gestalteter Anfragekörper (z. B. JSON)
Formulardaten	ja (im Wert)	Alternative zum Body: Schlüssel-Wert-Paare, gesendet als application/x-www-form-urlencoded. Sind Formulardaten konfiguriert, wird der Body ignoriert

Bei GET werden weder Body noch Formulardaten übertragen. Setzen Sie den Content-Type der Nutzlast als eigene Kopfzeile (z. B. application/json).

Body-Vorlage mit Platzhaltern

{
  "text": "Verpasster Anruf von {{callerName}} ({{callerNumber}})",
  "gruppe": {{groupId}},
  "quelle": "STARFACE"
}

Beim Empfänger eintreffender Body (Beispielwerte)

{
  "text": "Verpasster Anruf von Max Mustermann (67)",
  "gruppe": 5470,
  "quelle": "STARFACE"
}

Zustellverhalten: Der Aufruf erfolgt synchron auf dem Worker-Pool; der Antwort-Statuscode des Zielsystems wird im Modul-Log (Trace) vermerkt, die Antwort selbst wird nicht weiterverarbeitet. Es gibt keine modulseitig konfigurierbaren Timeouts und keine Wiederholversuche.

E-Mail

Versendet eine Text-E-Mail über die Mailversand-Funktion des STARFACE-Modul-SDK.

Feld	Platzhalter	Beschreibung
Empfänger	ja	Zieladresse
Absender	ja	Absenderangabe (Feld fromName des STARFACE-Mailversands)
Betreff	ja	Betreffzeile
Text	ja	Nachrichtentext

Betreff-Vorlage (Beispiel)

Verpasster Anruf von {{callerName}} {{callerNumber}} an Zentrale

Zustellverhalten: Erfolg oder Misserfolg des Versands wird im Modul-Log vermerkt; keine Wiederholversuche.

Modul-Logeintrag

Schreibt eine Zeile in das Modul-Log der Anlage.

Feld	Platzhalter	Beschreibung
Log-Level	–	TRACE, DEBUG, INFO (Standard), WARN, ERROR
Nachricht	ja	Logtext

Internes Ereignis (FpEvent)

Veröffentlicht ein Fluxpunkt-Ereignis auf dem anlageninternen Ereignisbus (Topic fp-event_<Ereignisname>). Das ist keine Netzwerkschnittstelle: Empfänger sind Fluxpunkt-Module (z. B. die Steuerereignisse des Admin Power Pack), eigene STARFACE-Module über die Modulfunktionen FpEvent abonnieren/FpEvent senden (siehe Schnittstellen & APIs) — und EventBridge selbst.

Feld	Platzhalter	Beschreibung
Ereignis	–	frei wählbarer Ereignisname; Platzhalter werden hier nicht ersetzt
Nutzlast (JSON)	ja	JSON-Vorlage des Ereignisses

Eigene Handler abonnieren ein solches Ereignis über die Ereignisauswahl (Kategorie FLUXPUNKT; intern wird der synthetische Klassenname de.fluxpunkt.fpevent.<Ereignisname> verwendet). In der Ereignisauswahl erscheinen nur Ereignisnamen, die auf Event enden — Steuerereignisse wie ExecuteUserTemplate sind bewusst nur sendbar, nicht abonnierbar.

Ablage (SFTP / SMB / SQL-Datenbank)

Schreibt frei gestaltete Inhalte auf ein wiederverwendbares Speicherziel (Tab Speicherziele). Die Aktion referenziert das Ziel; Pfad und Inhalt definieren Sie je Handler.

Ziel-Konfiguration:

Zieltyp	Felder
SFTP	Host (Port 22), Basisverzeichnis, Benutzername, Passwort (verschlüsselt gespeichert)
SMB/CIFS	Host (Port 445), Freigabename, Unterordner, Benutzername, Passwort, Domäne, Sicherheitsmodus (Standard ntlmssp)
SQL-Datenbank	Datenbanktyp (MySQL, PostgreSQL, Microsoft SQL Server, Derby), Host, Datenbankname, Benutzername, Passwort, Verbindungsoptionen

Aktion — Datei-Ziele (SFTP/SMB):

Feld	Platzhalter	Beschreibung
Pfad	ja	Pfad einschließlich Dateiname, relativ zum Basisverzeichnis des Ziels; ein Verzeichnisanteil wird angehängt
Inhalt	ja	Dateiinhalt, geschrieben als UTF-8

Aktion — Datenbank-Ziele:

Der Inhalt ist eine SQL-Anweisung. Ereignisdaten werden nie in den SQL-Text eingesetzt: Jeder {{Platzhalter}} wird durch einen ?-Bindeparameter ersetzt und der aufgelöste Wert als Zeichenkette gebunden (PreparedStatement) — konstruktionsbedingt kein SQL-Injection-Vektor. Ein unaufgelöster Platzhalter bindet eine leere Zeichenkette (nie SQL-NULL). Die Ausführung ist auf 10 Sekunden je Anweisung begrenzt.

Platzhalter in SQL nicht in Anführungszeichen setzen

Schreiben Sie VALUES ({{callerNumber}}), nicht VALUES ('{{callerNumber}}'). Innerhalb eines SQL-String-Literals wird der Platzhalter nicht zum Bindeparameter; die Anweisung schlägt durch die abweichende Parameteranzahl fehl und es wird nichts geschrieben (fail-closed).

Beispiel: Zieltabelle (MySQL)

CREATE TABLE eventbridge_calls (
  id         INT AUTO_INCREMENT PRIMARY KEY,
  erfasst_am TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
  anrufer    VARCHAR(64),
  gruppe     VARCHAR(32),
  ergebnis   VARCHAR(32)
);

Inhalt der Aktion (Vorlage)

INSERT INTO eventbridge_calls (anrufer, gruppe, ergebnis)
VALUES ({{callerNumber}}, {{groupId}}, {{result}})

Tatsächlich ausgeführte Anweisung

INSERT INTO eventbridge_calls (anrufer, gruppe, ergebnis) VALUES (?, ?, ?)
-- gebundene Parameter (in Reihenfolge): '67', '5470', 'MISSED'

Alle Parameter werden als Zeichenketten gebunden; die Konvertierung in numerische Spalten übernimmt das Datenbanksystem.

Zustellverhalten: Schreibvorgänge laufen synchron auf dem Worker-Pool, ohne Wiederholversuche. SFTP/SMB besitzen kein konfigurierbares Timeout; Datenbankanweisungen sind auf 10 Sekunden begrenzt. Halten Sie Speicherziele schnell erreichbar — langsame oder nicht erreichbare Ziele belegen die 4 Worker-Threads und verzögern damit auch andere Aktionen.

Syslog

Übermittelt eine Nachricht im Format RFC 5424 oder RFC 3164 an ein als Speicherziel konfiguriertes Syslog-Ziel.

Ziel-Konfiguration:

Feld	Standard	Beschreibung
Host / Port	Port 514	Syslog-Collector
Transport	UDP	UDP, TCP oder TLS
Nachrichtenformat	RFC 5424	RFC 5424 oder RFC 3164
TCP-Framing	Octet-Counting	RFC 6587: Octet-Counting (<Länge> vor der Nachricht) oder Non-Transparent (abschließendes \n); nur TCP/TLS
Standard-Facility	LOCAL0	alle RFC-5424-Facilities KERN (0) bis LOCAL7 (23)
App-Name	STARFACE EventBridge	RFC-5424-APP-NAME bzw. RFC-3164-TAG
Hostname-Override	–	ersetzt den automatisch ermittelten Anlagen-Hostnamen
TLS-Zertifikatsprüfung	aktiv	abschaltbar (dann werden alle Zertifikate akzeptiert)
Verbindungs-Timeout	5000 ms	Verbindungs- und Socket-Timeout für TCP/TLS

Aktionsfelder:

Feld	Platzhalter	Beschreibung
Severity	–	EMERGENCY (0) bis DEBUG (7); Standard INFO (6)
Facility-Override	–	ersetzt die Standard-Facility des Ziels für diese Aktion
App-Name-Override	–	ersetzt den App-Namen des Ziels; Platzhalter werden nicht ersetzt
MSGID	–	RFC-5424-MSGID; leer ⇒ -; Platzhalter werden nicht ersetzt
STRUCTURED-DATA	ja	RFC-5424-STRUCTURED-DATA; leer ⇒ -
Nachricht	ja	der Nachrichtentext (MSG)

Nachrichtenformat: Der PRI-Wert berechnet sich als Facility × 8 + Severity (LOCAL0/INFO ⇒ <134>). Zeilenumbrüche im Nachrichtentext werden durch Leerzeichen ersetzt.

RFC-5424-Nachricht (Beispiel)

<134>1 2026-08-04T09:30:12.184+02:00 pbx01 STARFACEEventBridge - - - Verpasster Anruf von Max Mustermann (67)

• Aufbau: PRI, Version 1, ISO-8601-Zeitstempel mit Zeitzone, HOSTNAME, APP-NAME, PROCID (immer -), MSGID, STRUCTURED-DATA, Nachricht.
• Unmittelbar vor dem Nachrichtentext steht die unsichtbare UTF-8-Byte-Order-Mark (U+FEFF), wie in RFC 5424 §6.4 für UTF-8-Nachrichten vorgesehen.
• Leere Kopffelder werden als - übertragen; Leerzeichen innerhalb von HOSTNAME, APP-NAME und MSGID werden entfernt (aus STARFACE EventBridge wird STARFACEEventBridge).

RFC-3164-Nachricht (Beispiel)

<134>Aug  4 09:30:12 pbx01 STARFACE EventBridge: Verpasster Anruf von Max Mustermann (67)

• Aufbau: PRI, Zeitstempel (englische Monatsabkürzung, Tag mit führendem Leerzeichen), HOSTNAME, TAG (App-Name, hier unverändert mit Leerzeichen), : , Nachricht.

Zustellverhalten: UDP versendet ein einzelnes Datagramm ohne Zustellbestätigung. Bei TCP/TLS wird je Nachricht eine neue Verbindung aufgebaut (Timeout siehe Ziel); keine Wiederholversuche.

Platzhalter-Referenz

Platzhalter der Form {{name}} werden beim Ausführen einer Aktion durch Werte aus vier Quellen ersetzt. Die Namen der Ereignis-, Global- und Zustandsvariablen vergeben Sie selbst — es gibt kein festes Platzhalter-Vokabular und keine eingebauten Funktions- oder Datumsplatzhalter: Jeder benötigte Wert wird per JsonPath aus dem Ereignis extrahiert oder als globale bzw. Zustandsvariable bereitgestellt.

Variablenquellen

Quelle	Platzhalter	Bedeutung	Beispielwert
Ereignisdaten (Parser)	{{callerNumber}}, {{groupId}}, … (frei benannt)	Je Handler definierte Extraktionen: ein JsonPath-Ausdruck gegen das Ereignis-JSON (z. B. $.callListEntry.callerNumber), ein fester Wert oder eine Benutzer-/Gruppenauswahl. Skalare Treffer werden zur Zeichenkette, Objekte/Arrays zu JSON-Text; ein nicht vorhandener Pfad lässt die Variable unbelegt	67
Implizite Webhook-Variablen	{{webhookId}}	ID des eingehenden Webhooks, der den Aufruf angenommen hat — nur bei eingehenden Webhooks	9f3a21c4
	{{webhookName}}	Name des eingehenden Webhooks	Ticket-Import
Globale Variablen	{{apiKey}}, … (frei benannt)	Anlagenweite Name-Wert-Paare aus dem Tab Globale Variablen — z. B. Zugangsschlüssel, Basis-URLs, Standorte	k7fj29a…
Zustandsvariablen	{{lastCaller}}, … (frei benannt)	Zur Laufzeit von Handlern geschriebene Werte (Abschnitt „Zustand speichern"), mit Lebensdauer je Eintrag (maximal 90 Tage; 0 ⇒ 90 Tage). Damit reichen Handler Werte an spätere Ereignisse weiter	0711459880

Im Konfigurationsexport (.ebc) und in der Modul-RPC werden die Parser-Werte mit den Präfixen jp: (JsonPath), val: (fester Wert) und ug: (Benutzer-/Gruppenauswahl als URL-kodiertes JSON-Objekt mit users/groups) serialisiert; ohne Präfix gilt JsonPath.

Rangfolge

Bei gleichem Namen gilt: Ereignis-/Parser-Variablen überschreiben Zustandsvariablen, diese überschreiben globale Variablen. Im Webhook-Ingress liegen die impliziten Variablen {{webhookId}}/{{webhookName}} zwischen Parser- und Zustandsebene — eine gleichnamige Parser-Variable überschreibt sie gezielt.

Wirkungsbereiche

Aktionstyp	Feld	Platzhalter ersetzt
Webhook	URL, Kopfzeilen-Werte, Body, Formulardaten-Werte	ja
E-Mail	Empfänger, Absender, Betreff, Text	ja
Internes Ereignis	Nutzlast (JSON)	ja
Internes Ereignis	Ereignisname	nein
Modul-Logeintrag	Nachricht	ja
Ablage	Pfad, Inhalt (SQL: als gebundene Parameter)	ja
Syslog	Nachricht, STRUCTURED-DATA	ja
Syslog	MSGID, App-Name-Override	nein
Zustand speichern	Name, Wert	ja
Eingehender Webhook	Ereignis-Nutzlast (JSON)	ja
Bedingung (MVEL)	—	nein — Variablen stehen dort ohne Klammern als Bezeichner bereit (result == "MISSED")

Syntax und Auflösungsverhalten

• Schreibweise: exakt {{name}} — ohne Leerraum zwischen Klammern und Namen; Groß-/Kleinschreibung ist relevant.
• Unaufgelöste Platzhalter bleiben in Textfeldern wörtlich erhalten. Ausnahme SQL-Inhalte: Dort wird jeder Platzhalter zum ?-Parameter; ein unaufgelöster bindet eine leere Zeichenkette.
• Standardwerte: In Textfeldern liefert {{name:-Ersatzwert}} den Ersatzwert, wenn name nicht belegt ist (Verhalten der eingesetzten Template-Engine Apache Commons Text). In SQL-Inhalten gilt diese Syntax nicht — dort zählt der gesamte Text zwischen den Klammern als Variablenname.
• Escaping: Ein vorangestelltes Dollarzeichen (${{name}}) gibt die Zeichenfolge {{name}} in Textfeldern wörtlich aus.
• Rekursion: Enthält ein aufgelöster Wert selbst {{…}}, wird er in Handler-Aktionen erneut ersetzt. Bei eingehenden Webhooks ist diese Rekursion aus Sicherheitsgründen deaktiviert.
• Datentypen: Alle Variablenwerte sind Zeichenketten. In JSON-Vorlagen entscheidet die Vorlage über den Typ: "{{groupId}}" erzeugt einen String, {{groupId}} ein JSON-Zahlen- bzw. Rohtoken.

Anwendungsbeispiel

Ein Systemhaus protokolliert jeden verpassten Gruppenanruf doppelt: per SQL-Ablage in eine Auswertungstabelle und als RFC-5424-Nachricht an das zentrale SIEM. Vollständige Konfigurationen dieser Art enthält der Abschnitt Beispielkonfigurationen.

Fehlerbehandlung

Situation	Verhalten
Bedingung nicht erfüllt	Aktion unterbleibt; Vermerk im Modul-Log (Debug)
MVEL-Fehler oder Nicht-Boolean-Ergebnis der Bedingung	zählt als „nicht erfüllt"; Aktion unterbleibt; Vermerk im Modul-Log
Aktion schlägt fehl (Netzwerk, SMTP, SQL, Syslog)	Eintrag im Modul-Log; keine Wiederholung
Referenziertes Speicher-/Syslog-Ziel nicht vorhanden	Warnung im Modul-Log; nichts wird gesendet
SQL-Parameteranzahl-Konflikt (z. B. Platzhalter in Anführungszeichen)	SQLException, im Modul-Log protokolliert; nichts wird geschrieben
Datenbankanweisung überschreitet 10 Sekunden	Abbruch der Anweisung

Zur Diagnose stehen je Handler eine Testfunktion (wartet bis zu 30 Sekunden auf ein passendes Ereignis und zeigt die vollständig aufgelösten Vorlagen an, ohne die Aktion auszuführen) sowie die Vorschau „Echte Werte" mit aufgezeichneten Beispielereignissen bereit. Die „Zustand speichern"-Einträge werden — anders als die Aktion — bereits vor der Aktionsausführung persistiert und bleiben auch bei fehlgeschlagener Aktion erhalten.

Versionierung & Kompatibilität

Funktion	Verfügbar seit
Aktionen Webhook, E-Mail, Modul-Logeintrag, internes Ereignis	Grundbestandteil des Moduls
Zustandsvariablen	26.6.4
Ablage SFTP/SMB/Datenbank	26.7.10
Syslog	26.7.13
Implizite Webhook-Variablen {{webhookId}}/{{webhookName}}	26.7.23

Die dokumentierten Formate — Platzhalter-Syntax, Syslog-Nachrichtenaufbau, SQL-Parameterbindung — gelten als stabiler Vertrag; abwärtskompatible Erweiterungen (neue Aktionstypen, zusätzliche Felder) erfolgen ohne Ankündigung, Änderungen bestehenden Verhaltens werden in den Release Notes dokumentiert. Die Struktur der abonnierbaren Ereignisse selbst ist kein Bestandteil dieses Vertrags — STARFACE-Ereignisse können sich mit Anlagen-Updates ändern (siehe Hinweise in der Ereignisliste).