Relatives Datum mit Zeit
Wertauflöser - Kurzfassung
Zweck: Liefert ein "Datum mit Zeit", das durch einen vordefinierten oder benutzerdefinierten Zeitberechnungsausdruck relativ zur Systemzeit oder dem Eingabewert (nur für "Benutzerdefiniert") berechnet wird.
Siehe auch: Typ Zeit (Dynamische Aufzählung), Relativer Datumsbereich mit Zeit (Wertauflöser)
Der Relatives Datum mit Zeit-Wertauflöser liefert ein "Datum mit Zeit", das abhängig vom ausgewählten Typ relativ zu einem der folgenden Bezugszeitpunkte ermittelt wird:
Per Standard gilt die aktuelle Systemzeit als Bezugszeitpunkt für die durch den Typ bestimmte "relative" Berechnung des Rückgabewerts.
►HINWEIS◄ Abhängig vom Ausführungskontext kann entweder die Systemzeit des Servers (s. in Ereignisbehandlungen) oder des Clients (z. B. in einem Client Workflow) ausschlaggebend sein.Der Eingabewert wird ausschließlich in Verbindung mit dem Typ "Benutzerdefiniert" (CUSTOM) als Bezugszeitpunkt berücksichtigt, sofern dieser einem der folgenden Datentypen entspricht:
Eingabewert-Typ |
Klasse |
Bezugszeitpunkt |
Zeitzone (aus Eingabewert) |
"Datum mit Zeit" |
core:DateTime |
Feld "Datumswert" (dateValue) |
Feld "Zeitzone" (timeZone) wird für Rückgabewert nur dann berücksichtigt, falls keine Auswahl für den Parameter Zeitzone besteht |
"Datumsbereich mit Zeit" |
core:DateRange |
Feld "Start" (start) oder |
|
"Long" |
java.lang.Long |
Eingabewert |
n/a |
"Timestamp" |
java.sql.Timestamp |
||
"Date" |
java.util.Date |
Der Rückgabewert wird abhängig vom gewählten Typ (s. Typ Zeit) ausgehend vom Bezugszeitpunkt durch einen Zeitberechnungsausdruck ermittelt:
Typ |
Konfigurationsbeispiel |
Berechnung des Rückgabewerts |
"Benutzerdefiniert" |
|
Auf den Bezugszeitpunkt (entweder geeigneter Eingabewert oder die Systemzeit) wird der im Parameter Zeitwert definierte Zeitberechnungsausdruck angewendet. Im Beispiel wird ausgehend von einem durch den Eingabewert gegebenen Datum z. B. der Zeitpunkt berechnet, der zwei Kalendertage später (+2d) genau um 6:30 Uhr (6H 30m 0s 0S) liegt. ►WICHTIG◄ Die für den Rückgabewert anwendbaren Zeitzone ist auch ausschlaggebend für die Interpretation des Zeitberechnungsausdrucks. Da im Beispiel (links) der Parameter Zeitzone keine Auswahl vorgibt, wird die Zeitzone aus dem Eingabewert übernommen, sofern dieser eine spezifiziert (s. Tabelle oben). Liegt für den Parameter Zeitzone eine Auswahl vor, dann wird stattdessen die betreffende Zeitzone für die Umrechnung verwendet und dem Rückgabewert zugewiesen. Wirkung von Zeitzonen auf die Interpretation im Zeitwert des Zeitberechnungsausdrucks
|
alle anderen Typen |
|
Der für den ausgewählten Typ in der Dynamischen Aufzählung Typ Zeit hinterlegte Zeitberechnungsausdruck wird auf die aktuelle Systemzeit des Servers oder Clients angewendet. Im Beispiel wird das Ende des aktuellen Kalendertags (s. Typ Zeit, "Ende heute") in der Zeitzone "Europe/Lisbon" zurückgegeben.
|
Konfiguration
►HINWEIS◄ Der Eingabewert wird ausschließlich in Verbindung mit dem Typ "Benutzerdefiniert" (CUSTOM) berücksichtigt. Dann muss ein als Datum interpretierbarer Wert vorliegen.
Parameter |
Konfiguration |
Beschreibung |
Typ |
|
Der Parameter Typ ermöglicht die statische Einfachauswahl eines Werts aus der Dynamischen Aufzählung Typ Zeit. Wie im Bild (links) gezeigt wird die Auswahl durch eine Suchfunktion unterstützt. Dynamische Aufzählungsfilter können die Verfügbarkeit von Optionen im Dropdown für den Kontext der Konfiguration einschränken. Sie haben keine Einfluss auf das Laufzeitverhalten des Wertauflösers. ►HINWEIS◄ Wird kein Typ ausgewählt, dann lautet der Rückgabewert immer $null. |
Zeitzone |
|
Der Parameter Zeitzone ermöglicht optional die statische Einfachauswahl einer von Java unterstützten Zeitzone. Wie im Bild (links) gezeigt wird die Auswahl durch eine Suchfunktion unterstützt. Die Auswahl einer Zeitzone beeinflusst die Interpretation des zur Laufzeit angewendeten Zeitberechnungsausdrucks. Außerdem wird die ausgewählte Zeitzone für den Rückgabewert verwendet. Wird keine Zeitzone ausgewählt, dann wird im Allgemeinen die im Kontext anwendbare Standardzeitzone verwendet, die (mit absteigender Priorität) durch ein der folgenden Einstellungen definiert wird:
Falls in Verbindung mit dem Typ "Benutzerdefiniert" (CUSTOM) ein Eingabewert vorliegt, der explizit eine Zeitzone beinhaltet, wird diese berücksichtigt, wenn keine Auswahl für den Parameter Zeitzone getroffen wurde. ►HINWEIS◄ Die Auswahloptionen für die Zeitzonen sind nicht lokalisierbar und sie können auch nicht durch Dynamische Aufzählungsfilter eingeschränkt werden. Die angezeigten Texte entspringen direkt der Java-Umgebung. |
Zeitwert |
|
Der Parameter Zeitwert unterstützt die Eingabe eines statischen Texts, der zur Laufzeit als Zeitberechnungsausdruck (Details s. folgender Abschnitt) interpretiert wird. ►HINWEIS◄ Der Parameter erscheint nur, wenn der Typ "Benutzerdefiniert" (CUSTOM) ausgewählt ist. Für alle anderen Typen sollte in der Dynamischen Aufzählung Typ Zeit ein geeigneter Zeitberechnungsausdruck hinterlegt vorliegen. Dort können auch eigene Typen mit spezifischen Zeitberechnungsausdrücken ergänzt werden. Im Beispiel wird der Zeitpunkt 9:30 Uhr (UTC) am dritten Kalendertag nach dem Bezugszeitpunkt zurückgegeben. ►ANMERKUNG◄ Ein in der Konfiguration einmal eingegebener Text für den Zeitwert bleibt (unwirksam) erhalten, falls ein anderer Typ als "Benutzerdefiniert" ausgewählt wird. Er erscheint daher wieder, sofern der Typ "Benutzerdefiniert" später erneut ausgewählt wird. Wird kein Zeitberechnungsausdruck als Zeitwert angegeben, dann wird der Bezugszeitpunkt also entweder der Eingabewert oder die Systemzeit ggf. unter Berücksichtigung der ausgewählten Zeitzone ausgegeben. |
Zeitberechnungsausdrücke
Ein Zeitberechnungsausdruck definiert eine Kette von durch Leerzeichen getrennte Sequenz von Tokens für Manipulationen, die einen ursprünglichen Datumswert schrittweise verändern sollen.
Sofern ein Zeitberechnungsausdruck überhaupt mehr als eine Manipulation vorsieht, erhält jeder Folgeschritt das Ergebnis der bisherigen Manipulationen als "Input".
Eine Liste der je Typ vordefinierten Ausdrücke zeigt die Seite Typ Zeit.
Typen von Manipulationen
Absolute Manipulation
Die Kombination einer Ganzzahl ohne Vorzeichen mit einem Kennbuchstaben definiert einen absolut bestimmten Zielwert für die durch den Kennbuchstaben identifizierte Komponente.
Beispiel: Der Token 10M definiert, dass für die Komponente "Monat im Jahr" (M) der zehnte Monat, also "Oktober", zugeordnet werden soll, während andere Komponenten unverändert gelten.
Falls Ganzzahlen außerhalb des nominellen Wertebereichs einer Komponente zugewiesen werden, verursacht die Zuordnung in der Regel indirekt Änderungen in einer oder mehreren übergeordneten Komponenten.
Beispiel: Der Token 13M definiert, dass der dreizehnte "Monat im Jahr" (M) zugewiesen werden soll. Effektiv verweist das auf den Januar des nächsten Jahres.
Relative Manipulation
Die Kombination einer Ganzzahl mit Vorzeichen mit einem Kennbuchstaben definiert einen relativ bestimmten Zielwert (Offset) für die durch den Kennbuchstaben identifizierte Komponente.
Beispiel: Der Token +2M bewirkt einen Versatz der Monatskomponente um zwei Kalendermonate, was abhängig vom aktuellen Monat einen Wechsel in das nachfolgende Kalenderjahr bewirken kann oder auch nicht.
Sonderfall: Da Kalendermonate unterschiedlich viele Tage haben, kann es vorkommen, dass ein Monatsversatz für unterschiedliche "Tage des Monats" denselben Zielwert ergibt.
Beispiel: Der Token +2M wird auf das Datum 31.12.2020 angewendet. Da der 31.02.2020 nicht definiert ist, wird der letzte definierte Tag des Zielmonats (hier: 28.02.2021) zurückgegeben. Ausgangswerte zwischen dem 28. und 31. Dezember liefern denselben Rückgabewert.
Kennbuchstaben
Die folgende Tabelle gibt eine Übersicht über die Bedeutung der unterstützten Kennbuchstaben:
Kennbuchstabe |
Ziel-Komponente |
Bedeutung |
Nomineller Wertebereich (für absolute Zuweisungen) |
Hierarchische Datumskomponenten (Jahr > Monat > Tag > Stunden > Minute > Sekunde > Millisekunde) |
|||
y |
Jahr |
Jahr |
1 bis 9999 |
M |
Monat |
Monat im Jahr |
1 (Januar) bis 12 (Dezember) |
d |
Tag |
Tag im Monat |
1 bis Anzahl Tage im betreffenden Monat |
H/h |
Stunde |
Stunde des Tages |
0 bis 23 |
m |
Minute |
Minute der Stunde |
0 bis 59 |
s |
Sekunde |
Sekunde der Minute |
0 bis 59 |
S |
Millisekunde |
Millisekunden in der Sekunde |
0 bis 999 |
Spezielle Datumskomponenten |
|||
D |
Tag |
Tag im Jahr |
1 bis Anzahl Tage im betreffenden Jahr |
E/F |
Tag der Woche |
1 (Montag) bis 7 (Sonntag) |
|
q |
Quartal/Tag |
erster Tag des Quartals |
1 bis 4 |
Q |
letzter Tag des Quartals |
1 bis 4 |
Beispiele
Einfacher Anwendungsfall: Vergleichswert für eine Feldeinschränkung
Eine Übersicht (s. Eigene Übersichten) soll alle Benutzer auflisten, deren "Passwort Ablaufdatum" (passwordExpiryDate) überschritten ist oder bis zum Ende des aktuellen Monats überschritten wird.
Der Screenshot rechts zeigt die Konfiguration für eine Einschränkung, die dieses Kriterium berücksichtigt:
|
|
►HINWEIS◄ Entsprechende Einschränkungen können auch zur Definition einer Suche für ein Import -Profil im Lobster_data verwendet werden. Die XML-Struktur rechts zeigt wie einfach der Zugriff auf ein vordefiniertes "Relatives Datum" (im vorliegenden Beispiel: END_THIS_MONTH ) über das DateTimeValue -Objekt (hier als value -Element einer Feld Einschränkung ) innerhalb einer Suche ist. |
<?xml version="1.0" encoding="UTF-8"?> |
Die folgende Variante deckt den Fall ab, dass alle Benutzer aufgelistet werden sollen deren "Passwort Ablaufdatum" (passwordExpiryDate) überschritten ist oder in den nächsten 14 Tagen überschritten wird.
Der Screenshot rechts zeigt die Konfiguration für eine Einschränkung, die dieses Kriterium berücksichtigt:
►ANMERKUNG◄ Hier wird eine Zeitzone für die Berechnung explizit vorgegeben. Sofern das "Passwort Ablaufdatum" in einer abweichenden Zeitzone eingegeben wurde, liefert die Feldprojektion trotzdem die Ausschlaggebenden "UTC-Millisekunden". |
|
Einfacher Anwendungsfall: Einen berechneten Termin zuweisen
Beim Kopieren von Konten für Gastbenutzer soll eine Ereignisbehandlung deren Gültigkeit automatisch auf 36 Stunden ab dem Beginn des nächsten Kalendertags begrenzen.
Die Ereignisbehandlung reagiert auf das Ereignis "Kopieren" (s. Allgemein (Ereignisse)) als Auslösendes Ereignis. Mit diesem Auslöser wird die Ereignisbehandlung sofort aktiv, wenn ein Benutzer den Ribbon-Befehl "Kopieren" ausführt. Sie kann das als Kopie neu angelegte Datenobjekt damit initialisieren bevor der Benutzer über die bereits geöffnete Erfassungsmaske Zugriff erhält. Die Prüfende Regel stellt per Typprüfung sicher, dass Aktionen nur ausgeführt werden, sofern es sich bei der kopierten Entität um ein Gastbenutzerkonto handelt. Als Aktion bei bestandener Regel wird hier eine Setze Wert-Ereignisaktion ausgeführt:
►HINWEIS◄ Anstelle der Verkettung könnte man auch nur einen Relatives Datum mit Zeit-Wertauflöser verwenden, der im Parameter Zeitwert den Ausdruck für "Anfang des nächsten Tages" (s. Typ Zeit) mit dem Ausdruck für den Versatz verkettet: 0h 0m 0s 0S +1d +36H ... bzw. im Ergebnis gleichwertig ... |
|
►ANMERKUNG◄ Die rechts oben explizit zugewiesene Zeitzone "Europe/Kiev" wird für die Berechnung und den letztendlich zugewiesenen Wert übernommen, weil der verkettete Relatives Datum mit Zeit-Wertauflöser keine explizite Auswahl für den Parameter Zeitzone verwendet. |
|
Mit der rechts abgebildeten Anpassung der bestehenden Konfiguration wird erreicht, dass die Zeitzone "Europe/Kiev" zwar für die Berechnung verwendet wird, aber im Feld "Gültig bis" (validTo) die Zeitzone erhalten bleibt, die im kopierten Gastbenutzerkonto bereits eingetragen war:
|
|