Format date
Value resolver – Abstract
Purpose: Converts a date value or date range in the input value to a formatted string that describes a time or interval.
|
In the server context (e.g. Event handling) |
In the client context (e.g. Client workflow) |
|
|
|
The Format date value resolver converts the date value or date range present as input value into a formatted string according to the template (pattern) defined as Format.
Interpretation of date values without a declared time zone
A Long value as input value is interpreted as milliseconds since 01.01.1970 00:00:00.000 (UTC). However, as for all input value types interpreted as date without time zone (Long, Timestamp, Date), the UTC time zone is not the default. Rather, the default time zone applicable in the context is taken into account according to the following logic:
If a 'Default time zone' (defaultTimeZone) is defined for the User of session (in the actual logged-in session), this will be used.
Otherwise, the account of the Company of session (in the actual logged-in session) and the 'Default time zone' (defaultTimeZone) defined there, if applicable, are used.
Only if neither account defines a 'Default time zone' for the actual logged in session, the selection for the time zone in the operating system of the server or client will be the deciding factor:
In the server context (e.g. for Event handling) the time zone is taken from the Lobster Data Platform / Orchestration server execution context.
In the client context (e.g. in a Client workflow), the selection for the time zone is adopted in the client operating system.
For a date range, the same Format is applied for 'From' and 'To' time.
The return value of the value resolver shows a date range as an interval only if the formatted values (From/To) differ.
For example, a Relative date range with time value resolver with the 'This year' type results in the following interval when formatted with the date, time, and time zone:
01/01/2022 12:00 AM (UTC) - 12/31/2022 11:59 PM (UTC)
If the formatted strings for from-time and to-time of a date range are identical, the return value does not define an interval, but only the (common) point in time.
For example, a Relative date range with time value resolver of the 'This day' type for a format that uses only date and time zone returns the following value:
04/30/2022 (UTC)
Configuration
In the optional Format parameter, a so-called pattern can be specified by direct input (as static text) or via value resolvers at runtime, which defines the desired combination of date/time components in combinations with 'literals' (e.g. separators).
The optional Locale parameter is only supported for server-side use. It explicitly defines the Locale for localizations in the return value and, if applicable, the applicable default pattern.
How pattern letters in the Format parameter can be resolved at runtime depends on the context of use of the value resolver:
|
Operational context |
Interpretation of the pattern in the 'Format' parameter |
Example |
|
Server |
Pattern syntax for the Java SimpleDateFormat with the following exceptions: ►IMPORTANT◄ Specific deviations from SimpleDateFormat
By default, date components are not localized on the server side (unlike the client, which localizes in the same way as the fd (format date) function). However, the optional Locale parameter can be used to explicitly define the Locale to be considered for localizations statically (through Static values in the configuration) or dynamically (through value resolvers of other categories). Without assigning a Locale, the Java Locale takes effect on the server side depending on the execution context of the Lobster Data Platform / Orchestration server:
|
HH:mm 'am' dd-MMMM-yyyy returns e.g. 13:45 on 31-December-2021 ... provided that the execution context of the Lobster Data Platform / Orchestration server is localized as 'English'. |
|
Client |
Restricted pattern syntax as described for the fd function:
Localization of date components (via Localization or Company specific localization), as described for the fd function.
|
HH:mm 'am' dd-MMMM-yyyy always returns $null , because...
HH:mm ~ dd-MMMM-yyyy returns e.g.: 13:45 ~ 31-December-2021 |
Without specifying a pattern for the Format string, localization entries from the Localization or Company specific localization are assigned as default patterns according to the following scheme:
[lobsterui,dateFormat] [lobsterui,timeFormat]
Localization provides the following localizations for the default pattern by default:
|
Component |
Bundle |
Resource |
Locale |
Default pattern |
Example |
|
Date |
lobsterui |
dateFormat |
German (de) |
DD.MM.YYYY |
31.12.2021 |
|
English (en) |
MM/DD/YYYY |
12/31/2021 |
|||
|
Time |
timeFormat |
German (de) |
HH:mm |
13:45 |
|
|
English (en) |
hh:mm a |
01:45 PM |
The two components (Date and Time) are output together (separated by a space) by default.
►NOTE◄ The patterns stored as localization texts should be defined to match the more restrictive syntax for the client context (see table above). Otherwise, the Format date value resolver in client-side use will always return $null if no Format is specified.
Other default localizations in the Localization that may be relevant for the output:
|
Component |
Pattern |
Bundle |
Resource |
Locale |
Default |
|
Date |
MonthMMMM |
lobsterui |
monthNames |
German (de) |
Januar,Februar,März,April,Mai,Juni,Juli,August,September,Oktober,November,Dezember |
|
English (en) |
January,February,March,April,May,June,July,August,September,October,November,December |
||||
|
Month (short) |
monthNamesShort |
German (de) |
Jan,Feb,Mrz,Apr,Mai,Jun,Jul,Aug,Sep,Okt,Nov,Dez |
||
|
English (en) |
Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec |
||||
|
Weekday |
dayNames |
German (de) |
Sonntag,Montag,Dienstag,Mittwoch,Donnerstag,Freitag,Samstag |
||
|
English (en) |
Sunday,Monday,Tuesday,Wednesday,Thursday,Friday,Saturday |
||||
|
Weekday (short) |
dayNamesShort |
German (de) |
So,Mo,Di,Mi,Do,Fr,Sa |
||
|
English (en) |
Sun,Mon,Tue,Wed,Thu,Fri,Sat |
||||
|
Quarter |
quarterNames |
German (de) |
erstes Quartal,zweites Quartal,drittes Quartal,viertes Quartal |
||
|
English (en) |
first quarter,second quarter,third quarter,fourth quarter |
||||
|
Time |
AM/PM |
am |
German (de) |
vorm. |
|
|
English (en) |
AM |
||||
|
pm |
German (de) |
nachm. |
|||
|
English (en) |
PM |
Examples
Formatting a date value
|
Configuration |
Result (in the server context) |
Result (in the client context) with the locale 'German' (de) |
|
|
Due to the settings for the Lobster Data Platform / Orchestration server execution context, the date format (here) always appears in Java 'English'
|
In the client, the localizations for the locale 'German' (de) are taken into account. |
In this example, the current time is determined by a Relative date with time resolver to display it in a special format in a message.
The Format date value resolver is used by concatenation to format the output of date and time (here incl. time zone).
Formatting by default date and time settings from localization
|
Configuration |
Result (EN) |
Result (DE) |
|
Without parameters the default formats for date and time from the localization (see above) are applied. If, on the other hand, the Format date value resolver were completely omitted in the context of the message, then the message would display the string image for the 'Relative date range with time' in the following format: 2019-03-10 23:00:00.000 UTC- 2019-03-16 23:00:00.000 UTC |
|
|
|
►IMPORTANT◄ If the default pattern defined via the localization entry contains localizable components (e.g. the EEEE pattern for the day of the week), the result will differ depending on the deployment context (server: depends on Java Locale, client: Current locale) as shown above. The server-side execution context also governs other aspects of date handling in Lobster Data Platform / Orchestration. This includes, among other things, the setting for the first day of the week. Whether the 'Current week' – as above left – is delimited from Monday (03/10/2019) to Sunday or – as above right – from Sunday (11/03/2019) to Monday, depends solely on the server-side setting for the first day of the week. The two screenshots were therefore generated on two different systems. ►NOTE◄ The Localization contains an entry lobsterui/firstDayOfWeek, which is only relevant for the display of DatePicker elements (e.g. Date/Time and Date range) in the interactive interface. . |
||
Formatting date and time for a specific locale
In the context of event handling, the 'Subject' of a booking confirmation e-mail explicitly reflects the booking date using the localization specified in Lobster Data Platform / Orchestration for the en_US language.
The output should look like this without regard to the Current locale for a posting for 07/04/2022: 'CONFIRMED: MON04JUL22'.
Configuration:
|
In the Subject of the E-Mail event action, the text output is generated by the concatenation of value resolvers shown on the right:
|
|
►NOTE◄ The single quotation marks ('...') are absolutely necessary here so that the text 'CONFIRMED: ' is processed as a literal. Otherwise already the first letter ('C') causes an error message (IllegalArgumentException: Illegal pattern character).