Zum Hauptinhalt springen

Ereignisse

DirectoryHub tauscht Ereignisse („FpEvents") mit anderen Fluxpunkt-Modulen aus: Es sendet zu jedem Importlauf ein Start- und ein Abschlussereignis mit Quelle, Ergebnis und Zählern — und empfängt ein Steuerereignis, mit dem Drittsysteme den Import einer Quelle sofort anstoßen. Typische Konsumenten sind EventBridge (Weiterleitung als Webhook, E-Mail, Syslog oder Datenbankeintrag) und eigene STARFACE-Module, die Ereignisse direkt abonnieren oder senden.

Verwendung durch Dritte

Diese Schnittstelle ist für die Nutzung durch Drittsysteme freigegeben. Änderungen und Erweiterungen werden je Version in den Release Notes dokumentiert.

Grundlagen​

  • Typ: FpEvents — der modulübergreifende Ereignismechanismus der Fluxpunkt-Module auf dem anlageninternen Ereignisbus. Es handelt sich um keine Netzwerkschnittstelle: Ereignisse sind nur innerhalb der Anlage erreichbar; nach außen gelangen sie über EventBridge.
  • Identifikatoren: die Ereignisnamen DirectoryImportStartedEvent, DirectoryImportFinishedEvent (gesendet) und ExecuteDirectoryImport (empfangen). Die Namen sind anlagenweit gültig und unabhängig vom Namen der Modulkonfiguration.
  • Nutzlast: ein JSON-Objekt. Felder ohne Wert (null) entfallen in der Nutzlast; unbekannte Felder werden beim Empfang ignoriert.
  • Zugriff: EventBridge abonniert Ereignisse per Konfiguration und kann das Steuerereignis als Aktion senden (z. B. ausgelöst durch einen eingehenden Webhook). Eigene Module verwenden die Modulfunktionen FpEvent abonnieren / FpEvent senden — Download und Anleitung im Artikel Schnittstellen & APIs.
  • Quellen-ID: Alle Ereignisse identifizieren die Importquelle über ihre stabile ID (Format src- + acht Zeichen, z. B. src-9f3a21c7). Die ID einer Quelle lesen Sie am einfachsten aus einem gesendeten Importereignis ab — etwa per Event-Logging in EventBridge während eines manuellen Importlaufs.

Gemeinsame Felder​

Alle drei Ereignisse tragen neben der Quellen-ID zwei gemeinsame Felder:

FeldTypBeschreibung
triggerStringHerkunft des Laufs: MANUAL (Schaltfläche Jetzt importieren), TIMER (Zeitplan der Quelle), EVENT (Steuerereignis eines anderen Moduls), API (programmatischer Aufruf). Im Steuerereignis optional; fehlt der Wert, gilt EVENT. Start- und Abschlussereignis übernehmen den Wert des Auslösers.
timerNameString, optionalName des auslösenden Timer-Tasks; bei zeitgesteuerten Läufen von DirectoryHub ist das directoryhub-import. Nur bei trigger = TIMER gesetzt, sonst nicht enthalten.

Empfangenes Steuerereignis: ExecuteDirectoryImport​

Stößt den Import einer Quelle sofort an — unabhängig von deren Zeitplan. DirectoryHub führt den Lauf aus und veröffentlicht dazu DirectoryImportStartedEvent und DirectoryImportFinishedEvent.

FeldTypPflichtBeschreibung
sourceIdStringjaID der zu importierenden Quelle. Ereignisse ohne sourceId werden verworfen.
triggerStringneinHerkunftskennzeichnung, wird in die gesendeten Ereignisse übernommen (Standard EVENT).
timerNameStringneinNur sinnvoll bei trigger = TIMER (z. B. wenn ein fremder Zeitplan den Import auslöst).
ExecuteDirectoryImport
{
  "sourceId": "src-9f3a21c7"
}

So senden Drittsysteme das Ereignis:

  • Aus einem eigenen STARFACE-Modul: Modulfunktion Fluxpunkt: FpEvent senden (FpPublishEvent) mit Ereignisname ExecuteDirectoryImport und der Nutzlast als Map oder JSON-Text.
  • Von außerhalb der Anlage: über einen eingehenden EventBridge-Webhook, dessen Aktion das interne Ereignis ExecuteDirectoryImport mit obiger Nutzlast sendet — damit wird der Import per HTTP-Aufruf auslösbar, ohne dass DirectoryHub selbst eine Netzwerkschnittstelle öffnet.
Anwendungsbeispiel

Ein CRM meldet über seinen Automatisierungs-Workflow jede Kontaktänderung an einen EventBridge-Webhook. Die hinterlegte Aktion sendet ExecuteDirectoryImport für die CRM-Quelle — neue Ansprechpartner stehen Minuten später im LDAP-Telefonbuch aller Tischtelefone, statt erst beim nächsten Intervall-Import.

Gesendete Ereignisse​

DirectoryHub veröffentlicht die beiden Ereignisse zu jedem Importlauf — gleich, ob er manuell, zeitgesteuert oder per Steuerereignis ausgelöst wurde.

DirectoryImportStartedEvent​

Wird unmittelbar vor Beginn des Laufs gesendet.

FeldTypBeschreibung
sourceIdStringstabile ID der Quelle
sourceNameStringAnzeigename der Quelle
sourceTypeStringQuelltyp: SQL_JDBC, LDAP_AD, MS_GRAPH, CSV, XML, CARDDAV, VCARD, ODOO, HUBSPOT oder PIPEDRIVE
startedAtZahlStartzeitpunkt (Unix-Zeit in Millisekunden)
trigger / timerNameStringsiehe gemeinsame Felder
DirectoryImportStartedEvent
{
  "sourceId": "src-9f3a21c7",
  "sourceName": "CRM (Odoo)",
  "sourceType": "ODOO",
  "startedAt": 1785826800000,
  "trigger": "EVENT"
}

DirectoryImportFinishedEvent​

Wird nach Abschluss des Laufs gesendet — bei Erfolg wie bei Fehlschlag.

FeldTypBeschreibung
sourceId / sourceName / sourceTypeStringwie im Startereignis
successBooleantrue, wenn der Lauf ohne fatalen Fehler abgeschlossen wurde
readZahlaus der Quelle gelesene Rohdatensätze
upsertedZahlals eigener Kontakt angelegte oder aktualisierte Datensätze
mergedZahlmit einem bestehenden Kontakt (quellenübergreifend) zusammengeführte Datensätze
deletedZahlaus dem Bestand entfernte Kontakte, die in der Quelle nicht mehr vorhanden sind
skippedZahlübersprungene Datensätze (nicht abbildbar oder je Datensatz fehlerhaft)
filteredZahlvom Datensatz-Filter der Quelle ausgeschlossene Datensätze
errorStringFehlermeldung des Laufs; entfällt bei Erfolg
startedAtZahlStartzeitpunkt (Unix-Zeit in Millisekunden)
durationMsZahlLaufdauer in Millisekunden
trigger / timerNameStringsiehe gemeinsame Felder
DirectoryImportFinishedEvent — erfolgreicher Lauf
{
  "sourceId": "src-9f3a21c7",
  "sourceName": "CRM (Odoo)",
  "sourceType": "ODOO",
  "success": true,
  "read": 1284,
  "upserted": 1210,
  "merged": 46,
  "deleted": 12,
  "skipped": 9,
  "filtered": 7,
  "startedAt": 1785826800000,
  "durationMs": 8412,
  "trigger": "EVENT"
}
DirectoryImportFinishedEvent — fehlgeschlagener Lauf
{
  "sourceId": "src-9f3a21c7",
  "sourceName": "CRM (Odoo)",
  "sourceType": "ODOO",
  "success": false,
  "read": 0,
  "upserted": 0,
  "merged": 0,
  "deleted": 0,
  "skipped": 0,
  "filtered": 0,
  "error": "Connection refused: crm.example.de:8069",
  "startedAt": 1785826800000,
  "durationMs": 5031,
  "trigger": "TIMER",
  "timerName": "directoryhub-import"
}

Fehlerbehandlung​

Der Ereignisweg arbeitet nach dem Fire-and-forget-Prinzip: Es gibt keine Empfangsbestätigung. Ein Steuerereignis, das nicht ausgeführt wird, bleibt ohne Start- und Abschlussereignis; die Ursache steht im Modul-Log:

SituationVerhalten
ExecuteDirectoryImport ohne sourceIdVerworfen (Log-Eintrag).
sourceId unbekanntVerworfen mit Log-Eintrag „Unknown source: …"; es werden keine Ereignisse gesendet.
Quelle editionsbedingt inaktiv (Small Business Edition: nur die erste Quelle läuft)Ausführung abgelehnt bzw. bei trigger = TIMER still übersprungen; keine Ereignisse.
Importlauf schlägt fehl (Quelle nicht erreichbar, Zugangsdaten ungültig, …)Regulärer Ereignisfluss: DirectoryImportStartedEvent, danach DirectoryImportFinishedEvent mit success = false und error.
Unbekannte Felder in der NutzlastWerden ignoriert; das Ereignis wird normal verarbeitet.
Unbekannter oder fehlender Wert in triggerWird wie EVENT behandelt.

Das Veröffentlichen der Import-Ereignisse ist best-effort: Ein Fehler beim Senden bricht einen laufenden Import nicht ab.

Versionierung & Kompatibilität​

Ereignisnamen und Feldnamen sind stabile Verträge; Erweiterungen erfolgen additiv (neue optionale Felder, neue sourceType-Werte bei neuen Quelltypen). Verarbeiten Sie Nutzlasten daher tolerant gegenüber zusätzlichen Feldern und unbekannten Werten. Zum Erkunden der tatsächlichen Nutzlasten Ihrer Installation eignet sich das Event-Logging von EventBridge; Änderungen an den Ereignissen dokumentieren die Release Notes der jeweiligen Modulversion.

Inhaltsverzeichnis