Erzeuge Instanz

Wertauflöser - Kurzfassung

Zweck: Erzeugt eine neue Instanz, also ein "volatiles" Datenobjekt, für den in der Konfiguration statisch ausgewählten konkreten Typ.

Siehe auch: Erzeuge Instanz mit Werten, Instanz kopieren

images/download/attachments/201662370/image-2025-3-14_11-1-12-version-1-modificationdate-1741946472381-api-v2.png

Der Erzeuge Instanz-Wertauflöser erzeugt eine neue Instanz, also ein "volatiles" Datenobjekt, für den in der Konfiguration statisch ausgewählten konkreten Typ.

Der Eingabewert wird ignoriert.

Falls das Erzeugen des Datenobjekts erfolgreich ist, wird es zurückgegeben.

Schlägt das Erzeugen fehl, wird in den folgenden Fällen "kein Wert" ($null) zurückgegeben:

  • Es wurde kein Typ angegeben.

  • Der ausgewählte Typ ist nicht-konkret, z. B. die übergreifende Klasse für alle Entitäten: "Entität" (de.lobster.scm.entity.Entity).

  • Der ausgewählte Typ ist im Kontext der Lobster Data Platform / Orchestration-Installation nicht bekannt, weil er ein Modul betrifft, das nicht installiert ist.

  • Der ausgewählte Typ ist im Kontext der Lobster Data Platform / Orchestration-Installation nicht bekannt, weil anstelle einer Auswahl ein fehlerhafter Klassenname als Freitext eingegeben wurde (z. B. cutsom.myTypo anstelle von custom.myType).

images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/warning.svg ACHTUNGimages/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/warning.svg Falls eine Klasse für statische oder Dynamische Aufzählungswerte (z. B. Anrede/de.lobster.scm.base.address.Salutation) als Typ ausgewählt wird, tritt zur Laufzeit ein Fehler (Failed to create Instance) auf.

HINWEISE

  • Wird ein eigenständiger Entitätstyp als Typ ausgewählt, dann entspricht das Erzeugen der Instanz für eine neue Entität dem Klick auf "Neu" in einem interaktiven Kontext (s. Erfassungsmasken bzw. Eigene Übersichten) und nicht etwa dem Erstellen beim Klick auf "Speichern". Das Ereignis "Neu" (s. Allgemein (Ereignisse)) wird allerdings nicht ausgelöst.

  • In Ereignisbehandlungen kann eine volatile Entität mit Hilfe der Ereignisaktionen Ausführen mit und Änderungen später speichern zum Speichern beim Abschluss der Transaktion vorgemerkt werden. Bei Bedarf kann vorab auch die Ereignisaktion Primärschlüssel füllen ausgeführt werden, um eine ID für die Entität vom Server zu beziehen.

  • Ein Client Workflow kann eine volatile Entität zu erzeugen, z. B. um deren Daten per Elementdaten setzen einem Formularelement oder eingebetteten Formular zuzuweisen. Auch dann wird die volatile Entität nur persistiert, wenn sie anschließend explizit gespeichert wird.

Konfiguration

images/download/attachments/201662370/image-2025-3-14_11-2-50-version-1-modificationdate-1741946569785-api-v2.png

Für den einzigen Parameter Typ ermöglicht ein Auswahlfeld eine statische Einfachauswahl für die zu instanziierende Klasse.

Wie im Screenshot zu sehen, berücksichtigt die Suchfunktion neben der ggf. anwendbaren Lokalisierung für die Sprache der Sitzung auch den internen Namen. Die Groß- und Kleinschreibung wird dabei ignoriert.

Das [+]-Symbol signalisiert, dass auch nicht im Dropdown auswählbare Klassennamen als Freitext eingegeben werden können.

Beispiele

Ein Datenobjekt des Typs "Datumsbereich mit Zeit" erzeugen und initialisieren

Innerhalb einer Ereignisbehandlung soll eine Variable (enroute) die voraussichtliche Transportzeit einer Sendung als "Datumsbereich mit Zeit" in der Zeitzone angeben, die im Firmenkonto des Auftraggebers als "Default Zeitzone" (defaultTimeZone) ausgewählt ist.

Die voraussichtliche Transportzeit wird dabei durch zwei Variablen vorgegeben, die den voraussichtlichen Startzeitpunkt (ETD) und die voraussichtliche Ankunft (ETA) des Transports jeweils als "Datum mit Uhrzeit" (mit beliebiger Zeitzone) definieren.

Da es sich bei einem "Datumsbereich mit Zeit" nicht um einen simplen Wert handelt, sondern um ein "komplexes" Datenobjekt mit mehreren Feldern ("Zeitzone"/timeZone, "Von"/start und "Bis"/end) muss eine Instanz als Ziel für die notwendigen Wertzuweisungen erzeugt werden.

Die Variable enroute soll hier vor allem weitere Berechnungen innerhalb der Transaktion ermöglichen. Ihr Wert könnte aber ggf. auch einem Datumsattribut der Sendung (z. B. "Voraussichtliche Transportzeit"/ENROUTE_ESTIMATE) als Wert zugewiesen werden.

Konfiguration:

HINWEIS◄ Zum "Initialisieren" einer erzeugten Instanz mit Werten kann auch der Erzeuge Instanz mit Werten-Wertauflöser eingesetzt werden, der das Erzeugen und Initialisieren einer Instanz in eine einzige Konfiguration verdichtet.

Der Erzeuge Instanz mit Werten-Wertauflöser kann die initialisierte Instanz auch in Kontexten als Rückgabewert bereitstellen, in denen keine Ereignisaktionen sondern nur Wertauflöser verüfgbar sind (z. B. Zuordnungskriterien, Einschränkungen).


Da alle drei Felder des "Datumsbereichs mit Zeit" Zuweisungen erhalten sollen, wird wie rechts gezeigt eine Setze Werte-Ereignisaktion verwendet, um die erzeugte Instanz als Zielobjekt für alle Zuweisungen zu verwenden.

  • In der Wert-Konfiguration für das Zielobjekt der Setze Wert-Ereignisaktion wird der Erzeuge Instanz-Wertauflöser verwendet, um den Typ "Datumsbereich mit Zeit" (DateRange) zu instanziieren.

  • Der unmittelbar verkettete Wert als Variable speichern-Wertauflöser speichert eine Referenz auf die erzeugte Instanz in der Variablen enroute. Die Variable verweist also nur auf das neue Datenobjekt und konserviert nicht etwa deren aktuellen Zustand als Schnappschuss. Die Referenz in der Variable ermöglicht den Zugriff auf die erzeugte Instanz über den Kontext der Wertzuweisungen innerhalb der Setze Werte-Ereignisaktion hinaus.

  • Innerhalb der Setze Werte-Ereignisaktion sind drei Zuweisungen konfiguriert, die als Zielwerte Felder im Datenmodell der erzeugten DateRange-Instanz betreffen:

    • Für die Zuweisung an das Feld "Zeitzone" (timeZone) wird auf das Firmenkonto des Auftraggebers (hier in der Variable principalCompany) zugegriffen, in dem im Feld "Standard-Zeitzone" (defaultTimeZone) eine Zeitzone angegeben sein sollte. Das Feld liefert die Kennung der Zeitzone als Text (z. B. Europe/London oder UTC), der im Kontext der Zuweisung automatisch in einen TimeZone-Wert umgewandelt wird.

      ANMERKUNG◄ Per Standard ist die Angabe einer "Standard-Zeitzone" im Firmenkonto optional. Ggf. wäre per Verkettung mit dem Objekt-Feld-Wertauflöser mit einem Standardwert-Wertauflöser zu empfehlen, der z. B. über statischen Text die Zeitzone UTC für den Fall spezifiziert, dass das Firmenkonto keine Angabe enthält.

    • Die Zuweisungen an die Felder "Von" (start) und "Bis" (end) beziehen sich per Definition auf Millisekunden seit 01.01.1970 (UTC), so dass die entsprechenden Werte direkt aus dem Feld "Datumswert" (dateValue) der jeweiligen Variablen vom Typ "Datum mit Zeit" (ETD/ETA) übernommen werden können. Die in diesen Variablen angegebene "Zeitzone" (timeZone) ist dagegen für die Zuweisung unerheblich.


images/download/attachments/201662370/image-2025-3-14_11-9-51-version-1-modificationdate-1741946990954-api-v2.png


Eine "Eindeutige Liste" erzeugen und mit Werten füllen

Ein Administrator soll für Benutzer-Konten in seiner Zuständigkeit einen automatisierten "Health-Check" ausführen können, der einen Katalog von Kriterien für diese Benutzer überprüft und ggf. auf qualitative "Handlungsbedarfe" bei der Verwaltung der Konten hinweist.

Jeder "Handlungsbedarf" wird dabei durch einen Schlüsseltext gekennzeichnet. Jeder Schlüsseltext soll in der Meldung nur max. einmal aufgeführt werden. Hinweise auf die betroffenen Konten sind nicht Bestandteil der Anforderung.

Laufzeitbeispiel:

images/download/attachments/201662370/image-2025-3-14_12-54-34-version-1-modificationdate-1741953273475-api-v2.png

Konfiguration:

Eine Ereignisbehandlung, die über ein eigens eingerichtetes Eigenes Aktionsevent (HEALTH_CHECK) ausgehend vom Ribbon in der Übersicht für Benutzer ausgelöst werden kann, wird wie rechts dargestellt konfiguriert:

  • Eine Suche (Ereignisaktion) ermittelt zunächst alle für die Prüfung relevanten Benutzer und stellt diese als Liste in einer Variablen users bereit.

  • Die folgende Ausführen mit-Ereignisaktion definiert als Bezugsobjekt für den Aktionsteil über der Parameter Objekt Resolver eine neue Instanz vom Typ "Eindeutige Liste" (java.util.Set).

  • Im Aktionsblock wird eine Für jeden Eintrag wiederholen (Schleife)-Ereignisaktion ausgeführt, die über die Benutzer-Konten in der Variablen users iteriert und eine Reihe von Kriterien überprüft. Wird ein "Handlungsbedarf" erkannt, soll der zugehörigen Textschlüssel der "Eindeutigen Liste" hinzugefügt werden, falls er unter den bestehenden Einträgen noch nicht vorkommt.

    HINWEIS◄ Die "Eindeutige Liste" überwacht die Eindeutigkeit der enthaltenen Einträge automatisch. Wie unten gezeigt können die möglicherweise redundanten Textschlüssel einfach per Liste modifizieren an die Liste übergeben werden, für die im den Kontext der Schleife der Variablenname issueTypes gesetzt wurde.

  • Nachdem alle Benutzer-Konten geprüft wurden, gibt die Hinweis anzeigen (Popup)-Ereignisaktion die festgestellten "Handlungsbedarfe" (en: issues) als String-Abbildung der "Eindeutigen Liste" aus. Der Parameter Meldung verweist dazu über einen Objekt-Feld-Wertauflöser "ohne Feld" auf das Bezugsobjekt, also die "Eindeutige Liste".

images/download/attachments/201662370/image-2025-3-14_12-53-12-version-1-modificationdate-1741953192139-api-v2.png

images/download/attachments/201662370/image-2025-3-14_12-55-47-version-1-modificationdate-1741953346971-api-v2.png

Eine Entität erzeugen, initialisieren und erstellen

Innerhalb der Firmenhierarchie sollen Firmen, die sich auf einen bestimmten Firmentyp (z. B. "Logistikzentrum") beziehen, abhängig von der Auswahl für das Adressfeld "Land" (address.countryCode) einer bestimmten "Gruppe" (s. Firmen als Gruppen) zugeordnet werden.

  • Für jedes Land, das erstmals in der Adresse einer relevanten Firma erscheint, soll automatisch eine neue "Gruppe" - also ein Firmenkonto mit dem Firmen-Metatyp "Gruppe" (GROUP) - eröffnet werden.

  • Jede Firma soll per Zuordnung im Feld "Übergeordnete Firmen" (parentCompanies) mit der "Gruppe" verknüpft werden, die für das in der Adresse angegebene Land eingerichtet wurde.

Konfiguration:

Der Screenshot rechts zeigt die Konfiguration für eine Ereignisbehandlung, die auf die Auslösenden Ereignisse "Ändern" und "Erstellen" (s. Allgemein (Ereignisse)) reagiert.


Als Prüfende Regel dient eine UND-Verknüpfung einer Reihe von Regeln (u. a. Typprüfung, Firmentyp-Regel, Rollenregel), auf die hier nicht im Detail eingegangen werden soll. Diese Regeln sollen insgesamt scherstellen, dass die unterhalb definierten Aktionen nur ausgeführt werden, wenn es bezüglich der Gruppenzuordnung für die geänderte oder erstellte Firma "etwas zu tun" gibt.


Auch die Aktionen bei bestandener Regel sollen hier ebenfalls nur im großräumigen Überblick vorgestellt werden, da die Erzeuge Instanz-Ereignisaktion nur einen optionalen Prozessschritt betrifft:

  • Zu Beginn wird eine Suche ausgeführt, die die zum Land der Firma passende "Gruppe" identifizieren soll. Sofern diese bereits existiert, wird sie in die Variable countryGroup geschrieben.

  • Die folgende Wenn Dann Sonst-Ereignisaktion prüft, ob in der Variable countryGroup ein Suchergebnis vorliegt. Falls diese leer ist (s. Ist leer) muss eine zusätzliche Gruppe für das Land angelegt werden. Eine Ausführen mit-Ereignisaktion fass alle notwendigen Schritte dafür zusammen. Diese werden unten im Detail vorgestellt. Die neue angelegte Gruppe wird in die Variable countryGroup geschrieben, die aus der Suche keinen Wert erhalten hat.

  • Abschließend muss noch die "ID" der gefundenen oder erstellten Gruppe (countryGroup) der Liste im Feld "Übergeordnete Firmen" (parentCompanies) hinzugefügt werden, sofern dies erforderlich ist.

images/download/attachments/201662370/image-2025-3-14_17-43-24-version-1-modificationdate-1741970604162-api-v2.png

Für den Kontext der rechts abgebildeten Ausführen mit wird das äußere Bezugsobjekt (das Firmenkonto für das "Logistikzentrum") in die Variable newCompany geschrieben.

Im Objekt-Wertauflöser kommt der Erzeuge Instanz-Wertauflöser mit dem Typ "Firmenkonto" (CompanyAccount)zum Einsatz, der die neue "Gruppe" als temporäres Bezugsobjekt für den folgenden Aktionsblock festlegt:

  • Die Änderungen später speichern-Ereignisaktion bewirkt einerseits die Vormerkung der gerade erzeugten "Firmenkonto"-Instanz für die "Gruppe" zum Speichern am Ende der Transaktion. Andererseits führt diese Aktion dazu, dass dieser Instanz sofort eine eindeutige "ID" (id) zugewiesen wird (s. a. Primärschlüssel füllen).

  • Die Setze Werte-Ereignisaktion erfüllt unterschiedliche Aufgaben:

    • In der Wert-Konfiguration für das Zielobjekt sorgt ein Wert als Variable speichern-Wertauflöser dafür, dass das Firmenkonto für die neue "Gruppe" in die Variable countryGroup geschrieben wird. Es dient unabhängig davon auch ohne besondere Vorkehrungen als Zielobjekt für alle Zuweisungen, soweit diese einen gegebenen Eingabewert berücksichtigen. Im konkreten Fall betreffen alle Zuweisungen Feld der Gruppe.

    • Das Quellobjekt wird aus der Variable newCompany gelesen, die als Schnittstelle zum äußeren Bezugsobjekt - also dem Firmenkonto für das "Logistikzentrum" - fungiert.

    • Dem Feld "Metatyp" (metaType) wird statisch auf den Firmen-Metatyp "Gruppe" (GROUP) gesetzt.

    • Das Adressfeld "Land" (countryCode) wird direkt vom Quellobjekt ins Zielobjekt übernommen.

    • Die Adressfelder "Matchcode" (address.accMatchCode) und "Name" (addressName) werden unter Berücksichtigung der Land-Zuordnung im Quellobjekt mit einer verketteten Zeichenfolge belegt.


images/download/attachments/201662370/image-2025-3-14_17-46-41-version-1-modificationdate-1741970801348-api-v2.png

Laufzeitbeispiel:

Falls erstmalig ein Firmenkonto für ein "Logistikzentrum" mit Bezug zum Land "Italien" (IT) angelegt wird, erstellt die Ereignisbehandlung eine "Gruppe", also ein Firmenkonto mit dem Firmen-Metatyp "Gruppe" (GROUP), dem Text "GROUP_IT" als Matchcode und dem (ggf. vorläufigen) Namen "NEW COUNTRY GROUP: IT". Das Konto wird dem "Logistikzentrum" automatisch als "Übergeordnete Firma" zugeordnet. Der Matchcode soll hier per Konvention das Wiederkennen der für ein Land angelegten Gruppe ermöglichen, sodass die automatisch erstellte "Gruppe" beliebig umbenannt werden kann.