Expression
Funktionsbeschreibung und Anwendung
Der Expression Evaluator-Block (ExpEval) kann Berechnungen und sonstige mathematische oder logische Verknüpfungen auf Grundlage einlaufender Nachrichten durchführen. Der Processing-Block hat Zugriff auf einlaufende Nachrichten-Payloads.
Die folgenden Skizze veranschaulicht die Funktionsweise.
Im Beispiel der Skizze wird laut Konfiguration die Berechnung eines Wertes result durchgeführt.
Dafür wird auf die einlaufenden Datenfelder a und b zugegriffen. Nach Verarbeitung wird die einlaufende Nachricht mit dem Wert result erweitert und ausgegeben.
In der folgenden Tabelle werden die Konfigurationsparameter erläutert.
| Parameter | Beschreibung |
|---|---|
Name |
Name der Blockinstanz. |
Into |
Name der Blockinstanz des Folgeblocks an welchen Ausgabenachrichten weitergeleitet werden sollen. |
Expressions - Name |
Name des Ergebnis (Key) für einen angegebenen Ausdruck. |
Value |
string, Auszuwertender Ausdruck. Die Syntax ist unter Ausdrücke beschrieben. |
Preserve input properties |
optional, boolean, default=false, |
Results in object |
optional, string, Wenn an dieser Stelle etwas angegeben wird, werden Ergebnisse in einem Unterobjekt der Ausgangsnachricht eingefügt. |
Ausdrücke
Folgende Operatoren und Ausdrücke stehen zur Verfügung und können ausgewertet werden:
-
mathematische Verknüpfungen mit den Operatoren
+, -, *, / -
Modulo mit Operator
% -
mathematische Funktionen aus .NET Math. Bspw.
Round(..), Abs(..), Pow(..), Sqrt(..), .. -
binäre Verknüpfungen mit den Operatoren
| , &, ^, ~ -
logische Verknüpfungen mit den Operatoren
||, &&, or, and, !, not -
mathematische Vergleiche mit den Operatoren
<, >, <=, >=, ==, !=
Neben numerischen Konstanten (wie 12 oder 7.91) oder booleschen true/false kann auf die Properties der einlaufenden Nachricht per JSON Key zugegriffen werden.
Die folgende Tabelle zeigt einige Beispiele.
| Expression (JSON Value) | Variables (aus einlaufender Nachricht) | Ergebnis (JSON Value) |
|---|---|---|
"1.1*6" |
6.6 |
|
"20 % 10" |
0 |
|
"not true" |
false |
|
"true && true" |
true |
|
"true || false" |
true |
|
"not(2>8)" |
true |
|
"foo*bar" |
foo:20; bar:4 |
80 |
"foo-bar" |
foo:20; bar:4 |
16 |
"foo/bar" |
foo:20; bar:4 |
5 |
"foo+bar" |
foo:20; bar:4 |
24 |
"foo%bar" |
foo:20; bar:4 |
0 |
"foo-(bar * 100)" |
foo:20; bar:4 |
-380 |
Zu beachten ist, dass dieser Processing-Block über keinen Zustand verfügt. Jede Berechnung erfolgt anhand der Konfiguration und der einlaufenden Nachrichten!
.Net Math Operations Syntax: Auf die Funktionen aus dotnet math kann folgendermaßen zugegriffen werden:
-
Potenzieren:
y = x^a⇒ "y": "Pow(x,a)" -
Runden:
y = x (auf zwei Nachkommastellen)⇒ "y": "Round(x,2)" -
Quadratwurzel:
y = sqrt(x)⇒ "y": "Sqrt(x)" -
Abrunden auf Ganzzahl: x ⇒ "y": "Floor(x)"
-
Aufrunden auf Ganzzahl: x ⇒ "y": "Ceiling(x)"
-
Betrag einer Zahl: x ⇒ "y": "Abs(x)"
Weitere Details sind in der Dokumentation der Math Klasse .Net Core zu finden: https://docs.microsoft.com/de-de/dotnet/api/system.math.sqrt?view=netcore-3.1
Benutzung von regulären Ausdrücken (Regex)
Mit Hilfe regulärer Ausdrücke können komplexere Suchmuster erstellt werden. Beispielsweise nicht nur eine Zahl (z.B. 42), sondern auf ein ganzes Intervall (z.B. 00-99).
Die Syntax für Regular Expression ist: RegEx(<value>,'<pattern>'). Dabei gelten folgende Sonderregelen:
-
Mit Hochkomma ('') um den Value kann ein statischer Wert eingetragen werden
-
Ohne Hochkomma ('') wird der Wert aus den Parametern (Header & Body & Kontext) geholt
Für eine Expression die einen leeren String enthält, lautet die Ausgabe immer False.
Beispiel:
"HeaderScopeContainsSample" : "RegEx(header_scope, '.Sample.')"
Konstanten
Der Zugriff auf folgende Konstanten ist möglich:
-
PI⇒ Kreiszahl π -
EULER⇒ Eulerscher Zahl e, Basis des natürlichen Logarithmus -
ONE⇒ ganze Zahl 1
Umrechnung von Zeiten
Für die Konvertierung von Zeiten stehen mehrere Funktionen zur Verfügung:
| Funktion | Beschreibung |
|---|---|
DateTimeNowUtc() |
Gibt die aktuelle Zeit des Robogates im ISO Format aus. |
ToDateTime(value,format) |
Berechne aus Unixepochtime, einem String oder OLE-Zeitstempel ein Objekt im Datumsformat, Datetime genannt. |
DateTimeToString(value:datetime,format:optional string) |
Umkehrfunktion zu ToDateTime wo ein Objekt im Datumsformat zu einem String berechnet wird. |
DateTimeToUnixEpoch(value:datetime) |
Berechne aus der Datetime die Anzahl der Sekunden seit dem 1.1.1970 0:00 UTC. |
DateTimeToNumber(value:datetime) |
Berechnet die Anzahl der Tage vor oder nach Mitternacht, dem 30. Dezember 1899. Die Bruchkomponente enstpricht der Zeit an diesem Tag dividiert durch 24. |
Das Format ist hier die übliche Schreibweise mit den Identifikatoren. Beispiel: yyyy-MM-ddTHH:mm:ss.FFFFFFFK bzw. hier ein konkretes Datum wäre 2023-02-08T17:05:54.355023Z. Für genauere Details siehe https://learn.microsoft.com/de-de/dotnet/standard/base-types/custom-date-and-time-format-strings.
Beispiel für Zeitenumrechnung
Im folgendem Beispiel wird die Differenz zwischen einem Zeitstring und der aktuellen Zeit berechnet:
"Restzeit": "DateTimeToNumber(ToDateTime('2023-02-08T17:05:54.355023Z')) - DateTimeToNumber(DateTimeNowUtc())"
Aus dem String 2023-02-08T17:05:54.355023Z wird zunächst die Datetime berechnet. Anschließend wird die Datetime in eine Zahl formatiert und von der aktuellen Zeit im Zahlenformat (DateTimeNowUtc) abgezogen. Dies kann zum Beispiel benutzt werden, um zu prüfen ob der angegebene Zeitpunkt in der Zukunft (Restzeit>0) oder in der Vergangenheit liegt (Restzeit<0).
Beispielkonfiguration
Die Berechnung im Beispiel in Abbildung 2, ergibt sich aus dem Feld „a“ einer einlaufenden Nachricht und Addition mit einem konstanten Wert 1. Das Ergebnis wird in dem Feld „aPlus1“ abgelegt. Im Weiteren sollen alle vorhandenen Felder auf der Eingangsseite erhalten bleiben (→ Preserve input properties: true). Das Ergebnis soll direkt in das Top Level JSON-Objekt eingefügt werden (→ Results in object: null).
