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.

Module installieren und aktualisieren

Mit dem Steuerereignis ExecuteModuleInstallation installiert oder aktualisiert eine Aktion ein Modul aus dem signierten Update-Katalog. Ausgeführt wird der Auftrag von dem Modul, das in executorModuleId steht — üblicherweise dem Module Manager. Das Ergebnis kommt als ModuleInstallationExecutedEvent zurück; dieses Ereignis können Sie wie jedes andere abonnieren und weiterleiten.

Nutzlast der Aktion: Admin Power Pack auf eine bestimmte Version heben

{
  "executorModuleId": "c2ccd2c1-d74b-48c4-a462-2c1b2eb97eb7",
  "targetModuleId": "7ce0d8df-e9c8-42f6-a021-7a6e0bb44b88",
  "targetVersion": 20261003,
  "requestedBy": "EventBridge: nächtliches Modul-Update"
}

Eine Version unter der installierten wird nur mit "allowDowngrade": true installiert. Felder, Antwortereignisse und Fehlercodes beschreibt die Referenz im Admin Power Pack.

Anwendungsbeispiel

Ein Systemhaus plant ein Modul-Update ins Wartungsfenster: Im Tab Geplante Events legt es ExecuteModuleInstallation mit dieser Nutzlast einmalig für Sonntag, 3 Uhr, an. Ein Handler abonniert ModuleInstallationExecutedEvent und schreibt Ergebnis, alte und neue Version per Syslog in das zentrale Log. So sind Modul-Updates planbar und nachvollziehbar, ohne dass nachts jemand die Modulverwaltung öffnet.

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.
• Platzhalter in Werten: Nur globale Variablen dürfen selbst Platzhalter enthalten, z. B. baseUrl = https://{{host}}/api. Diese werden beim Einsetzen weiter aufgelöst. Werte aus Ereignisdaten, Zustandsvariablen und Webhook-Aufrufen setzt die EventBridge immer wörtlich ein – auch wenn sie {{…}} enthalten. So kann etwa ein Anrufer mit dem Anzeigenamen {{apiKey}} keine Zugangsdaten auslesen. Dieses Verhalten ist nicht abschaltbar.
• Verschachtelte Platzhalter: Ein Platzhalter darf in seinem Namen weitere Platzhalter enthalten, z. B. {{slackToken_{{accountId}}}}. Diese Option ist standardmäßig aus; Details im Abschnitt Verschachtelte Platzhalter.
• 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.

Verschachtelte Platzhalter

Pflegen Sie Zuordnungen pro Benutzer, Gruppe oder Standort zentral als globale Variablen – und wählen Sie den passenden Eintrag zur Laufzeit über die Ereignisdaten aus. Ein Handler reicht dann für alle Benutzer.

Aktivieren Sie dazu im Expertenmodus auf dem Tab Globale Variablen & Zustände in der Karte Einstellungen die Option Unterstützung für verschachtelte Variablen.

Anwendungsbeispiel

Ein Unternehmen mit 40 Mitarbeitern zeigt den Telefoniestatus in Slack an. Der Administrator legt je Mitarbeiter eine globale Variable slackToken_<accountId> an. Ein einziger Handler setzt mit Bearer {{slackToken_{{accountId}}}} für jeden Anrufer das richtige Token ein – statt 40 Handlern. Die vollständige Konfiguration zeigt die Beispielkonfiguration Telefoniestatus als Slack-Status.

So wird aufgelöst:

1. Zuerst wird der innere Platzhalter ersetzt: {{accountId}} → 123.
2. Das Ergebnis bildet den Namen des äußeren Platzhalters: slackToken_123.
3. Dessen Wert wird eingesetzt – egal ob Ereignis-, Zustands- oder globale Variable.

Vorlage	Ergebnis (mit accountId = 123, slackToken_123 = xoxp-1a2b)
Bearer {{slackToken_{{accountId}}}}	Bearer xoxp-1a2b
{{slackToken_{{accountId}}:-}} (Variable fehlt)	leere Zeichenkette
{{slackToken_{{accountId}}}} (Variable fehlt)	bleibt wörtlich stehen
{{slackToken_{{accountId}}}} (Option aus)	bleibt wörtlich stehen

Die Option gilt für alle Felder der Handler-Aktionen und für „Zustand speichern“. Sie gilt nicht für:

• Eingehende Webhooks: Werte von außen dürfen nicht bestimmen, welche globale oder Zustandsvariable gelesen wird.
• SQL-Inhalte: Dort zählt weiterhin der gesamte Text zwischen den äußeren Klammern als Variablenname.
• Bedingungen (MVEL): Dort werden keine Platzhalter ersetzt.

Vorhandene Vorlagen

Ist die Option aus, ändert sich an bestehenden Vorlagen nichts. Prüfen Sie nach dem Einschalten Vorlagen, die {{ innerhalb eines Platzhalters enthalten, mit der Testfunktion des Handlers.

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
Verschachtelte Platzhalter (Option, Expertenmodus)	nächstes Release nach 26.10.1

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).