Ereignisaktion - Kurzfassung

Zweck: Merkt das aktuelle Bezugsobjekt für den "Export", also die Übergabe an ein Lobster_data-Profil, am Ende der Transaktion vor.

images/download/attachments/189438746/image-2024-11-20_9-10-20-version-1-modificationdate-1732090220442-api-v2.png

Die Ereignisaktion Export merkt das aktuelle Bezugsobjekt für den "Export", also die Übergabe an ein Lobster_data-Profil, am Ende der Transaktion vor. Details zur Verarbeitung dieser Vormerkungen beschreibt der Abschnitt "Verarbeitungsschema für vorgemerkte Exporte" (unten).

Beim Profilaufruf wird der Datenstand des jeweils vorgemerkten Bezugsobjekts zum Zeitpunkt des Abschlusses der Transaktion als Eingangsdaten (XML) übergeben.
►HINWEIS◄ Handelt es sich bei dem Bezugsobjekt um eine neue Instanz einer Entität, die noch nicht gespeichert wurde, dann beinhalten die Eingabedaten für das Profil deshalb bereits die vom System als Primärschlüssel automatisch zugewiesene ID (id).

Informationen zum anwendbaren Anmeldekontext (Firma, Rolle, Benutzer) werden - wie bei Profilaufrufen aus Lobster Data Platform / Orchestration üblich - automatisch den in Profilen vordefinierten MSG_CALL-Variablen zugewiesen. Diese werden zur Laufzeit abhängig von den Anmeldedaten der Sitzung sowie ggf. unter Berücksichtigung von Anpassungen durch die Ereignisaktion Ausführen als automatisch mit Werten befüllt:

Datenobjekt	Wert	Variablenname (in Lobster_data`)`	Datentyp (in Lobster_data)
Firma der Session	ID (`id`) des Firmenkontos	SCM_Company_id	`BigInteger`
Firma der Session	Datenobjekt Firmenkontos als XML (Text)	SCM_Company_xml	`String`
Rolle der Session	ID (`id`) der Rolle	SCM_Role_id	`BigInteger`
Benutzer der Session	ID (`id`) des Benutzerkontos	SCM_User_id	`BigInteger`
	Benutzername (`username`)	SCM_User_username	`String`
	Datenobjekt des Benutzerkontos als XML (Text)	SCM_User_xml	`String`

Optional können für weitere Variablen Wertzuweisungen zur Übergabe zusätzlicher Daten an das aufgerufene Profil konfiguriert werden.

Verarbeitungsschema für vorgemerkte Exporte

►WICHTIG◄ Da beim Export der Profilaufruf nicht sofort erfolgt, kann im Unterschied zum Aufruf per Profil aufrufen (Ereignisaktion) kein Rückgabewert des aufgerufenen Profils abgewartet und in der Ereignisbehandlung verarbeitet werden.

Falls die auslösende Transaktion durch eine Abbrechen oder einen Fehler nicht erfolgreich abgeschlossen wird, entfallen alle ggf. vorgemerkten Profilaufrufe.

Nur beim erfolgreichen Abschluss einer Transaktion werden sämtliche im Zuge dieser Transaktion vorgemerkten Exporte nach dem folgenden Verarbeitungsschema ausgelöst:

Schritt 1: Profilaufrufe vor dem Commit	Sofern vorhanden, werden zunächst diejenigen Profilaufrufe ausgelöst, die ohne die Option Nach dem Commit ausführen vorgemerkt wurden. Die relevanten Profilaufrufe werden in der Reihenfolge ausgelöst, in der sie im Verlauf der Transaktion vorgemerkt wurden. Sofern für einen Profilaufruf die Option synchron gesetzt ist, wird der ggf. nachfolgende Profilaufrufe erst dann ausgelöst, wenn dieser komplett abgearbeitet wurde. Ist die Option synchron für einen Profilaufruf nicht gesetzt, wird der ggf. nachfolgende Profilaufruf sofort ausgelöst. Werden mehrere Profile nicht-synchron ausgelöst, entscheidet Lobster_data willkürlich über deren Abarbeitungsreihenfolge.
Schritt 2: Commit	Durch den Commit werden innerhalb der Transaktion vorgenommene Manipulationen an Entitäten in der Datenbank von Lobster Data Platform / Orchestration gespeichert, so dass sie u. a. von anschließend ausgeführten Profilaufrufen etwa beim Ausführen einer Suche berücksichtigt werden.
Schritt 3: Profilaufrufe nach dem Commit	Sofern vorhanden werden nach dem Commit diejenigen Profilaufrufe ausgelöst, die mit ausgewählter Option Nach dem Commit ausführen vorgemerkt wurden. Mit den relevanten Profilaufrufen wird wie in Schritt 1 verfahren.
Schritt 4: Ende der Transaktion	Eine Transaktion in Lobster Data Platform / Orchestration, in der mindestens ein Export vorgemerkt wurde, endet - nach der erfolgreichen Abarbeitung aller zugehörigen Ereignisbehandlungen, wenn die folgenden Bedingungen erfüllt sind: Alle synchronen Profilaufrufe wurden ausgelöst und von Lobster_data abgearbeitet. Alle asynchronen Profilaufrufe wurden ausgelöst.
Schritt 4: Ende der Transaktion	ACHTUNG Wenn ein Export innerhalb einer "schreibenden" Transaktion im Kontext einer Entität vorgemerkt wird, auf die ein ausgelöstes Profil entweder lesend oder schreibend zugreifen soll, kann ein Dead-Lock auf der Datenbankebene auftreten, wenn die Option synchron - wie im Standard - ausgewählt und die Option Nach dem Commit ausführen - wie im Standard - abgewählt ist. Denn in diesem Szenario wartet die aufrufende Transaktion in Lobster Data Platform / Orchestration vor dem Commit auf die Abarbeitung des Profils, das wiederum auf den Commit abwartet, bevor der lesende oder schreibende Zugriff (z. B. durch eine Suche oder einen Import) ausgeführt wird. Effektiv resultiert dann eine akute Blockade der betreffenden Datenbanktabelle(n), die nur aufgelöst werden kann, indem die blockierenden Datenbank-Sitzungen durch per Administratorzugriff beendet werden.

Konfiguration

images/download/attachments/189438746/image-2024-11-20_9-10-36-version-1-modificationdate-1732090235937-api-v2.png

Der Parameter Profilname identifiziert das aufzurufende Profil. Passend zur Eingabe im Textfeld werden existierende Profilnamen per "Autovervollständigung" in einer Dropdown-Liste vorgeschlagen.
►HINWEIS◄ Im Unterschied zur Konfiguration von Verhaltensweisen wie Profil aufrufen im Formulardesigner ist der Zugriff auf Profile in Ereignisbehandlungen nicht an Profilsicherheiten gebunden.

Optionen für die Ablaufsteuerung

Die Option synchron ist per Standard ausgewählt. Sie entscheidet, ob die Abarbeitung der Profilaufrufe in die Transaktion eingebettet wird oder nicht.

Option "synchron"	Laufzeitverhalten
	Ein "synchroner" Profilaufruf muss vollständig abgearbeitet sein, bevor nachfolgende für denselben Verarbeitungsschritt (vor/nach Commit, s. o.) vorgemerkte Profilaufrufe ausgelöst werden. Falls die Transaktion interaktiv ausgelöst wurde, rotiert bis zum Abschluss der Transaktion das Icon im Fenstertitel der betreffenden View.
	Ein "asynchroner" Profilaufruf wird nur ausgelöst, also an Lobster_data zur Verarbeitung übergeben, ohne dass nachfolgende für denselben Verarbeitungsschritt (vor/nach Commit, s. o.) vorgemerkte Profilaufrufe die Abarbeitung abwarten müssen. Werden mehrere asynchrone Profilaufrufe durch dieselbe Transaktion ausgelöst, kann Lobster_data diese parallel abarbeiten. Die Reihenfolge der Auslösung ist dann nicht bindend für die Reihenfolge der Abarbeitung.

Die Option Nach dem Commit ausführen ist per Standard nicht gesetzt. Sie definiert ob die vorgemerkten Profilaufrufe beim Abschluss der Transaktion vor oder nach dem Commit der Transaktion ausgeführt werden sollen.

Option
"Nach dem
Commit ausführen"

Laufzeitverhalten

Der Profilaufruf wird nach dem Commit (s. Schritt 3 im "Verarbeitungsschema" oben) ausgeführt.
Manipulationen an Entitäten (Erstellen, Ändern, Löschen), die im Zuge der Transaktion vorgenommen wurden, werden dann z. B. beim Ausführen einer Suche im Profilaufruf berücksichtigt.

Der Profilaufruf wird vor dem Commit (s. Schritt 1 im "Verarbeitungsschema" oben) ausgeführt.
Manipulationen an Entitäten (Erstellen, Ändern, Löschen), die im Zuge der Transaktion vorgenommen wurden, werden dann z. B. beim Ausführen einer Suche im Profilaufruf nicht berücksichtigt.

►HINWEIS◄ Das als Eingabewert an das Profil übergebene Bezugsobjekt beinhaltet dagegen Manipulationen am Bezugsobjekt innerhalb der Transaktion auch ohne Commit.

Variablen

Der Abschnitt Variablen bietet ein Wiederholendes Element an, in dem über die Symbole und Wertzuweisungen für Variablen definiert werden können.

Die Zuweisungen für diese Variablen gelten nur für den Kontext des Profilaufrufs.
Im Profil muss eine Variable definiert sein, die das Prafix MSG_CALL_ vor dem Eintrag für Variablenname verwendet.
Die für den Parameter Wert konfigurierten Wertauflöser werden zur Laufzeit in dem Moment aufgelöst, wenn die Ereignisaktion Export ausgeführt wird. Allerdings ist der Hinweis unten zu beachten, wenn der Variablen ein Datenobjekt als Wert zugewiesen wird!

images/download/attachments/189438746/image-2024-11-20_9-27-20-version-1-modificationdate-1732091240882-api-v2.png

Wie das Beispiel der zweiten Variablen attachment im Bild verdeutlicht, erscheint abhängig vom Typ des Rückgabewerts des Wertauflösers ggf. zusätzlich die Option Als Datei übergeben.

Wird die Option Als Datei übergeben gesetzt, dann wird der Rückgabewert des Wertauflösers nicht direkt der Variablen zugewiesen, sondern eine Pfadangabe zu einer Temporärdatei, in die der entsprechende Inhalt beim Profilaufruf geschrieben wird. Nach dem Profilaufruf werden solche Temporärdateien automatisch wieder gelöscht.

►HINWEIS◄ Wird einer Variablen in Lobster Data Platform / Orchestration ein Datenobjekt als Wert zugewiesen, dann speichert die Variable nur eine Referenz auf dieses Datenobjekt und nicht etwa einen Schnappschuss der Daten des Datenobjekts. Erst zum Zeitpunkt des Profilaufrufs wird bei der Wertzuweisung an die MSG_CALL-Variable des Profils das Datenobjekt als XML-Text ausgegeben und dadurch "eingefroren". Veränderungen am Datenobjekt durch Ereignisaktionen, die nach dem Export aber noch innerhalb derselben Transaktion ausgeführt werden, verändern betreffen daher immer auch den Wert der Profilvariablen beim Export. Der Profilvariable kann allerdings bei Bedarf ein Schnappschuss eines Datenobjekts zum Zeitpunkt der Ausführung der Ereignisaktion Export zugewiesen werden, indem der Wertauflöser das Datenobjekt per Verkettung z. B. an den Wertauflöser Server XML aus Objekt erzeugen übergibt, um das zurückgegebene XML als Textwert sofort der Variablen zuzuweisen, die später an das Profil übergeben wird.

Beispiele

Einfaches Beispiel

Immer dann, wenn eine in Lobster Data Platform / Orchestration neu erfasste Sendung erstellt, also erstmalig gespeichert, wird, sollen deren Daten über einen Profilaufruf an ein über Lobster_data angebundenes Transport-Management-System (TMS) übertragen werden.

Aus der Sicht von Lobster Data Platform / Orchestration handelt es sich bei diesem Vorgang um einen "Export", der über das eigens eingerichtete Lobster_data-Profil eine Import-Schnittstelle des TMS adressiert. Im vorliegenden Fall wird angenommen, dass für die Neuanlage keine unmittelbare Rückmeldung oder Empfangsbestätigung vom TMS zu erwarten ist, die in Lobster Data Platform / Orchestration synchron verarbeitet werden müsste.

Konfiguration:

Für das Auslösende Ereignis "Erstellen" (s. Allgemein (Ereignisse)) eine Ereignisbehandlung wie rechts abgebildet konfiguriert.
Die Prüfende Regel stellt per Typprüfung sicher, dass der Export nur beim Erstellen von Sendungen ausgeführt wird.
Als Aktion bei bestandener Regel wird die Ereignisaktion Export wie abgebildet konfiguriert. Das per Profilname adressierte Lobster_data-Profil PRO2TMS_NEW_SHIPMENT wird demnach synchron aufgerufen, soll aber vor dem Commit ausgeführt werden. Beide Optionseinstellungen entsprechen also dem Standard. Zusätzliche Variablen werden nicht verwendet.

►ANMERKUNG◄ Dass der Aufruf synchron erfolgt, bewirkt hier vor allem, dass für den Benutzer nachvollziehbar ist, wann der Transfer der Daten über das Profil komplett abgearbeitet ist.

images/download/attachments/189438746/image-2024-11-20_9-41-43-version-1-modificationdate-1732092103282-api-v2.png

Komplexeres Beispiel

Immer dann, wenn eine bestehende Sendung in Lobster Data Platform / Orchestration geändert (also nach dem Erstellen erneut gespeichert) wird, soll jede Sendungsposition individuell und abhängig von ihren Trackingstatus an eine bestimmte Schnittstelle zum Transport-Management-System (TMS) übergeben werden.

Wenn der Trackingstatus einer Sendungsposition aus der Perspektive des Versenders final ist ("Versandfertig" oder "Storniert"), soll das Profil PRO2TMS_LINE_ITEM_FINAL ausgeführt werden.
Mit allen anderen Trackingstatus gilt eine Sendungsposition noch als volatil, also nicht endgültig definiert. Dann soll das Profil PRO2TMS_LINE_ITEM_VOLATILE ausgeführt werden.
In beiden Fällen soll das Profil das gesamte Datenobjekt der Sendung als Eingangsdaten erhalten, während die ausschlaggebende Sendungsposition nur durch Angabe der internen id als Wert einer Variablen itemId (im Profil MSG_CALL_itemId) identifiziert werden soll.
Aus technischen Gründen auf der TMS-Seite der Schnittstelle müssen die "volatilen" Positionen strikt seriell und in der gegebenen Reihenfolge übergeben werden, während die "finalen" Postionen erst danach und in beliebiger Reihenfolge folgen dürfen.

Konfiguration:

Ausgehend vom Auslösenden Ereignis "Ändern" (s. Allgemein (Ereignisse) wird durch die Prüfende Regel per Typprüfung sichergestellt, dass die folgenden Aktionen bei bestandender Regel nur für Sendungen ausgeführt werden.

Dann wird eine Für jeden Eintrag wiederholen (Schleife) über Direkte Positionen vom Typ "Standard" ausgeführt, wobei die Sendung aus dem Eingabewert der Ereignisbehandlung in der Variable shipment gespeichert wird.
Innerhalb der Schleife wird per Wenn Dann Sonst die Fallunterscheidung zwischen "finalen" und "volatilen" Trackingstatus-Codes für die jeweilige Sendungsposition ausgewertet.
In beiden Ästen (Dann/Sonst) der Fallunterscheidung folgt danach der Aufruf der Ereignisbehandlung Export, innerhalb einer Ausführen mit-Ereignisaktion, die das Bezugsobjekt für den Export temporär von der Sendungsposition zur übergeordneten Sendung verschiebt. Dabei wird die Sendungsposition in die Variable lineItem gespeichert, damit ihre id beim Export unter Variablen als Wert der Variablen itemId zugewiesen werden kann.
Der Export für die "volatilen" Positionen (im Sonst-Zweig, unten rechts) wird mit der Option synchron und ohne die Option Nach dem Commit konfiguriert, damit die entsprechenden Profilaufrufe seriell und vor denen für "finale" Positionen stattfinden.
Der Export für die "finalen" Positionen (im Dann-Zweig, unten links) wird ohne die Option synchron und mit der Option Nach dem Commit konfiguriert, so dass die entsprechenden Profilaufrufe nach dem Commit und damit der Abarbeitung aller synchron ausgeführten Profilaufrufe für "finalen" Positionen ausgelöst werden. Ohne die Option synchron werden diese Profilaufrufe nahezu gleichzeitig ausgelöst. Danach endet die Transaktion aus der Perspektive von Lobster Data Platform / Orchestration, ohne dass die Abarbeitung der Profilaufrufe abgewartet wird.