Variable

Wertauflöser - Kurzfassung

Zweck: Stellt den Bezug zu einer Variablen im Ausführungskontext für einen Lese- oder Schreibzugriff her und unterstützt dabei Typprüfungen, Typumwandlungen und Nachschlagefunktionen analog zum Eingabeobjekt (Typsicher)-Wertauflöser.

Siehe auch: Wert als Variable speichern, Eingabeobjekt (Typsicher)

images/download/attachments/177908063/image-2024-8-13_9-38-25-version-1-modificationdate-1723534705040-api-v2.png

Der Variable Wertauflöser stellt den Bezug zu einer Variablen im Ausführungskontext für einen Lese- oder Schreibzugriff her. Der Eingabewert wird in beiden Fällen ignoriert.

HINWEIS◄ Der Variable Wertauflöser kann auf der linken Seite einer Setze Wert-Ereignisaktion verwendet werden, um einer Variablen einen Wert zuzuweisen. Oft kann ein "Schreibzugriff" ohne Nachteile auch über den Wert als Variable speichern-Wertauflöser erreicht werden. Dieser ist vielseitiger einsetzbar (z. B. auch in Zuordnungskriterien, wo Ereignisaktionen nicht zur Verfügung stehen) und ermöglicht elegantere Konfigurationen, da z. B. innerhalb einer Wertauflöserkette ein beliebiges Zwischenergebnis buchstäblich "beiläufig" einer Variablen zugewiesen werden kann.

Der Parameter Key definiert dabei den Namen der Variablen, die bei einem Schreibzugriff erzeugt wird, falls sie noch nicht existiert.

Die Parameter Typ und Ist Liste von deklarieren einerseits im Kontext der Konfiguration den für nachfolgende Elemente erwarteten Datentyp.

Andererseits sind die beiden Parameter bei Lese- und Schreibzugriffen auf Variablen abhängig vom Kontext für die folgenden Funktionen analog zum Eingabeobjekt (Typsicher)-Wertauflöser relevant:

Funktion

bei Lesezugriff

bei Schreibzugriff

Typumwandlung
für simple Werte (String, Long, Double usw.)

images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/check.svg automatisch

images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/check.svg automatisch

Nachschlagen eines Aufzählungswerts in der als Typ ausgewählten Aufzählung
ausgehend von einem als Wert übergebenen Textschlüssel, der mit einem je Aufzählung definierten Schlüsselfeld verglichen wird (i. d. R. name, für Einheiten alias)

images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/check.svg automatisch

images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/check.svg automatisch

Nachschlagen einer Entität vom ausgewählten Typ (konkreter Entitätstyp)
ausgehend von einem numerischen Wert für die ID (id) der Entität

images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/check.svg im Server-Kontext unterstützt
images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/error.svg im Client Workflow nicht unterstützt

images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/error.svg nicht unterstützt

Typprüfung gegen den ausgewählten Typ
Prüfen der Klassenzugehörigkeit eines Werts bzw. aller Listeneinträge (wenn Ist Liste von ausgewählt ist):
→ Rückgabewert bei bestanden: geprüfter Wert (ggf. Liste)
→ Rückgabewert bei nicht bestanden: "Kein Wert" ($null)

images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/check.svg automatisch

images/s/-95e2zf/9012/8yg2g7/_/images/icons/emoticons/check.svg automatisch

HINWEIS◄ Die Typprüfung erfolgt immer erst nach den anderen ggf. anwendbaren Funktionen. Verläuft das Nachschlagen oder die Typumwandlung erfolgreich, wird die Prüfung daher immer bestanden. Scheitert eine anwendbare Funktion lautet der Rückgabewert "Kein Wert" ($null), weil danach der ausgewählte Typ nicht vorliegt.

WICHTIG◄ Falls bei einem Schreibzugriff der Variable Wertauflöser mit den Parametern Typ und/oder Ist Liste von auf der Zielseite der Zuweisung (z. B. links in einer Setze Wert-Ereignisaktion) eingesetzt wird, führt das Scheitern einer Typprüfung, Typumwandlung oder des Nachschlagens eines Aufzählungswerts nicht etwa zur Zuweisung von "Kein Wert" ($null), sondern zu einem "stillen" Abbruch der Zuweisung. Die als Ziel definierte Variable behält also ihren vorherigen Wert unverändert bei und der Ausführungskontext wird ohne Fehlermeldung fortgesetzt. Lediglich im Kontext von Tests ist der Abbruch über den Reiter "Log" eine UnsupportedOperatonException nachvollziehbar.

Konfiguration

Der Eingabewert wird vom Variable Wertauflöser (im Unterschied zum Wert als Variable speichern-Wertauflöser) grundsätzlich ignoriert.

Key

Per Standard wird für den Parameter Key ein Textfeld für die direkte Eingabe eines statischen Texts für den Variablennamen eingeblendet.

HINWEIS◄ Um bereits existierende Variablen zu adressieren, muss die Groß-/Kleinschreibung exakt mit dem beim Schreibzugriff verwendeten Variablennamen übereinstimmen.

Direkteingabe eines statischen Texts:

images/download/attachments/177908063/image-2024-8-13_9-39-39-version-1-modificationdate-1723534778634-api-v2.png

Als Alternative zur Direkteingabe können nach einem Klick auf den kleinen grauen Pfeil links unten im Textfeld für die Direkteingabe Wertauflöser konfiguriert werden, die als Rückgabewert eine als Key geeignete Zeichenfolge zurückgegeben sollten.

Sofern beim Klick auf den Pfeil noch kein Text eingegeben wurde, erscheint daraufhin ein Platzhalter für die Konfiguration von Wertauflösern:

images/download/attachments/177908063/image2022-9-29_11-14-14-version-1-modificationdate-1723534694572-api-v2.png


Konfiguration von Wertauflösern:

images/download/attachments/177908063/image-2024-8-13_10-2-5-version-1-modificationdate-1723536124799-api-v2.png

  • Im Beispiel wird über einen Relatives Datum mit Zeit eine benutzerdefinierte Datumsrechnung ausgeführt und für den berechneten Zeitpunkt per Datum formatieren die vierstellige Jahreszahl als Text "aufgelöst".

  • Der umgebende Textverkettung-Wertauflöser verknüpft die Jahreszahl mit einem statischen Text year als Präfix, um abhängig von der Berechnung einen dynamischen Variablennamen wie year2037 oder year1984 als Key zuzuweisen.

ANMERKUNG◄ Die dynamisch zugewiesenen Variable könnte z. B. genutzt werden, um im Kontext einer Schleife über Rohdaten Kennzahlen je Kalenderjahr zu berechnen.

Typ

Der optionale Parameter Typ unterstützt eine statische Einfachauswahl für eine Klasse über ein Auswahlfeld/Combobox. Dessen Suchfunktion (s. Bild rechts) berücksichtigt sowohl Treffer für die anwendbare Lokalisierung sowie den internen Namen der Klasse.

Eine Auswahl für den Typ impliziert eine Typprüfung für den Wert der Variablen und kann - soweit automatische Umwandlungen vorgesehen sind - auch eine Typumwandlung oder ein Nachschlagen von Aufzählungswerten oder Entitäten in Bezug auf den Rückgabewert bewirken.

images/download/attachments/177908063/image-2024-8-13_10-11-35-version-1-modificationdate-1723536694985-api-v2.png

ANMERKUNG◄ Über das [+]-Symbol oder die Eingabetaste könnte die hier als Suchbegriff eingegebene Zeichenfolge range auch als Freitexteingabe für eine (nicht im Dropdown gelistete) Klasse bestätigt werden, was allerdings nur selten beabsichtigt sein dürfte.

Ist Liste von

Die Option Ist Liste von (per Standard abgewählt) spezifiziert, dass es sich beim Wert der Variablen um eine Liste handeln soll. Ist Wert keine Liste gibt der Variable Wertauflöser "Kein Wert" ($null) zurück.

Sofern ausdrücklich ein Typ angegeben ist (s. Bild rechts), impliziert die Auswahl der Option Ist Liste von eine Typprüfung aller Listeneinträge gegen diesen Typ, sodass der Rückgabewert $null lautet, falls mindestens einer dieser Einträge nicht dem ausgewählten Typ entspricht.

images/download/attachments/177908063/image-2024-8-13_10-14-28-version-1-modificationdate-1723536868373-api-v2.png

Die Auswahl des Typs Long und der Option Ist Liste von impliziert eine Typprüfung für den Wert der Variablen companyIds. Enthält die Variable keine Liste (sondern z. B. nur einen einzigen Long-Wert) oder eine Liste, die einen prüfungsrelevanten Eintrag enthält, der kein Long-Wert ist, lautet der Rückgabewert $null.

In Bezug auf in einer Variablen gespeicherte "Listen" ist außerdem zu beachten:

  • Ist die Option Ist Liste von abgewählt (Standard) und kein Typ ausgewählt dann findet keine Typprüfung statt. Man kann auf diesem Weg also nicht spezifizieren, dass nur ein Rückgabewert "erwünscht" ist, der keine Liste ist.

  • Solange die Option Ist Liste von abgewählt ist, wird eine Liste wie jedes andere in einer Variablen gespeicherte Datenobjekt direkt zurückgegeben.

  • Ist beim Zugriff auf eine Liste die Option Ist Liste von abgewählt, dann kann der Parameter Typ für eine Typumwandlung für die Liste als Ganzes genutzt werden.
    Beispiel: Eine Variable route enthält eine normale "Liste" (java.util.List) von String-Werten, die über IATA-Codes von Flugziele entlang eines "Reiseschemas" definiert:
    In JSON-Notation könnte die Liste in der Variablen route für eine "Rundreise" z. B. so aussehen: [MUC,JFK,GIG,CDG,MUC]Wird auf die Variable route per Typ "Liste" (java.util.List) oder ohne Angabe eines Typs zugegriffen, entspricht der Rückgabewert exakt dem gespeicherten Wert.
    Erfolgt der Zugriff auf die Variable route dagegen per Typ "Eindeutige Liste" (java.util.Set), dann wird die "Liste" in eine "Eindeutige Liste" umgewandelt, was die Reihenfolge und die Anzahl der Einträge verändern kann.
    Im konkreten Beispiel könnte der Rückgabewert so aussehen: [GIG,CDG,MUC,JFK]

Beispiele

Einfacher Schreibzugriff (mit und ohne Typumwandlung)

Ein Näherungswert für π/2 (Bogenmaß-Wert für 90°) soll als Dezimalzahl in eine Variable rightAngle geschrieben werden.

Konfiguration:

Innerhalb einer Setze Wert-Ereignisaktion wird der Variable Wertauflöser verwendet, um das Ziel für die Zuweisung zu identifizieren:

  • Der Key ist per Direkteingabe als statischer Text (rightAngle) definiert.

  • Auf die Angabe eines Typs wird verzichtet. Es wird also der Datentyp gespeichert, den die Wertauflöserkette auf der rechten Seite der Zuweisung liefert (hier: "Big Decimal"/java.math.BigDecimal).

images/download/attachments/177908063/image-2024-8-13_10-55-29-version-1-modificationdate-1723539329439-api-v2.png

Ergebnis: (XML-Abbild der Variablen als Eintrag in der storage-Map)


<entry>
<key xsi:type="xsd:string">rightAngle</key>
<value xsi:type="xsd:decimal">0.785398163397448309615</value>
</entry>

Innerhalb der bisherigen Konfiguration wird nun für den Schreibzugriff per Variable Wertauflöser (auf der linken Seite) der Typ "Double" (java.lang.Double) ausgewählt, der das Berechnungsergebnis in der Variablen weniger präzise speichert.

images/download/attachments/177908063/image-2024-8-13_10-56-28-version-1-modificationdate-1723539388474-api-v2.png

Ergebnis: (XML-Abbild der Variablen als Eintrag in der storage-Map)


<entry>
<key xsi:type="xsd:string">rightAngle</key>
<value xsi:type="xsd:double">0.7853981633974483</value>
</entry>

Einfacher Lesezugriff (mit und ohne Typumwandlung/Nachschlagen)

Eine Variable origin enthält einen statischen Text, der ein "Herkunftsland" über den internen Namen eines Werts aus der Dynamischen Aufzählung Land angibt.

In einer Benachrichtigung (per Hinweis anzeigen (Popup)-Ereignisaktion) soll im "Titel" der statische Text und als "Meldung" dessen Lokalisierung wiedergegeben werden.

Laufzeitbeispiel:

images/download/attachments/177908063/image2022-9-29_15-29-30-version-1-modificationdate-1723534694549-api-v2.png

Konfiguration:

In einem Client Workflow (im Kontext eines Formulars) kann eine Hinweis anzeigen (Popup)-Ereignisaktion wie rechts abgebildet konfiguriert werden, um das gewünschte Ergebnis zu erzielen:

  • Im Titel wird über den Variable Wertauflöser auf den in der Variablen origin gespeicherten String-Wert (CN) direkt (per Key origin und ohne Auswahl für den Typ) zugegriffen.

  • In der Meldung wird wiederum der Variable Wertauflöser mit dem Key origin verwendet, um auf die Variable zuzugreifen. Allerdings wird hier als Typ "Land" (Country) ausgewählt. Zur Laufzeit wird dadurch eine Typumwandlung des Textwerts in der Variablen origin in einen Wert aus der Dynamischen Aufzählung Land vorgenommen. Wird dort kein Land vorgefunden, dessen interner "Name" dem Textwert entspricht, wird "kein Wert" ($null) zurückgegeben.

WICHTIG◄ Der Rückgabewert für die Meldung ist bei erfolgreicher Typumwandlung ein Dynamischer Aufzählungswert (DynamicEnumValue), das im Kontext des Parameters Meldung für die Anzeige in der Benachrichtigung wieder in einen String-Wert umgewandelt werden muss. Die String-Umwandlung für den Land-Wert berücksichtigt nur im Client-Kontext (hier: Client Workflow) die anwendbare Lokalisierung. Im Server-Kontext (z. B. in Ereignisbehandlungen) wird dagegen der "Name" als String ausgegeben. Dann zeigen Titel und Meldung im Beispiel CN.

images/download/attachments/177908063/image-2024-8-13_11-0-9-version-1-modificationdate-1723539609223-api-v2.png

Lesezugriff auf eine Liste von Entitäten aus einer Suche im Kontext einer Schleife

Ein typischer Anwendungsfall, in dem eine Variable eine Liste von Entitäten enthält ist das Ausführen einer Suche (Ereignisaktion) vom Typ "Suche" für die der Modus "Suchwert" ausgewählt ist.

Im folgenden Beispiel soll die Suche alle Adressen liefern, die sich auf eine durch eine Liste von Ländern (s. Land) definierten Region beziehen (hier: "Benelux" mit den Länderkennzeichen BE, NL, LU).

Eine Schleife soll anschließend über alle "gefundenen" Adressen iterieren, um statistische Kennzahlen zu ermitteln.

Da eine Suche (Ereignisaktion) nur als Ereignisaktion und nicht als Wertauflöser ausgeführt werden kann, muss bei der Konfiguration per Parameter Ergebnis speichern als der Name einer Variablen angegeben werden, in die das Ergebnis der Suche zur Laufzeit gespeichert wird.

  • In unserem Beispiel sollen Adressen gesucht werden, so dass dieser Entitätstyp im Parameter Entität ausgewählt werden muss.

  • Der Modus "Suchwert" gibt an, dass eine Liste von allen "gefundenen" Entitäten des gewählten Typs zurückgegeben werden soll.

  • Im Parameter Suche muss dazu außerdem die Option "Suche" ausgewählt sein, damit im Ergebnis komplette Entitäten aufgelistet werden und nicht etwa nur Tupel mit ausgewählten Projektionen aus deren Daten.

  • Die Bedingung prüft genau eine Bedingung, nämlich ob der Wert für das Feld "Land" (countryCode) der Adresse in einer Positivliste mit den statisch definierten Aufzählungswerten "Belgien" (BE), "Niederlande" (NL) und "Luxemburg" (LU) enthalten ist.

HINWEIS◄ Die Suche (Ereignisaktion) listet für die Entität "Adressen" nur Adressen auf, auf die im gegebenen Ausführungskontext über Adressbucheinträge zugegriffen werden kann.

images/download/attachments/177908063/image-2024-8-13_15-40-21-version-1-modificationdate-1723556420686-api-v2.png

Die folgende Für jeden Eintrag wiederholen (Schleife)-Ereignisaktion soll über alle "gefundenen" Adressen iterieren. Als Wertauflöser für Einträge wird daher ein Variable Wertauflöser verwendet und wie folgt konfiguriert:

  • Als Key wird der Name der Variablen addrBNL angegeben, der im Parameter Ergebnis speichern als der Suche (Ereignisaktion) (s. o.) willkürlich festgelegt wurde.

  • Als Typ wird wie für den Parameter Entität in der Suche (Ereignisaktion) (s. o.) der Entitätstyp "Adresse" ausgewählt.

  • Die Option Ist Liste von wird ausgewählt, da der Modus "Suchwert" für die Suche (Ereignisaktion) (s. o.) eine Liste von Entitäten des gesuchten Typs liefert.

Entsprechend wird als erwarteter Datentyp (am unteren Ende des Wertauflösers "Adresse[]" ausgewiesen und für den Aktionsblock der Schleife der Typ "Adresse".

images/download/attachments/177908063/image-2024-8-13_14-23-50-version-1-modificationdate-1723551829913-api-v2.png

HINWEIS◄ Auf die Auswahl für den Typ könnte technisch auch verzichtet werden, da alle mit dem Modus "Suchwert" in die Listen-Variable addrBNL übergebenen Einträge vom Entitätstyp "Adresse" sein müssen. Werden keine Einträge gefunden, enthält die Variable eine leere Liste, so dass ohnehin keine Iterationen der Schleife ausgeführt werden. Die Auswahl für den Typ dient hier vor allem der Deklaration des Variableninhalts, so dass dieser in der Konfiguration der Schleife und der enthaltenen Ausführen mit-Ereignisaktion transparent nachvollzogen werden kann und die "richtigen" Elemente (z. B. Wertauflöser) für den Kontext als "passend" angeboten werden.

Lesezugriff auf eine Entität über deren ID in einem Zuordnungskriterium

Ein Zuordnungskriterium (s. Zuordnungskriterien) soll genau dann zutreffen, wenn die folgende Bedingung erfüllt ist:

  • Die angemeldete Firma (Firma der Session) besitzt das zur Anmeldung verwendete Benutzer- oder Gastbenutzerkonto (Benutzer der Session) entweder selbst oder ist Besitzer der Firma, die dieses Konto besitzt.

Man könnte auch formulieren: Der Benutzer der Session soll entweder im Besitz der Firma der Session oder der Firma sein, die diese besitzt.

Die rechts abgebildete Konfiguration für ein Zuordnungskriterium überprüft das oben beschriebene Kriterium im Kontext einer Objekt-Feld-Regel:

  • Auf der linken Seite wird die angemeldete Firma durch den Firma der Session-Wertauflöser ermittelt und deren ID (id) durch einen verketteten Objekt-Feld-Wertauflöser für einen In Liste-Vergleich herangezogen.

  • Auf der rechten Seite wird eine Liste mit den IDs der beiden Firmenkonten zusammengestellt, die laut der Anforderung oben als "akzeptable" Kandidaten im Sinne des Kriteriums gelten sollen:

    • Der erste Kandidat ist der "Besitzer" des angemeldeten Benutzerkontos, das der Benutzer der Session-Wertauflöser zurückgibt.

      • Der verkettete Objekt-Feld-Wertauflöser greif auf dessen Feld "Besitzer" (ownerId) zu, dessen Wert die für den Vergleich relevante ID (id) des betreffenden Firmenkontos enthält.

      • Der verkettete Wert als Variable speichern-Wertauflöser speichert diese ID in der Variablen myOwnerId, da auf das betreffende Firmenkonto zugegriffen muss, um als zweiten Kandidaten deren Besitzer zu ermitteln.

    • Der zweite Kandidat ist der "Besitzer" der Firma die den Benutzer der Session besitzt. Um diesen zu ermitteln, muss das betreffende Firmenkonto ausgewertet werden:

      • Der Variable Wertauflöser liest die in der Variablen myOwnerId gespeicherte ID und schlägt - da diese ein Zahlenwert und der Typ "Firmekonto" ( CompanyAccount) ausgewählt ist, das betreffende Firmenkonto als Rückgabewert nach.

      • Der verkettete Objekt-Feld-Wertauflöser greift dann wie oben auf das Feld "Besitzer" (ownerId) zu, um die "ID" (id) des betreffenden Firmenkontos als Vergleichswert zu liefern.

HINWEIS◄ Anstatt die Variable myOnwerId zu verwenden, könnte man hier auch für den zweiten Kandidaten die Wertauflöserkette beim Benutzer der Session beginnen und die besitzende Firma über das Feld ownerId als Eingabewert für einen Eingabeobjekt (Typsicher)-Wertauflöser nachschlagen, um dann deren ownerId zu erhalten.

images/download/attachments/177908063/image-2024-8-13_15-44-6-version-1-modificationdate-1723556646181-api-v2.png