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)

images/download/attachments/78256099/image2022-9-2_15-55-47-version-1-modificationdate-1662126947321-api-v2.png

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
(Millisekunden seit 01.01.1970 UTC)

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
falls dieses keinen Wert liefert
Feld "Bis" (end)

"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"

images/download/attachments/78256099/image2022-9-14_12-33-13-version-1-modificationdate-1663151593467-api-v2.png

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

  • Als Eingabewert liegt ein "Datum mit Zeit" vor, das sich auf den 20.12.2020 um 00:00 Uhr in der Zeitzone "Asia/Manila" bezieht.

  • Die Beispielkonfiguration (ohne Auswahl für die Zeitzone) liefert als Rückgabewert den 22.12.2020 um 06:30 Uhr (in Manila).

  • Mit "Europe/Berlin" im Parameter Zeitzone, würde stattdessen der 21.12.2020 um 06:30 Uhr (in Berlin) zurückgegeben, Das entspricht 13:30 Uhr (am 21.12.2020) in Manila. Der Rückgabewert liegt also 10,5 Stunden vor dem Original-Ergebnis (s. o.).

    • Der Eingabewert wird zuerst in die Zeitzone Berlin umgerechnet (19.12.2020 17:00).

    • Der Offset (+2) für den Kalendertag wird "in Berliner Zeit" angewendet. Danach wird die lokale Uhrzeit gesetzt.

alle anderen Typen

images/download/attachments/78256099/image2022-9-14_14-13-7-version-1-modificationdate-1663157587808-api-v2.png

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.

  • Der Zeitberechnungsausdruck für "Ende heute" lautet: 23h 59m 59s 999S.

  • Da als Zeitzone "Europe/Lisbon" ausgewählt ist, wird das Ende des in dieser Zeitzone aktuellen Kalendertages ausgegeben. Dieser kann von dem Kalendertag abweichen, der in der ohne Auswahl für den Parameter Zeitzone anwendbaren Zeitzone als "Heute" gelten würde. Etwa wenn sich das System in der Zeitzone "Europe/Berlin" befindet und die Uhrzeit 00:30 anzeigt. Dann ist aus Berliner Sicht in Lissabon noch "Gestern".

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

images/download/attachments/78256099/image2022-9-14_15-5-57-version-1-modificationdate-1663160758046-api-v2.png

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

images/download/attachments/78256099/image2022-9-14_15-10-27-version-1-modificationdate-1663161027889-api-v2.png

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:

  • Feld "Default Zeitzone" im Benutzerkonto der tatsächlich angemeldeten Sitzung

  • Feld "Default Zeitzone" im Firmenkonto der tatsächlich angemeldeten Sitzung

  • Einstellungen im für den Ausführungskontext (Client/Server) relevanten Betriebssystem

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

images/download/attachments/78256099/image2022-9-14_15-42-8-version-1-modificationdate-1663162928131-api-v2.png

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)
HINWEIS0M verweist auf den letzten Monat im Vorjahr

d

Tag

Tag im Monat

1 bis Anzahl Tage im betreffenden Monat
HINWEIS◄ 0d verweist auf den letzten Tag des Vormonats

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
HINWEIS0D verweist auf den letzten Tag des Vorjahres

E/F

Tag der Woche

1 (Montag) bis 7 (Sonntag)
WICHTIG◄ Die Kalenderwoche beginnt per Definition immer Montags!
HINWEIS0E/0F verweisen auf den Sonntag der Vorwoche

q

Quartal/Tag

erster Tag des Quartals

1 bis 4
HINWEIS0q verweist auf den ersten Tag im letzten Quartal des Vorjahrs

Q

letzter Tag des Quartals

1 bis 4
HINWEIS0Q verweist auf den letzten Tag im letzten Quartal des Vorjahrs

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:

  • Innerhalb einer Feld Einschränkung verweist die linke Seite per Feldprojektion auf das Feld "Passwort Ablaufdatum". Dieses Feld ist vom Typ "Datum mit Zeit".

  • Auf der rechten Seite der Feld Einschränkung kommt der Relatives Datum mit Zeit-Wertauflöser zum Einsatz, um den Grenztermin für den Vergleich per Typ "Ende des Monats" zu definieren.

  • Als Vergleichstypen (Matcher) kommt hier ein Vergleiche mit (Vergleichstyp) zum Einsatz für den eine "<"-Bedingung ausgewählt wurde.

    ANMERKUNG◄ Auf die Vorgabe einer Zeitzone wurde hier verzichtet. Daher wird die im Kontext der Sitzung anwendbare Standard-Zeitzone für die Abgrenzung des Monat berücksichtigt. Der Vergleich erfolgt effektiv anhand der "UTC-Millisekunden", so dass auch die Zeitzone des Ablaufdatums einen Einfluss auch die Anzeige von Benutzern haben kann.

images/download/attachments/78256099/image2022-9-15_9-22-36-version-1-modificationdate-1663226556397-api-v2.png

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"?>
<core:PropertySearch xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:core="CORESYSTEM">
<core:PropertyProjection property="passwordExpiryDate"/>
<compareType>&lt;</compareType>
<value type="END_THIS_MONTH" xsi:type="core:DateTimeValue"/>
</core:PropertySearch>

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:

  • Innerhalb einer Feld Einschränkung verweist die linke Seite per Feldprojektion auf das Feld "Passwort Ablaufdatum". Dieses Feld ist vom Typ "Datum mit Zeit".

  • Auf der rechten Seite der Feld Einschränkung kommt der Relatives Datum mit Zeit-Wertauflöser mit dem Typ "Benutzerdefiniert" zum Einsatz, da es keinen vordefinierten Zeitpunkt "in 14 Tagen" gibt. Als Zeitwert wird dabei ausgehend von der aktuellen Systemzeit der Beginn des 15. Tages nach Heute (in der Zeitzone "Europe/Berlin") berechnet. Dieser Wert wird in Verbindung mit dem "<"-Vergleich genau nicht mehr vom Kriterium akzeptiert.

  • Als Vergleichstypen (Matcher) kommt hier ein Vergleiche mit (Vergleichstyp) zum Einsatz für den eine "<"-Bedingung ausgewählt wurde.

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".

images/download/attachments/78256099/image2022-9-15_18-57-51-version-1-modificationdate-1663261071064-api-v2.png

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:

  • Auf der linken Seite definiert ein Objekt-Feld-Wertauflöser das Feld "Gültig bis" (validTo) als Ziel der Wertzuweisung.

  • Auf der rechten Seite werden zwei Instanzen des Relatives Datum mit Zeit-Wertauflösers verkettet, um den Ablauf der Gültigkeit des kopierten Kontos zu terminieren:

    • Der erste Relatives Datum mit Zeit-Wertauflöser ermittelt zunächst ausgehend von der aktuellen Systemzeit den "Anfang des nächsten Tages", (s. Typ-Parameter) bezieht sich dabei aber auf die Zeitzone "Europe/Kiev".

    • Der unterhalb verkettete Relatives Datum mit Zeit-Wertauflöser verwendet den Typ "Benutzerdefiniert", um den Offset von 36 Stunden (+36) auf den bisherigen Wert aufzuschlagen.

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 ...
0h 0m 0s 0S +2d +12H ... oder ebenso gleichwertig ...
12h 0m 0s 0S +2d

images/download/attachments/78256099/image2022-9-15_13-21-53-version-1-modificationdate-1663240913470-api-v2.png

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:

  • Links und rechts wird per Verkettung mit einem Objekt-Feld-Wertauflöser auf das Feld "Datumswert" (dateValue) zugegriffen.

  • Die Zuweisung betrifft dadurch nur die Millisekunden-Komponente des "Datum mit Zeit"-Datenobjekts, während dessen Zeitzone rechts ignoriert und links unverändert beibehalten wird.

images/download/attachments/78256099/image2022-9-15_13-43-13-version-1-modificationdate-1663242193656-api-v2.png