Berechne Wert

Wertauflöser - Kurzfassung
Zweck: Führt mathematische Operationen mit numerischen Werten (mit und ohne Einheit) aus, und liefert in der Regel das Berechnungsergebnis als "Zahl mit Einheit" als Rückgabewert.
Tooltip
Verwendung: Der Wertauflöser beinhaltet eine statische Definition für einen Berechnungsausdruck, der Variablen aus dem inneren und äußeren Kontext des Wertauflösers einbeziehen kann, sofern diese die numerische Werte oder Textinhalt bereitstellen, der als Zahlenwert interpretierbar ist.
Parameter: Zum Editieren eines Berechnungsausdrucks (mit Konstanten, Variablen, Operatoren, Funktionen) steht ein mehrzeiliges Code-Eingabefeld zur Verfügung, dessen Größe nach Bedarf verändert werden kann.
Optional können beliebig viele Wertzuweisungen für Variablen über Wertauflöser hinzugefügt werden. Der Variablenname sollte sich dabei möglichst nicht identisch mit dem Alias von Einheiten (z. B. b, l, m, D, H, M, usw.) gewählt werden.
Variablen aus dem äußeren Kontext des Wertauflösers (storage) stehen auch ohne Zuweisung direkt zur Verfügung, sofern kein Namenskonflikt mit den Alias von Einheiten besteht.
Auch der Eingabewert (input) und das Bezugsobjekt (entity) können direkt im Berechnungsausdruck referenziert werden, sofern sie numerisch interpretierbare Werte beinhalten.
Exklusiv für den Eingabewert (input) werden im Berechnungsausdruck außerdem Datenfeldpfade für den Zugriff auf numerisch interpretierbare Feldwerte aufgelöst (z. B. input.numericProperty).
Hinweis: Bei syntaktischen Fehlern (z. B. fehlerhafter Klammersetzung) lautet der Rückgabewert $null. Mathematische "Unmöglichkeiten" (z. B. eine "Division durch Null") werdend dagegen als Fehler (ggf. mit Rollback) behandelt.
Warnung: Der Wertauflöser unterstützt Umrechnungen zwischen Einheiten desselben Typs (per convert()-Funktion und teilweise automatisch), hat aber weder hellseherische Fähigkeiten noch ein Ingenieur-Studium absolviert. Ein Produkt aus drei Werten mit Längeneinheiten erscheint daher nicht automatisch als "Volumen" sondern formal als "Länge".

images/download/attachments/201666907/image-2025-3-5_15-2-13-version-1-modificationdate-1743580304085-api-v2.png

Der Berechne Wert-Wertauflöser ermöglicht mathematische Operationen mit numerischen Werten (mit und ohne Einheit), und liefert in der Regel das Berechnungsergebnis als "Zahl mit Einheit" als Rückgabewert.

Ausnahmen:

Der Berechnungsausdruck ist leer oder syntaktisch fehlerhaft (z. B. bzgl. Klammersetzung). Dann lautet der Rückgabewert "Kein Wert" ($null), es tritt aber kein Fehler auf.
Der Berechnungsausdruck ist syntaktisch einwandfrei, aber nicht berechenbar. Dann tritt zur Laufzeit ein Fehler auf (z. B. ArithmeticException: Division by zero).

Prinzipiell kann ein Berechnungsausdruck ausschließlich dem Zweck dienen, eine "Zahl mit Einheit" statisch (per Texteingabe in der Konfiguration) zu definieren, etwa: 7.5t für die Definition eines Maximalgewichts von "7,5 Tonnen".

In den meisten Fällen verknüpft die Berechnung aber variable Eingangsgrößen, die mindestens teilweise über Variablen bereitgestellt werden.

Der Berechnungsausdruck kann aus unterschiedlichen Komponenten aufgebaut werden:

Komponententyp	Syntax / Beispiel	Beschreibung	Beispielausdrücke	Ergebnis (Beispiel)
Konstante numerische Werte (mit und ohne Einheiten)	`<Wert>[<Alias der Einheit>]` oder `<Alias der Einheit`>(dann wird als Wert `1` angenommen)	►WICHTIG◄ Unabhängig von Einstellungen für die Aktuelle Sprache ist die Eingabe des Punkts als Dezimaltrenner im verpflichtend. Die Einheit einer Konstante muss nachgestellt erscheinen und über den Alias aus der betreffenden Dynamischen Aufzählung identifiziert werden. Leerzeichen zwischen Wert und Einheit sind optional.	`-1.024` `1250kg` `123456 USD` `USD (= 1 USD)ft (= 1 ft)m3 (= 1 m3)`	Konstante "Zahl mit Einheit" (`UnitNumber`), deren Feld "Wert" (`value`) eine vorzeichenbehaftete Kommazahl angibt und im optionalen Feld "Einheit" (`unit`) auf eine der konfigurierten Einheiten
Vorbelegte Konstanten (übersteuern Zuweisungen an Variablen mit demselben Namen)	`pi`	Kreiszahl π (3.1415926535897932384...)	`radius^2*pi`	Kreisfläche für einen Kreis mit dem per Variable `radius` definierten Radius
	e	Eulersche Zahl e (2.7182818284590452353...)	`ln(e)`	`1`
Automatisch vorbelegte Variablen (können durch ausdrückliche Zuweisungen für den denselben Variablennamen im inneren Kontext (s. u.) des Berechne Wert-Wertauflösers übersteuert werden)	`input` Eingabewert	Per Standard wird die Variable `input` mit dem Eingabewert vorbelegt, sofern dieses in einen Zahlenwert umgewandelt werden kann.	`input*1.19`	Berechnet einen Bruttobetrag (mit einem Steuersatz von 19%), wenn als Eingabewert (`input`) ein Nettobetrag anliegt
		►HINWEIS◄ Exklusiv für den Eingabewert (`input`) werden Datenfeldpfade für den Zugriff auf numerisch interpretierbare Feldwerte aufgelöst (z. B. `input.numericProperty`), sodass z. B. mehrere Felder des Eingabewerts verrechnet werden können, ohne dass diese dazu auf individuelle Variablen abgebildet werden müssten.	`input.end-input.start` `(input.end-input.start)ms` `convert((input.end-input.start)ms,H)`	Berechnet die Zeitspanne für einen Eingabewert vom Typ "Datumsbereich" (`DateRange`) im Beispiel links in drei Varianten: als Skalar (in Millisekunden) in der Zeiteinheit "Millisekunden" (`ms`) umgerechnet in die Zeiteinheit "Stunden" (`H`)
			►HINWEIS◄ Für Rückgabewerte des Relatives Datum mit Zeit-Wertauflösers sollte der Ausdruck für die Zeitspanne in Millisekunden in der Regel `(1ms+input.end-input.start)` lauten, da der `end`-Wert per Standard 1ms zu früh definiert ist.
	`entity`	Sofern das Bezugsobjekt im Kontext des Wertauflösers ein Zahlenwert (mit oder ohne Einheit) ist oder in einen Zahlenwert umgewandelt werden kann, steht dieser über den Variablennamen `entity` zur Verfügung.	`convert(input,entity)`	Rechnet den Eingabewert in die Einheit einer "Zahl mit Einheit" um, die als Bezugsobjekt vorliegt
	`$index` `$length`	Aktueller Iterationsindex (`$index`) und planmäßige Anzahl der Iterationen (`$length`) innerhalb einer Für jeden Eintrag wiederholen (Schleife)-Ereignisaktion	`round(($index+1)/$length*100)`	"Fortschritt": Abarbeitungsgrad bzgl. der Iterationen beim Ausführen einer Schleife (in Prozentpunkten)
	►HINWEIS◄ Abhängig vom Kontext (z. B. abhängig von Ereignissen oder der Auswahl in einer Übersicht) können weitere Variablen automatisch vorbelegt sein. Allerdings können diese (wie auch die Variable `entity`) nur in Ausnahmefällen direkt in einem Berechnungsausdruck verwendet werden, da sie überwiegend komplexere Datenobjekte enthalten und nicht, die im Beschriftungsausdruck erwarteten numerische Werte.
Variablen aus dem äußeren Kontext (`storage`) des Wertauflösers (können durch ausdrückliche Zuweisungen für den denselben Variablennamen im inneren Kontext (s. u.) des Berechne Wert-Wertauflösers übersteuert werden)	Grundsätzlich können beliebige Variablennamen innerhalb von Beschriftungsausdrücken verwendet werden. Allerdings sind die rechts aufgeführten Einschränkungen zu beachten. Um zu verhindern, dass Variablennamen wie "17+4" oder "2022m3" im Ausdruck berechnet bzw. geparst werden, können sie im Ausdruck in einfache oder doppelte Hochkommas eingeschlossen werden. Das ermöglich auch den Einsatz von Leerzeichen im Variablennamen. Als Escape-Zeichen (z. B. für Hochkommas als Textzeichen) kann innerhalb von Hochkommas außerdem der Backslash genutzt werden.	►WICHTIG◄ Die Namen der vorbelegten Konstanten `e` und `pi` (in Kleinschreibung) werden in Berechnungsausdrücken niemals als Variablen aufgelöst. Ein Berechnungsausdruck kann auf den Wert von Variablen im Kontext (`storage`), deren Name exakt (inkl. Groß-/Kleinschreibung) mit dem Alias für eine Einheit (s. Einheiten) übereinstimmt, nicht direkt zugreifen. Der Versuch auf eine Variable mit dem Namen `b` zuzugreifen scheitert z. B. weil dieser Buchstabe per Standard als Alias für die (Größeneinheit "Bit" gilt. Ein Ausdruck wie `1+b` liefert daher "2 Bit". Auch Hochkommas - etwa `1+'b'` - beheben dieses Problem nicht! Allerdings können Variablen mit Alias-Namen explizit für den Kontext des Wertauflösers definiert werden (s. nächste Zeile). Dann kann allerdings die betreffende Einheit nicht in demselben Berechnungsausdruck verwendet werden.	`profit` `profit2020` `profit_2020` `"1D"'1D'` `"2020_profit"` `'2020_profit'` `"2020-profit"'2020-profit'` `"Profit 2020"'Profit 2020'` `"Inbound/Outbound"'Inbound/Outbound'` `"Sales 'AOB'"'Sales \'AOB\''`	Falls der Wert einer Variable kein Zahlenwert oder eine "Zahl mit Einheit" ist, wird versucht, deren Inhalt als Zahl zu interpretieren. Dabei wird für komplexere Datenobjekte (z. B. Werte von Dynamischen Aufzählungen) nicht automatisch das String-Abbild herangezogen. Nur wenn die Variable bereits einen String wie `1.5e2` als Wert enthält, kann dieser als Zahlenwert (`1500`) gelesen werden. Scheitert die Umwandlung in einen Zahlenwert, dann wird als Wert der Variablen stattdessen der Wert 0 (ohne Einheit) verwendet.
Eigens definierte Variablen für den (inneren) Kontext des Wertauflösers	Innerhalb der Konfiguration des Wertauflösers können per Klick auf das Symbol beliebig viele ausdrückliche Wertzuweisungen für bestehende oder neu eingeführte Variablen (mit dem angegebenen Variablennamen) hinzugefügt werden, die nur innerhalb des Berechnungsausdrucks gelten. Zuweisungen für den Kontext der Berechnung verändern den Wert von im äußeren Kontext bereits definierten Variablen nicht. Sie werden im inneren Kontext nur temporär übersteuert, so dass die "äußeren Werte" nicht in die Berechnung einfließen können.	►WICHTIG◄ Die Namen der vorbelegten Konstanten `e` und `pi` (in Kleinschreibung) werden in Berechnungsausdrücken niemals als Variablen aufgelöst. Zuweisungen für Variablennamen, die exakt mit dem Alias für eine Einheit (s. Einheiten) übereinstimmen sind möglich. Der entsprechende Alias kann dann allerdings nicht wie sonst üblich in demselben Berechnungsausdruck verwendet werden. (s. Beispiel rechts)	►WICHTIG◄ Um das Berechnungsergebnis in Tagen auszugeben, kann hier nicht einfach die Umrechnung per `convert(D24-2.5H,D)` genutzt werden, weil `D` hier temporär* als Long-Wert ohne Einheit gilt und nicht als "1 Tag"!
	Das Beispiel rechts demonstriert, wie der Alias `D` (für die Zeiteinheit "Tag") temporär durch eine Zuweisung für den Variablennamen `D` übersteuert wird, weil im speziellen Kontext die Variable `D` eine bestimmte "Anzahl Tage" (ohne Einheit) angeben soll. Für einen Wert von `D = 1` ergibt der Berechnungsausdruck konkret `1*24-2.5H = 21.5 (Stunden)`, wobei der im Minuenden verwendete Alias `H` die Einheit "Stunden" für den Ergebniswert beisteuert.
Klammern	( <Ausdruck> )	Paare von Klammern strukturieren Aggregate bzw. grenzen enthaltene Ausdrücke aus Operatoren und Operanden (Konstanten, Variablen, Funktionen) gezielt voneinander ab, um den Vorrang zwischen Operatoren explizit zu regeln.	`5+4*3^2`	`149 = 5+(4*3)²`
			`5+4*(3^2)`	`41 = 5+4*(3²)`
			`(5+4)*3^2`	`729 = (9*3)²`
			`(5+4)*(3^2)`	`8 = 9 * 9`
			`8^2/3`	`21,333... = 64/3`
			`8^(2/3)`	`4 = cbrt(8^2)`
			`sqrt((width)^2+(width/16*9)^2)`	Diagonale eines 16:9-proportionierten Rechtecks mit der Breite laut Variable `width`
Operatoren	`+`	Addition bzw. positives Vorzeichen	`1250kg + 2.5t`	`3750kg`
	`-`	Subtraktion bzw. negatives Vorzeichen	`actual - target`	Differenz zwischen Ist- und Sollwert in je einer Variablen
	`*`	Multiplikation	`bottomLine * 1.25`	Aufschlag von 25% auf einen Saldowert in der Variablen `bottomLine`
	`/`	Division	`profit/capita` `EUR/CHF`	"Gewinn pro Kopf" "Wechselkurs" für Schweizer Franken (CHF) im Sinne einer Mengennotierung (mit 1 EUR als Bezugsgröße in "Heimatwährung") anhand der Umrechnungsfaktoren in der Aufzählung Währung; s. a. `convert()`-Funktion
	`%`	Modulo (Rest der Ganzzahl-Division)	`totalPallets % 24`	Anzahl der Paletten für eine Teilladung, wenn das in der Variablen `totalPallets` angegebene Transportaufkommen in Container mit je 24 Palettenplätzen füllen soll
	`^`	Potenzieren (für Quadratwurzel im Beispiel wäre alternativ die Funktion `sqrt()` geeignet)	`squaredErrors^0.5`	Quadratwurzel ("hoch 1/2") der in der Variablen `squaredErrors` aggregierten "Summe der Fehlerquadrate"
Funktionen	`abs(a)`	Absolutbetrag ohne Vorzeichen (math.: \|a\|)	`abs(target-actual)`	Absolutbetrag der Differenz von Soll- und Ist-Werten in Variablen
	`sgn(a)`	Signum-Wert: 1 für (a>0), -1 für (a<0), 0 für (a=0)	`sgn(target-actual)`	"Vorzeichenwert" der Differenz von Soll- und Ist-Werten in Variablen
	`ceil(a)`	Aufrunden zur nächsthöheren Ganzzahl	`ceil(totalPallets)`	Anzahl der benötigten Container (mit je 24 Palettenplätzen) für die in der Variablen `totalPallets` angegebenen Palettenanzahl
	`floor(a)`	Abrunden zur nächstkleineren Ganzzahl	`floor(totalPallets/24)`	Anzahl der komplett beladenen Container (mit je 24 Palettenplätzen) für die in der Variablen `totalPallets` angegebene Palettenanzahl
	`round(a)`	ganzzahliges Runden (ab 0.5 wird aufgerundet)	`round(profit/capita/1000)*1000`	"Gewinn pro Kopf" (aus Variablen) gerundet auf 1000 Währungseinheiten
	`min(a,b)`	Minimum von zwei Werten	`min(actual,estimate)`	der kleinere Wert aus zwei Variablen für "Ist" und "Schätzung" einer Größe
	`max(a,b)`	Liefert den größeren der beiden Werte	`max(actual,estimate)`	der größere Wert aus zwei Variablen für "Ist" und "Schätzung" einer Größe
	`sqrt(a)`	Quadratwurzel, sinngemäß: `a^(1/2)`	`sqrt(squaredErrors)`	Quadratwurzel der in der Variablen `squaredErrors` aggregierten"Summe der Fehlerquadrate"
	`cbrt(a)`	Kubikwurzel, sinngemäß: `a^(1/3)`	`cbrt(totalVolume*0.75/pi)`	Radius einer Kugel mit dem in der Variablen `totalVolume` angegeben Rauminhalt
	`ln(a)`	Natürlicher Logarithmus von a	`ln(maxNumber)/ln(2)`	Der Binärlogarithmus des Werts in der Variablen `maxNumber`.
	`log(a)`	Logarithmus zur Basis 10	`log(actual/target)`	Die "Größenordnung" der Abweichung zwischen einem Ist- und einem Soll-Wert (in Variablen) als signierte Zehnerpotenz (z. B. -`1` wenn der Ist-Wert nur ein Zehntel vom Soll beträgt)
	`convert(a,b)`	Umrechnen von Wert a in die Einheit von Wert b	`convert(load,capacity)`	Umrechnen der Fracht(menge) in der Variablen `load` in die Einheit der Kapazitätsangabe (Variable `capacity`)
	`convert(a,b)`	Umrechnen von Wert a in die Einheit von Wert b	`convert(totalCost,EUR)`	Umrechnen der Gesamtkosten in der Variablen `totalCost` in die Währung `EUR`
	`deg(a)`	Bogenmaß-Winkel a in Winkelgrad umrechnen	`deg(atan(-1))`	`-45 (°)` (`atan()` liefert Bogenmaß)
	`rad(a)`	Grad-Winkel a in Bogenmaß umrechnen	`sin(rad(30))`	`0.5` (`sin()` erwartet Bogenmaß)
	`sin(a)`	Sinus-Wert für Bogenmaß-Winkel a	`sin(pi/2)`	`1.0` (`pi/2` = 90°)
	`cos(a)`	Cosinus-Wert für Bogenmaß-Winkel a	`cos(pi/2)`	`0.0` (`pi/2` = 90°)
	`tan(a)`	Tangens für Bogenmaß-Winkel a	`tan(pi/4)`	`1.0` (`pi/4` = 45°)
	`asin(a)`	Arkussinus-Wert (im Bogenmaß) für a (Sinuswert)	`asin(1)/pi`	`0.5` (`pi/2` = 90°)
	`acos(a)`	Arkuscosinus-Wert (im Bogenmaß) für a (Cosinuswert)	`acos(0)/pi`	`0.5` (`pi/2` = 90°)
	`atan(a)`	Arkustangens-Wert (im Bogenmaß) für a (Tangenswert)	`deg(atan(1))`	`45 (°)`(`atan()` liefert Bogenmaß)
	`sinh(a)`	Sinus-hyperbolicus-Wert für a	`sinh(0)`	`0`
	`cosh(a)`	Consinus-hyperbolicus-Wert für a	`cosh(0)`	`1`
	`tanh(a)`	Tangens-hyperbolicus-Wert für a	`tanh(0)`	`0`

Beispiele

Berechnen einer Zeitspanne in Tagen mit Dezimalen

Über den Lobster Data Platform / Orchestration-Server können Benutzer besondere betriebliche Vorfälle (Störungen, Unfälle, Verzögerungen usw.) melden, indem sie eine Entität eines eigens definierten Typs ("Ereignis") erstellen und dabei den Vorfall durch spezifische Merkmale klassifizieren.

Beim Erstellen der Ereignis-Entität soll das System prüfen, wann zuletzt ein Vorfall mit vergleichbarer Klassifikation gemeldet wurde. Liefert diese Recherche einen Treffer, soll eine Meldung angeben, wie viel Zeit (in Tagen mit einer Dezimale) seit diesem Vorfall vergangen ist.

Laufzeitbeispiel:

images/download/attachments/201666907/image-2025-3-5_15-48-3-version-1-modificationdate-1743580304069-api-v2.png

Konfiguration:

Die rechts abgebildete Ereignisbehandlung reagiert auf das Auslösende Ereignis (s. Allgemein (Ereignisse)) "Erstellen", das u. a. beim Speichern einer Entitäten durch den Benutzer in einer Erfassungsmaske ausgelöst wird .

In der Prüfenden Regel wird Typprüfung sichergestellt, dass eine Enität des Typs "Ereignis" erstellt werden soll.

Als Aktion bei bestandener Regel wird zunächst die Suche (Ereignisaktion) ausgeführt, die unter allen bisher erstellten Ereignissen nach "vergleichbaren" Vorfällen sucht. Details zu den Kriterien für die Suche sind für den weiteren Workflow unerheblich.

Die Suche übergibt das erste Ergebnis, also das zuletzt erstellte Ereignis, das alle Suchkriterien erfüllt, in die Variable latestIncident. Auf eine Prüfung, ob überhaupt ein Treffer vorliegt wurde hier zwecks Kürze verzichtet. Dieser Sonderfall kann bei Bedarf per Wenn Dann Sonst abgehandelt werden.
Die Ausführen mit-Ereignisaktion definiert das ggf. gefundene Ereignis in der Variable lastIncident als Bezugsobjekt für folgende Aktionen:
- Die Hinweis anzeigen (Popup)-Ereignisaktion, soll den Zeitraum seit dem gefundenen Ereignis angeben. Die erforderliche Berechnung kann direkt innerhalb der Meldung mit dem Berechne Wert-Wertauflöser dargestellt werden.
- Der wesentliche Rechenschritt ist die Differenz zwischen der aktuellen Systemzeit und dem Erstelldatum des gefundenen Ereignisses im Eingabewert zu ermitteln. Für beide Zeitangaben sollen dabei die UTC-Millisekunden-Werte (seit 01.01.1970) verwendet werden. Entsprechende Angaben sollen über die Variablen now und created durch Wertauflöser ermittelt werden, die weiter unten beschrieben werden.
- Innerhalb des Berechnungsausdruck wird die Long-Wert-Differenz now-created zunächst als Millisekunden (ms) deklariert, um diese dann über die convert()-Funktion in die Zeiteinheit "Tag" (D) umzurechnen. Die Zeitspanne in Tage wird mit 10 multipliziert, ganzzahlig abgerundet und danach wieder durch 10 geteilt, was als Rückgabewert einen Zahlenwert in Tagen mit einer Dezimale ergibt.
- Die nachfolgende Textverkettung betreibt noch ein bisschen Kosmetik, um das Erscheinungsbild der Ausgabe zu optimieren, so dass anstelle des internen Namens für die Einheit (day) deren Alias (D) in Kleinbuchstaben ausgegeben wird.

images/download/attachments/201666907/image-2025-3-5_15-9-38-version-1-modificationdate-1743580304074-api-v2.png

Rechts sind Details zur Konfiguration des Berechne Wert-Wertauflösers zu sehen:

Die erste Variable mit Variablenname now liest den Millisenkunden-Wert der aktuellen Systemzeit, die der Relatives Datum mit Zeit-Wertauflöser per Typ "Jetzt" liefert. Da wir nur die UTC-Millisekunden im Long-Feld "Datumswert" (dateValue) in die Berechnung einbeziehen ist die Zeitzone hier komplett irrelevant.
Die zweite Variable created wird aus dem Feld "Erstelldatum" (created) des Eingabewerts - also der Ereignis-Entität - gelesen. Hierbei handelt es sich um den Datumstyp "Timestamp", aus dem über den Eingabeobjekt (Typsicher)-Wertauflöser über eine Umwandlung in Long direkt die UTC-Millisekunden ermittelt werden können.

►HINWEIS◄ Der Datentyp Timestamp kann nicht direkt als numerischer Wert interpretiert werden. Sonst könnte man hier im Ausdruck ohne Umweg über eine Variable per input.created zugreifen.

►ANMERKUNG◄ Die Umrechnung der Millisekunden-Differenz in Tage stützt sich auf Umrechnungsregeln in der Dynamischen Aufzählung Zeiteinheit, die keine kalenderspezifischen Operationen sind, sondern nur zwischen den Zeiteinheiten Millisekunde (ms) und Tag (D)"vermittelt". Entsprechende Umrechnungen könnten hier auch direkt und ohne Konvertierung abgewickelt werden, indem die Millisekunden durch 86.400.000 geteilt werden. So viele Millisekunden hat ein Tag nämlich.

Allerdings fällt mit der convert()-Funktion vergleichsweise leicht, die Ausgabe bei Bedarf auf andere Ziel-Zeiteinheiten umzustellen, in dem deren Alias (etwa das H für Stunden) anstelle von D eingesetzt wird.

images/download/attachments/201666907/image-2025-3-5_15-10-42-version-1-modificationdate-1743580304071-api-v2.png

Berechnen des Packstückvolumens aus Länge x Breite x Höhe (mit variabler Längeneinheit)

Zu einem Packstück liegen für die Dimensionen als "Länge", "Breite" und "Höhe" Angaben in numerischen Feldern vor, deren Längeneinheit vom Benutzer - ggf. für jede Dimension anders - ausgewählt werden kann.

Aus diesen Angaben soll innerhalb einer Ereignisbehandlung das Volumen der quaderförmig idealisierten Packstücks in einer wählbaren Volumeneinheit berechnet und als Wert des Typs "Zahl mit Einheit" in die Variable Volume geschrieben werden.

Zur Vorgabe der gewünschten Volumeneinheit wird diese der Variable Volume vorab zugewiesen, sodass diese bereits vor der Berechnung einen Wert wie "0 Liter" oder "0 Gallonen" enthält.

Konfiguration:

Die geeignet initialisierte Ziel-Variable Volume (mit der Vorgabe für die Ziel-Volumeneinheit) steht wie rechts dargestellt am Anfang einer Verkettung von Wertauflösern. Für unser Beispiel sollen "0 Liter" vorbelegt sein.

Der Berechne Wert-Wertauflöser erhält den Wert der vorbelegten Variable Volume als Eingabewert, auf den der Berechnungsausdruck über den Namen input zugreifen kann. Die verschachtelte Berechnung wird nachfolgend "von innen nach außen" schrittweise beschrieben:
- Auf der "innersten" Ebene werden die Längenangaben in den Variablen length, width und height in eine willkürlich gewählte einheitliche Längeneinheit ("Meter" mit Alias m) umgerechnet. Dies leistet die convert()-Funktion mit der Zieleinheit m.
- Formal wird einem Produkt aus drei Größen mit derselben Einheit diese Einheit auch im Ergebnis zugewiesen. So ergibt sich hier aus den konvertierten Längen ein Zahlenwert, der zwar Kubikmeter "meint", aber technisch als "Meter" ausgewiesen wird. Das ist nicht besonders sinnvoll. Aber aufgrund der vorab ausgeführten Umrechnung der Eingangsdaten in die einheitliche Einheit (m) wissen wir zumindest, dass der Zahlenwert als "Kubikmeter" (m3) zu werten ist.
- In der im Screenshot selektierten Zeile 6 wird das Produkt aus den "Längen" noch mit der Alias m3 multipliziert. Innerhalb des viergliedrigen Produkts sollen - aus Sicht des Systems - damit Angaben in nicht-kompatiblen Einheiten (Längen in m vs. Volumen in m3) verrechnet werden. Da dafür keine Umrechnungsvorschrift greift, wird das Produkt als skalare Größe (ohne Einheit) ausgewiesen.
- Die skalare Größe, deren Zahlenwert (wie wir wissen) Kubikmeter angibt, wird durch die umgebende convert()-Funktion nun auch formal in die Einheit m3 umgewandelt. Diese Umwandlung würde für eine Angabe in m scheitern.
- In der äußersten Ebene kann nun endlich eine echte Umrechnung von den inzwischen formal deklarierten "Kubikmetern" (m3) in die gewünschte Ziel-Volumeneinheit erfolgen. Dafür reicht der Verweis auf den Eingabewert (input) aus, wobei nur dessen Einheit aber nicht dessen Wert berücksichtigt wird.
Der verkettete Wert als Variable speichern-Wertauflöser speichert das Ergebnis hier direkt in die Variable Volume, so dass die komplette Wertauflöserkette z. B. direkt in einer Hinweis anzeigen (Popup)-Ereignisaktion verwendet werden kann. Stattdessen könnte man auch eine Setze Wert-Ereignisaktion verwenden, um die berechnete "Zahl mit Einheit" in die Variablen zu schreiben.

images/download/attachments/201666907/image-2025-3-5_15-55-40-version-1-modificationdate-1743580304063-api-v2.png

Der Screenshot rechts zeigt wie in unserem Beispiel zu Testzwecken die Belegung der Variablen für die Eingangsdaten length, width und height gelöst wurde:

Für die Variable length wurde hier eine statische "Kommazahl" (mit dem Wert 1,2) zugewiesen. Durch die ausdrückliche Konvertierung im Berechnungsausdruck wird sichergestellt, dass diese eigentlich skalare Angaben als Meter (m) interpretiert wird.

►HINWEIS◄ Der Dezimaltrenner "Komma" betrifft hier nur die Darstellung im Eingabekontext. Direkt im Berechnungsausdruck müsste man 1.2 schreiben, um dasselbe Ergebnis zu erzielen.
Der Variable width wird eine statische Angabe in Zentimetern (cm) zugewiesen. Das funktioniert recht bequem, in dem man wiederum einen Berechne Wert-Wertauflöser mit einem statischen Ausdruck (80cm) einsetzt.
Der Variable height wird eine statische Angabe in Fuß (ft) zugewiesen. Wiederum kommt ein Berechne Wert-Wertauflöser mit einem statischen Ausdruck (3.33ft) zum Einsatz.

Für die operative Praxis macht die Zuweisung von statischen Werten für die drei Variablen natürlich keinen Sinn. Ausgehend von der Annahme, dass die Angaben für die drei Dimensionen des Packstücks z. B. als Felder (oder Attribute) eines gemeinsamen Datenobjekts vorliegen, könnte man dieses durch eine Ausführen mit-Ereignisaktion als Bezugsobjekt im Kontext des Wertauflösers definieren, um dann in den Zuweisungen für die Variablen length, width und height über die entity-Variable darauf zuzugreifen. Im Kontext einer nicht näher bezeichneten Entität würde der Zugriff auf ein Feld itemLength für die Zuweisung an die Variable length z. B. so aussehen:

images/download/attachments/201666907/image-2025-3-5_16-0-51-version-1-modificationdate-1743580304055-api-v2.png

images/download/attachments/201666907/image-2025-3-5_15-58-26-version-1-modificationdate-1743580304058-api-v2.png

►ANMERKUNG◄ Hier wird nicht beschrieben, wie die Variablen length, width und height - abgesehen vom Test mit statischen Werten - eigentlich mit Werten versorgt werden.

Typischerweise würden hier Objekt-Feld-Wertauflöser verwendeten werden, die den Variablen geeignete Werte aus dem äußeren Bezugsobjekt zuweisen.

Wenn aus demselben Bezugsobjekt mehrere Werte gelesen und direkt "verrechnet" werden sollen, läge es eigentlich nahe, das Bezugsobjekt als Eingabewert zu verwenden und die einzelnen Felder im Berechnungsausdruck über die input-Variable zu adressieren.

Konfigurationsvariante:

Der Screenshot rechts zeigt eine Wertauflöserkette, der als Eingabewert das Datenobjekt für das Packstück direkt (hier: als Bezugsobjekt) zugeführt wird. Die zu verrechnenden Abmessungen sollen in den Feldern "Länge" (length), "Breite" (width) und "Höhe" (height) jeweils als "Zahl mit Einheit" vorliegen.

Der Berechnungsausdruck ist grundsätzlich aufgebaut wie oben beschrieben, allerdings mit folgenden Anpassungen:

Der Zugriff auf die Abmessungen erfolgt nun über Datenfeldpfade für die Variable input (in Zeile 3-5).
Die Zieleinheit für die Umrechnung in den Zielwert (s. Zeile 8) wird nun nicht mehr aus dem input sondern aus der Variable Volume bezogen, die ursprünglich noch als input galt.

►HINWEIS◄ Die explizite "Zuordnung" der numerischen Eingangsgrößen in Variablen entfällt hier komplett. Allerdings funktioniert dieser Zugriff nur, solange die gelesenen Daten direkt als numerische Werte (hier: mit Einheit) im input vorliegen.

►ANMERKUNG◄ Für Tests kann z. B. ein Erzeuge Instanz mit Werten-Wertauflöser als Start für die Wertauflöserkette ergänzt werden, um ein "Packstück" als Client-Objekt bereitzustellen.

images/download/attachments/201666907/image-2025-4-2_13-29-25-version-1-modificationdate-1743593365603-api-v2.png

"Reichweite" des angemeldeten Benutzerkontos in einem Zuordnungskriterium bewerten

Benutzer sollen über eine Kennzahl "Reichweite" klassifiziert werden, die als Produkt aus den Anzahlen für die beim Login auswählbaren Rollen und Firmen/Mandanten definiert ist.

Ein Zuordnungskriterium soll genau dann zutreffen, wenn die "Reichweite" eines Benutzers mindestens 3 beträgt.

Konfiguration:

Im Kontext einer Mit-Regel, die den zu bewertenden Benutzer als Bezugsobjekt definiert (z. B. den Benutzer der Session), wird das im Screenshot rechts abgebildete Kriterium geprüft:

Eine Typprüfung stellt zunächst sicher, dass ein "Benutzer" als Bezugsobjekt vorliegt und (mit Blick auf den Benutzer der Session ggf. entscheidend) kein Gastbenutzer.
Innerhalb einer UND-Verknüpfung folgt eine Objekt-Feld-Regel nach, über den Vergleiche mit (Vergleichstyp)-Vergleichstyp feststellen soll, ob die als Prüfwert (links) berechnete "Reichweite" in der gewünschten Relation (≥) zum Vergleichswert (rechts) steht.
- Der Prüfwert kann mit dem Berechne Wert-Wertauflöser sehr elegant ermittelt werden, da die benötigen Eingangsdaten direkt im Eingabewert (input) adressiert werden können. Das length-Feld gibt jeweils die Anzahl der Einträge im übergeordneten Listenfeld des Benutzerkontos wieder. Der Berechnungsausdruck nutzt diese Information für die Listenfelder "Firmen" (companies) und "Rollen" (roles) des Benutzerkontos.
- Der Vergleichswert wird hier als statischer Long-Wert 3 festgelegt.

►ANMERKUNG◄ Dass der Wert im Objekt-Feld length hier nur auf eine interne Berechnung (für "Listen") zurückgeht und nicht etwa auf ein persistiertes Datenbankfeld des Benutzers, spielt für den Zugriff per Datenfeldpfad keine Rolle.

images/download/attachments/201666907/image-2025-4-2_14-10-5-version-1-modificationdate-1743595805683-api-v2.png

Berechnungen mit Daten aus einer Map

Der Zugriff über Datenfeldpfade für Details aus einem komplexen Eingabewert gelingt auch, wenn es sich dabei um eine Map geht.

Für das folgende Beispiel soll eine Map in einer Variablen sales vorliegen, in die unter Verwendung systematisch benannter Schlüsselwerte ("Q1", "Q2", "Q3", "Q4") Absatzzahlen (Stückzahlen) für die bereits abgeschlossenen Quartale des laufenden Jahres geschrieben wurden.

Die Summe aller Quartale zum aktuellen Stand soll berechnet und unter dem Schlüssel "TOTAL" als weiterer Wert in die Map geschrieben werden.

Konfiguration:

Der Screenshot rechts zeigt eine Ausführen mit-Ereignisaktion, für deren Aktionsblock die Map in der sales-Variable als temporäres Bezugsobjekt gilt.

Berechnung und Wertzuweisung können innerhalb derselben Setze Wert-Ereignisaktion abgewickelt werden:

Als Ziel für die Wertzuweisung (links) wird ein Map-Wert über den durch statischen Text bestimmten Schlüssel TOTAL identifiziert. Ob dieser bereits einen Wert enthält bzw. überhaupt existiert ist nicht von Belang.
Der zuzuweisende Wert (rechts) wird über den Berechne Wert-Wertauflöser ermittelt, für den die Map (sales) im Bezugsobjekt als Eingabewert (input) gilt. Der Berechnungsausdruck kann ganz einfach alle möglicherweise relevanten "Schlüssel" in der Map im Eingabewert (input) abrufen und aufaddieren. Für nicht gefundene Schlüssel wird der Wert 0 verwendet.

images/download/attachments/201666907/image-2025-4-2_14-55-51-version-1-modificationdate-1743598551158-api-v2.png

Berechnungen mit Daten aus Listen

Zugriff auf Listenwerte per Index
Sofern der Eingabewert eine Liste ist oder Listenwerte enthält, kann der Berechnungsausdruck auf individuelle Listenwerte über deren absolute Indexposition zugreifen.
Der Index startet jeweils bei 0.
Der erste Listenwert einer als Eingabewert vorliegenden Liste von numerischen Werten kann damit als input.0 im Berechnungsausdruck adressiert werden.
Handelt es sich bei einem Listenwert um ein komplexes Objekt, kann der Datenfeldpfad nach dem Indexwert fortgesetzt werden, um dessen Struktur weiter aufzulösen.
Der Ausdruck input.2.maxCapacity liest den Wert des Felds maxCapacity eines Objekts, das der dritte Eintrag in der als Eingabewert bereitgestellten Liste ist (sofern vorhanden).
►WICHTIG◄ Anders als im Kontext eines Formulars, wo die get (Wert aus Datenfeld lesen)-Funktion den Zugriff auf Listenwerte über einen variablen Indexwert ermöglicht, ist dies hier nicht möglich. Indexwerte können im Berechnungsausdruck ausschließlich statisch und absolut definiert werden.

Ein Eigener Entitätstyp "Aircraft" (Aircraft) listet im Listenfeld areas Ladebereiche eines Luftfahrzeugs auf, die über ein weiteres Listenfeld zones weiter untergliedert sein können.

Per Konvention is festgelegt, dass jedes relevante Luftfahrzeug durch maximal vier Ladebereiche (areas) beschrieben werden kann, denen je 1-2 Zonen (zones) zugeordnet sind.

Jeder Zone kann über das Feld weight ein "Ladungsgewicht" (weight) zugeordnet werden. Gleichzeitig ist je Zone ein fiktiver "Hebelarm" (arm) angegeben, über den das Moment abhängig von der Zuladung berechnet werden soll.

Vor dem Start des Luftfahrzeugs ist zu prüfen, ob die Gesamtmasse und das Gesamtmoment unter Berücksichtigung der konkreten Beladung und Betankung (hier: modelliert über die Zonen) im zulässigen Betriebsbereich liegen.

Die folgende Konfiguration zeigt wie das Gesamtmoment für ein in einer Variablen acft definiertes Aircraft-Objekt berechnet werden kann.

Konfiguration:

Der Screenshot rechts zeigt eine Wertauflöserkette (s. Verketteter Wertauflöser), über die das "Gesamtmoment" z. B. als Meldung in einer Hinweis anzeigen-Ereignisaktion ermittelt werden kann:

Der Variable-Wertauflöser stellt eine konkrete Aircraft-Entität bereit, die alle Rohdaten für eine Weight & Balance-Ermittlung enthält.
Der verkettete Berechne Wert-Wertauflöser erhält das komplette Aircraft-Objekt als Eingabewert (input) und kann im Berechnungsausdruck die maximal definierbaren 4 Bereiche (areas) mit je 2 Zonen (zones) in einem Gesamtansatz für das "Gesamtmoment" verarbeiten.

►WICHTIG◄ Für nicht parametrierte Bereiche und Zonen wird jeweils der Wert 0 berücksichtigt, was diesen konkreten Rechengang nicht beeinträchtigt.
Das Gesamtergebnis der berechneten "Produktsumme" (Gewicht x Hebelarm) wird als "Gesamtmoment" über einen Wert als Variable speichern-Wertauflöser in die Variable totalMoment geschrieben.

images/download/attachments/201666907/image-2025-4-3_12-40-47-version-1-modificationdate-1743676847041-api-v2.png

►ANMERKUNG◄ Dieses Beispiel soll aufzeigen, wie der Indexzugriff für Listenwerte für Berechnungen mit einer definierten (oder zumindest endlichen) Anzahl von Listenwerten ausgeführt werden kann. Berechnungen für Listen mit variabler Länge ermöglicht immer eine Für jeden Eintrag wiederholen (Schleife)-Ereignisaktion und - in besonderen Fällen - das Ausführen einer Berechnung (per Wertauflöser, z. B. Berechne Wert oder Einfache Berechnung (+,-,*,/,%)) in einem Sammle Werte-Wertauflöser.