Datum formatieren

Wertauflöser - Kurzfassung
Zweck: Wandelt einen Datumswert oder Datumsbereich im Eingabewert in eine formatierte Zeichenfolge um, die einen Zeitpunkt oder ein Intervall beschreibt.
Tooltip
Verwendung: Aus einem Eingabewert, der einen Zeitpunkt (Datum/Uhrzeit mit Zeitzone) oder ein Intervall (Datum/Zeit-Bereich mit Zeitzone) definiert, wird über das als Format definierte Pattern formatiert.
Parameter:
Der optionale Parameter Format kann das Pattern per Direkteingabe (statisch) oder über einen Wertauflöser (dynamisch) definieren. Ohne Angabe greifen Standard-Patterns für die Aktuelle Sprache oder die ausgewählte Sprache.
Das Standard-Pattern wir über die Sprachverwaltung oder Firmenspezifische Sprachanpassungen definiert: [lobsterui,dateFormat] [lobsterui,timeFormat]
Der optionale Parameter Sprache erscheint nur im serverseitigen Einsatz. Die Auswahl betrifft lokalisierbare Komponenten im Format bzw. die Auswahl des Standard-Formats aus der Sprachverwaltung. Ohne Angabe greift das serverseitige Java-Locale.
Clientseitig gilt für die Lokalisierung alternativlos die Aktuelle Sprache.
Hinweis: Abhängig vom Einsatzkontext des Wertauflösers (Server vs. Client) greifen ggf. unterschiedliche Regeln und Restriktionen für die Interpretation des Patterns (Details s. Handbuch).

Im Server-Kontext (z. B. Ereignisbehandlungen)	Im Client-Kontext (z. B. Client Workflow)
	►HINWEIS◄ Die Auswahl einer Sprache wird clientseitig nicht unterstützt. Die Aktuelle Sprache bestimmt im Client alternativlos die Lokalisierung.

Der Datum formatieren-Wertauflöser wandelt den als Eingabewert anliegenden Datumswert oder Datumsbereich nach der als Format definierten Vorlage (Pattern) in eine formatierte Zeichenfolge um.

Interpretation von Datumswerten ohne deklarierte Zeitzone
Ein Long-Wert als Eingabewert wird als Millisekunden seit 01.01.1970 00:00:00.000 (UTC) interpretiert. Allerdings gilt dabei - wie für alle als Datum interpretierten Eingabewert-Typen ohne Zeitzone (Long, Timestamp, Date) - nicht die Zeitzone UTC als Standard. Vielmehr wird die im Kontext anwendbare Standard-Zeitzone nach folgender Logik berücksichtigt:
Sofern für den Benutzer der Session (in der tatsächlich angemeldeten Sitzung) eine "Default Zeitzone" (defaultTimeZone) definiert ist, wird diese verwendet.
Andernfalls wird auf das Konto der Firma der Session (in der tatsächlich angemeldeten Sitzung) und die dort ggf. definierte "Default Zeitzone" (defaultTimeZone) zurückgegriffen.
Nur wenn keines der beiden Konten eine "Default Zeitzone" für die tatsächlich angemeldete Sitzung definiert, gibt die Auswahl für die Zeitzone im Betriebssystem des Servers oder Clients den Ausschlag:
Im Server-Kontext (z. B. für Ereignisbehandlungen) wird die Zeitzone aus dem Ausführungskontext des Lobster Data Platform / Orchestration-Servers übernommen.
Im Client-Kontext (z. B. in einem Client Workflow) wird die Auswahl für die Zeitzone im Client-Betriebssystem übernommen.

Für einen Datumsbereich wird dasselbe Format für Von- und Bis-Zeitpunkt angewendet.

Der Rückgabewert des Wertauflösers zeigt einen Datumsbereich nur als Intervall an, wenn sich die formatierten Werte (Von/Bis) unterscheiden.
- Ein Relativer Datumsbereich mit Zeit-Wertauflöser mit dem Typ "Dieses Jahr" ergibt bei einer Formatierung mit Datum, Uhrzeit und Zeitzone z. B. das folgende Intervall:
  
  01.01.2022 00:00 (UTC) - 31.12.2022 23:59 (UTC)
Sofern die formatierten Zeichenfolgen für Von-Zeitpunkt und Bis-Zeitpunkt eines Datumsbereichs identisch ausfallen, definiert der Rückgabewert kein Intervall, sondern nur den (gemeinsamen) Zeitpunkt.
- Ein Relativer Datumsbereich mit Zeit-Wertauflöser mit dem Typ "Dieser Tag" ergibt für ein Format, das nur Datum und Zeitzone verwendet, z. B. den folgenden Rückgabewert:
  
  30.04.2022 (UTC)

Konfiguration

Im optionalen Parameter Format kann per Direkteingabe (als statischer Text) oder über Wertauflöser zur Laufzeit ein sogenanntes Pattern festgelegt werden, das die gewünschte Kombination von Datum/Uhrzeit-Komponenten in Kombinationen mit "Literalen" (z. B. Trennzeichen) definiert.

Der optionale Parameter Sprache wird nur im serverseitigen Einsatz unterstützt. Er definiert explizit die Sprache für Lokalisierungen im Rückgabewert und ggf. das anwendbare Standard-Pattern.

Wie und welche Pattern letters im Parameter Format zur Laufzeit interpretiert werden, hängt vom Einsatzkontext des Wertauflösers ab:

Einsatzkontext	Interpretation des Patterns im Parameter "Format"	Beispiel
Server (z. B. in Ereignisbehandlungen)	Pattern-Syntax für das Java SimpleDateFormat mit den folgenden Ausnahmen: ►WICHTIG◄ Spezifische Abweichungen vom SimpleDateFormat Der Pattern Letter `Y` ("Week year") wird interpretiert wie `y` ("Year"); "Week year" (`Y`) wird vom Datum formatieren-Wertauflöser effektiv nicht unterstützt. Der Pattern Letter D ("Day of year") wird interpretiert wie d ("Day of month"); "Day of year" (`D`) wird vom Datum formatieren-Wertauflöser effektiv nicht unterstützt. Alle anderen Pattern Letters für das Java SimpleDateFormat werden unterstützt. Hochkommas können verwendet werden, um Literale zu definieren, die Pattern letters enthalten. Jede Komponente kann in demselben Pattern mehrfach adressiert werden. Serverseitig erfolgt per Standard keine Lokalisierung von Datumskomponenten (im Unterschied zum Client, der analog zur fd (Datum formatieren)-Funktion lokalisiert). Über den optionalen Parameter Sprache kann allerdings explizit die für Lokalisierungen zu berücksichtigende Sprache statisch (durch Statische Werte in der Konfiguration) oder dynamisch (über Wertauflöser anderer Kategorien) definiert werden. Ohne Zuordnung einer Sprache greift serverseitig das Java-`Locale` abhängig vom Ausführungskontext des Lobster Data Platform / Orchestration-Servers: Für Quartale (`QQQQ`), Monate (`MMM`,`MMMMM`), Wochentage (`EEE`,`EEEE`) und das "AM/PM"-Merkmal (`a`) werden per Standard die Texte ausgegeben, die Java vorsieht. Die Java-Lokalisierungen können sich von den korrespondierenden Standard-Lokalisierungen im `lobsterui`-Bundle unterscheiden. Für die Sprache "Deutsch" (`de`) sieht Java als Kurzform für den Monat "März" (per Pattern `MMM`) den Text `Mär` vor. Die Standard-Lokalisierung aus der Sprachverwaltung von Lobster Data Platform / Orchestration weist über die Standard-Lokalisierung für die Bundle/Resource-Kombination `lobsterui/monthNamesShort` den Text `Mrz`	`HH:mm 'am' dd-MMMM-yyyy` liefert z. B. `13:45 am 31-December-2021` ... sofern der Ausführungskontext des Lobster Data Platform / Orchestration-Servers "Englisch" lokalisiert ist.
Client (z. B. in einem Client Workflow)	Eingeschränkte Pattern-Syntax, wie für die Funktion fd (Datum formatieren) beschrieben: Nur eine Teilmenge der Pattern Letters (s. Java SimpleDateFormat) wird unterstützt. Nicht unterstützte Pattern letters (z. B. `W`) gelten als Literal. Hochkommas bewirken nicht den "Schutz" von Literalen, die Pattern Letters enthalten. Sie werden als Literale behandelt. Jede Komponente darf max. einmal im Pattern adressiert werden, sonst lautet der Rückgabewert`$null`. Lokalisierung von Datumskomponenten (über Sprachverwaltung bzw. Firmenspezifische Sprachanpassungen), wie für die Funktion fd (Datum formatieren) beschrieben Für Quartale (`QQQQ`), Monate (`MMM,MMMMM`), Wochentage (`EEE,EEEE`) und das "AM/PM"-Merkmal (`a`) werden Lokalisierungseinträge für das `lobsterui`-Bundle für die Aktuelle Sprache verwendet.	`HH:mm 'am' dd-MMMM-yyyy` liefert immer `$null` , weil ... die Hochkommas nicht das Literal "`am`" schützen, dessen Zeichen daraufhin als Pattern letters interpretiert werden und die Komponente "Minuten" (`m`) damit unzulässiger Weise doppelt adressiert wird. `HH:mm ~ dd-MMMM-yyyy` liefert z. B. `13:45 ~ 31-Dezember-2021`

Einsatzkontext

Interpretation des Patterns im Parameter "Format"

Beispiel

Server
(z. B. in Ereignisbehandlungen)

images/download/attachments/177910606/image-2024-9-11_9-40-15-version-1-modificationdate-1726040415184-api-v2.png

Pattern-Syntax für das Java SimpleDateFormat mit den folgenden Ausnahmen:

►WICHTIG◄ Spezifische Abweichungen vom SimpleDateFormat
Der Pattern Letter Y ("Week year") wird interpretiert wie y ("Year"); "Week year" (Y) wird vom Datum formatieren-Wertauflöser effektiv nicht unterstützt.
Der Pattern Letter D ("Day of year") wird interpretiert wie d ("Day of month"); "Day of year" (D) wird vom Datum formatieren-Wertauflöser effektiv nicht unterstützt.

Alle anderen Pattern Letters für das Java SimpleDateFormat werden unterstützt.
Hochkommas können verwendet werden, um Literale zu definieren, die Pattern letters enthalten.
Jede Komponente kann in demselben Pattern mehrfach adressiert werden.

Serverseitig erfolgt per Standard keine Lokalisierung von Datumskomponenten (im Unterschied zum Client, der analog zur fd (Datum formatieren)-Funktion lokalisiert). Über den optionalen Parameter Sprache kann allerdings explizit die für Lokalisierungen zu berücksichtigende Sprache statisch (durch Statische Werte in der Konfiguration) oder dynamisch (über Wertauflöser anderer Kategorien) definiert werden.

Ohne Zuordnung einer Sprache greift serverseitig das Java-Locale abhängig vom Ausführungskontext des Lobster Data Platform / Orchestration-Servers:

Für Quartale (QQQQ), Monate (MMM,MMMMM), Wochentage (EEE,EEEE) und das "AM/PM"-Merkmal (a) werden per Standard die Texte ausgegeben, die Java vorsieht.
Die Java-Lokalisierungen können sich von den korrespondierenden Standard-Lokalisierungen im lobsterui-Bundle unterscheiden. Für die Sprache "Deutsch" (de) sieht Java als Kurzform für den Monat "März" (per Pattern MMM) den Text Mär vor. Die Standard-Lokalisierung aus der Sprachverwaltung von Lobster Data Platform / Orchestration weist über die Standard-Lokalisierung für die Bundle/Resource-Kombination lobsterui/monthNamesShort den Text Mrz

HH:mm 'am' dd-MMMM-yyyy

liefert z. B.

13:45 am 31-December-2021

... sofern der Ausführungskontext des Lobster Data Platform / Orchestration-Servers "Englisch" lokalisiert ist.

Client
(z. B. in einem Client Workflow)

images/download/attachments/177910606/image-2024-9-11_9-42-15-version-1-modificationdate-1726040534565-api-v2.png

Eingeschränkte Pattern-Syntax, wie für die Funktion fd (Datum formatieren) beschrieben:

Nur eine Teilmenge der Pattern Letters (s. Java SimpleDateFormat) wird unterstützt. Nicht unterstützte Pattern letters (z. B. W) gelten als Literal.
Hochkommas bewirken nicht den "Schutz" von Literalen, die Pattern Letters enthalten. Sie werden als Literale behandelt.
Jede Komponente darf max. einmal im Pattern adressiert werden, sonst lautet der Rückgabewert$null.

Lokalisierung von Datumskomponenten (über Sprachverwaltung bzw. Firmenspezifische Sprachanpassungen), wie für die Funktion fd (Datum formatieren) beschrieben

Für Quartale (QQQQ), Monate (MMM,MMMMM), Wochentage (EEE,EEEE) und das "AM/PM"-Merkmal (a) werden Lokalisierungseinträge für das lobsterui-Bundle für die Aktuelle Sprache verwendet.

HH:mm 'am' dd-MMMM-yyyy

liefert immer $null , weil ...

die Hochkommas nicht das Literal "am" schützen,
dessen Zeichen daraufhin als Pattern letters interpretiert werden und
die Komponente "Minuten" (m) damit unzulässiger Weise doppelt adressiert wird.

HH:mm ~ dd-MMMM-yyyy

liefert z. B.

13:45 ~ 31-Dezember-2021

Ohne Angabe eines Patterns für die Format-Zeichenfolge werden Lokalisierungseinträge aus der Sprachverwaltung oder Firmenspezifische Sprachanpassungen nach dem folgenden Schema als Standard-Pattern zugeordnet:

Schema für das Standard-Pattern

[lobsterui,dateFormat] [lobsterui,timeFormat]

Die Sprachverwaltung sieht per Standard folgende Lokalisierungen für das Standard-Pattern vor:

Komponente	Bundle	Resource	Sprache	Standard-Pattern	Beispiel
Datum	`lobsterui`	`dateFormat`	Deutsch (`de`)	`DD.MM.YYYY`	`31.12.2021`
Datum		`dateFormat`	Englisch (`en`)	`MM/DD/YYYY`	`12/31/2021`
Uhrzeit		`timeFormat`	Deutsch (`de`)	`HH:mm`	`13:45`
Uhrzeit		`timeFormat`	Englisch (`en`)	`hh:mm a`	`01:45 PM`

Die beiden Komponenten (Datum und Uhrzeit) werden per Standard gemeinsam (getrennt durch ein Leerzeichen) ausgegeben.

►HINWEIS◄ Die als Lokalisierungstexte hinterlegten Patterns sollten so definiert sein, dass sie der restriktiveren Syntax für den Client-Kontext entsprechen (s. Tabelle oben). Anderenfalls liefert der Datum formatieren-Wertauflöser im clientseitigen Einsatz immer $null als Rückgabewert, wenn kein Format angegeben ist.

Weitere Standard-Lokalisierungen in der Sprachverwaltung, die für die Ausgabe relevant sein können:

Komponente	Pattern	Bundle	Resource	Sprache	Standard
Datum	Monat`MMMM`	`lobsterui`	`monthNames`	Deutsch (`de`)	`Januar,Februar,März,April,Mai,Juni,Juli,August,September,Oktober,November,Dezember`
	Monat`MMMM`		`monthNames`	Englisch (`en`)	`January,February,March,April,May,June,July,August,September,October,November,December`
	Monat (kurz) `MMM`		`monthNamesShort`	Deutsch (`de`)	`Jan,Feb,Mrz,Apr,Mai,Jun,Jul,Aug,Sep,Okt,Nov,Dez`
	Monat (kurz) `MMM`		`monthNamesShort`	Englisch (`en`)	`Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec`
	Wochentag `dddd`		`dayNames`	Deutsch (`de`)	`Sonntag,Montag,Dienstag,Mittwoch,Donnerstag,Freitag,Samstag`
	Wochentag `dddd`		`dayNames`	Englisch (`en`)	`Sunday,Monday,Tuesday,Wednesday,Thursday,Friday,Saturday`
	Wochentag (kurz) `ddd`		`dayNamesShort`	Deutsch (`de`)	`So,Mo,Di,Mi,Do,Fr,Sa`
	Wochentag (kurz) `ddd`		`dayNamesShort`	Englisch (`en`)	`Sun,Mon,Tue,Wed,Thu,Fri,Sat`
	Quartal `QQQQ`		`quarterNames`	Deutsch (`de`)	`erstes Quartal,zweites Quartal,drittes Quartal,viertes Quartal`
	Quartal `QQQQ`		`quarterNames`	Englisch (`en`)	`first quarter,second quarter,third quarter,fourth quarter`
Uhrzeit	AM/PM `a`		`am`	Deutsch (`de`)	`vorm.`
			`am`	Englisch (`en`)	`AM`
			`pm`	Deutsch (`de`)	`nachm.`
			`pm`	Englisch (`en`)	`PM`

Beispiele

Formatierung eines Datumswerts

Konfiguration	Ergebnis (im Server-Kontext)	Ergebnis (im Client-Kontext)
	Aufgrund der Einstellungen für den Ausführungskontext des Lobster Data Platform / Orchestration-Servers erscheint das Datumsformat (hier) immer in Java-"Englisch"	Im Client werden die Lokalisierungen für die Sprache "Deutsch" (`de`) berücksichtigt.

Konfiguration

Ergebnis (im Server-Kontext)

Ergebnis (im Client-Kontext)

images/download/attachments/177910606/image2019-3-15_13-16-49-version-1-modificationdate-1726040407548-api-v2.png

images/download/attachments/177910606/image2022-7-7_9-37-58-version-1-modificationdate-1726040407657-api-v2.png

Aufgrund der Einstellungen für den Ausführungskontext des Lobster Data Platform / Orchestration-Servers erscheint das Datumsformat (hier) immer in Java-"Englisch"

images/download/attachments/177910606/image2022-7-5_16-41-52-version-1-modificationdate-1726040407648-api-v2.png

Im Client werden die Lokalisierungen für die Sprache "Deutsch" (de) berücksichtigt.

Im Beispiel wird die aktuelle Uhrzeit über einen Wertauflöser vom Typ Relatives Datum mit Zeit ermittelt. Sie soll formatiert als Text einer Meldung erscheinen.

Der Datum formatieren-Wertauflöser wird per Verkettung nachgeschaltet, um die Ausgabe von Datum und Uhrzeit (hier inkl. Zeitzone) zu formatieren.

Formatierung von Datum und Uhrzeit per Standard je Sprache

Konfiguration	Ergebnis (DE)	Ergebnis (EN)
Ohne Parameter werden die Standardformate für Datum und Uhrzeit aus der Sprachverwaltung (s. o.) angewendet. Würde auf den Datum formatieren-Wertauflöser im Kontext der Meldung dagegen komplett verzichtet, dann zeigt die Meldung das String-Abbild für den "Datumsbereich mit Zeit" im folgenden Format: `2019-03-10 23:00:00.000 UTC - 2019-03-16 23:00:00.000 UTC`	Basierend auf diesen Einträgen in der Sprachverwaltung:	Basierend auf diesen Einträgen in der Sprachverwaltung:
►WICHTIG◄ Falls das über den Lokalisierungseintrag definierte Standard-Pattern lokalisierbare Komponenten (z. B. das Pattern `EEEE` für den Wochentag) enthält, unterscheidet sich das Ergebnis wie oben gezeigt abhängig vom Einsatzkontext (Server: abh. vom Java-`Locale`, Client: Aktuelle Sprache). Der serverseitige Ausführungskontext ist auch maßgeblich für andere Aspekte der Datumsbehandlung in Lobster Data Platform / Orchestration. Dazu gehört u. a. die Einstellung für den ersten Tag der Woche. Ob die "Aktuelle Kalenderwoche" - wie oben links - von Montag (11.03.2019) bis Sonntag oder - wie oben rechts - von Sonntag (10.03.2019) bis Montag abgegrenzt wird, hängt ausschließlich von der serverseitigen Einstellung für den ersten Tag der Woche ab. Die beiden Screenshots wurde also auf zwei unterschiedlichen Systemen erzeugt. ►ANMERKUNG◄ Die Sprachverwaltung enthält einen Eintrag `lobsterui/firstDayOfWeek`, der aber nur für die Darstellung von DatePicker-Elementen (z. B. Datum/Uhrzeit und Datumsbereich) in der interaktiven Oberfläche ausschlaggebend ist.

Konfiguration

Ergebnis (DE)

Ergebnis (EN)

images/download/attachments/177910606/image2019-3-15_14-6-0-version-1-modificationdate-1726040407564-api-v2.png

Ohne Parameter werden die Standardformate für Datum und Uhrzeit aus der Sprachverwaltung (s. o.) angewendet.

Würde auf den Datum formatieren-Wertauflöser im Kontext der Meldung dagegen komplett verzichtet, dann zeigt die Meldung das String-Abbild für den "Datumsbereich mit Zeit" im folgenden Format:

2019-03-10 23:00:00.000 UTC - 2019-03-16 23:00:00.000 UTC

images/download/attachments/177910606/image2019-3-15_14-2-45-version-1-modificationdate-1726040407559-api-v2.png

Basierend auf diesen Einträgen in der Sprachverwaltung:

images/download/attachments/177910606/image2019-3-15_14-9-24-version-1-modificationdate-1726040407566-api-v2.png

images/download/attachments/177910606/image2019-3-15_14-4-28-version-1-modificationdate-1726040407561-api-v2.png

Basierend auf diesen Einträgen in der Sprachverwaltung:

images/download/attachments/177910606/image2019-3-15_14-11-57-version-1-modificationdate-1726040407568-api-v2.png

►WICHTIG◄ Falls das über den Lokalisierungseintrag definierte Standard-Pattern lokalisierbare Komponenten (z. B. das Pattern EEEE für den Wochentag) enthält, unterscheidet sich das Ergebnis wie oben gezeigt abhängig vom Einsatzkontext (Server: abh. vom Java-Locale, Client: Aktuelle Sprache).

Der serverseitige Ausführungskontext ist auch maßgeblich für andere Aspekte der Datumsbehandlung in Lobster Data Platform / Orchestration. Dazu gehört u. a. die Einstellung für den ersten Tag der Woche. Ob die "Aktuelle Kalenderwoche" - wie oben links - von Montag (11.03.2019) bis Sonntag oder - wie oben rechts - von Sonntag (10.03.2019) bis Montag abgegrenzt wird, hängt ausschließlich von der serverseitigen Einstellung für den ersten Tag der Woche ab. Die beiden Screenshots wurde also auf zwei unterschiedlichen Systemen erzeugt.

►ANMERKUNG◄ Die Sprachverwaltung enthält einen Eintrag lobsterui/firstDayOfWeek, der aber nur für die Darstellung von DatePicker-Elementen (z. B. Datum/Uhrzeit und Datumsbereich) in der interaktiven Oberfläche ausschlaggebend ist.

Formatierung von Datum und Uhrzeit für eine bestimmte Sprache

Im Kontext einer Ereignisbehandlung soll im "Betreff" einer E-Mail für eine Buchungsbestätigung das Buchungsdatum ausdrücklich unter Verwendung der in Lobster Data Platform / Orchestration festgelegten Lokalisierung für die Sprache en_US wiedergegeben werden.

Die Ausgabe soll ohne Rücksicht auf die Aktuelle Sprache für eine Buchung für den 04.07.2022 wie folgt aussehen: "CONFIRMED: MON04JUL22"

Konfiguration:

Im Betreff der E-Mail-Versand-Ereignisaktion, wird der auszugebende Text durch die rechts abgebildete Verkettung von Wertauflösern erzeugt:

Der Variable-Wertauflöser liest das Buchungsdatum (Typ "Datum mir Uhrzeit") aus der Variablen confirmedSlot.
Im Datum formatieren-Wertauflöser wird das Format in Verbindung mit den Literalzeichen für den beschriftenden Klartext "CONFIRMED:" festgelegt als:
'CONFIRMED: 'EEEddMMMyy
Für die Sprache wird hier durch eine statische Auswahl in der Konfiguration die Sprache "English (US)" (en_US) für die Lokalisierung definiert.
Abschließend stellt der In Großbuchstaben-Wertauflöser sicher, dass die Kürzel für Wochentag (EEE) und Monat (MMM) in Großbuchstaben erscheinen.

images/download/attachments/177910606/image2022-7-12_11-27-36-version-1-modificationdate-1726040407539-api-v2.png

►HINWEIS◄ Die einfachen Hochkommas ('...') sind hier unbedingt erforderlich, damit der Text "CONFIRMED: " als Literal verarbeitet wird. Anderenfalls verursacht schon der erste Buchstabe ("C") eine Fehlermeldung (IllegalArgumentException: Illegal pattern character) auf.