Relative date with time
See also: Date time type (Dynamic enumeration), Date range with time (DateRangeValue) (Value resolver)
Value resolver – Abstract
Purpose: Returns a 'Date with time', calculated by a predefined or custom time calculation pattern relative to the system time or the input value (only for 'Custom').
The Relative date with time value resolver provides a 'Date with time' that is determined relative to one of the following reference times, depending on the selected Type:
By default, the current system time is considered the reference time for the 'relative' calculation of the return value determined by the Type.
►NOTE◄ Depending on the execution context, either the system time of the server (see Event handling) or of the client (e.g. in a Client workflow) can be the decisive factor.The input value is only taken into account in connection with the 'Custom' (CUSTOM) Type as the reference time, provided that it corresponds to one of the following data types:
Input value type |
Class |
Reference time |
Time zone (from input value) |
'Date with time' |
core:DateTime |
'Date value' (dateValue) |
'Time zone' (timeZone) field is taken into account for the return value only if there is no selection for the Time Zone parameter. |
'Date range with time' |
core:DateRange |
'Start' (start) field or if this does not return the value 'End' (end) field |
|
'Long' |
java.lang.Long |
Input value |
n/a |
'Timestamp' |
java.sql.Timestamp |
||
'Date' |
java.util.Date |
The return value is determined depending on the selected Type (see Date time type) starting from the reference time by a time calculation pattern:
Type |
Configuration example |
Return value calculation |
'Custom' |
|
The time calculation pattern defined in the Custom time parameter is applied to the reference time (either suitable input value or the system time). In the example, starting from a date given by the input value, for example, the time that is exactly at 6:30 (6H 30m 0s 0S) two calendar days later (+2d) is calculated. ►IMPORTANT◄ The time zone applicable for the return value is also decisive for the interpretation of the time calculation pattern. Since in the example (left) the Time Zone parameter does not specify a selection, the time zone is taken from the input value if one is specified (see table above). If there is a selection for the Time Zone parameter, then the respective time zone is used for the conversion instead and assigned to the return value. Effect of time zones on the interpretation in the Custom time value of the time calculation pattern.
|
All other types |
|
The time calculation pattern stored for the selected Type in the Date time type dynamic enumeration is applied to the current system time of the server or client. In the example, the end of the current calendar day (see Date time type, 'End of today') in the 'Europe/Lisbon' time zone is returned.
|
Configuration
►NOTE◄ The input value is only considered in connection with the 'Custom' (CUSTOM) Type. Then a value that can be interpreted as a date must be provided.
Parameter |
Configuration |
Description |
Type |
|
The Type parameter allows static single selection of a value from the Date time type dynamic enumeration. As shown in the image (left), the selection is supported by a search function. Dynamic enum filters can restrict the availability of options in the configuration context dropdown. They do not affect the runtime behaviour of the value resolver. ►NOTE◄ If no Type is selected, then the return value is always $null. |
Time Zone |
|
The Time Zone parameter optionally allows static single selection of a time zone supported by Java. As shown in the image (left), the selection is supported by a search function. The selection of a Time Zone influences the interpretation of the time calculation pattern applied at runtime. Also, the selected Time Zone is used for the return value. If no Time Zone is selected, then generally the default time zone applicable in the context is used, defined (in descending priority) by one of the following settings:
If there is an input value in connection with the 'Custom' (CUSTOM) Type that explicitly includes a time zone, it is taken into account if no selection has been made for the Time Zone parameter. ►NOTE◄ The selection options for time zones cannot be localized and they cannot be restricted by Dynamic enum filters. The displayed texts originate directly from the Java environment. |
Custom time |
|
The Custom time parameter supports the input of a static text which is interpreted at runtime as a time calculation pattern (see the following section for details). ►NOTE◄ The parameter appears only if the 'Custom' (CUSTOM) Type is selected. For all other types, a suitable time calculation pattern should be stored in the Date time type dynamic enumeration. Custom types with specific time calculation patterns can also be added there. In the example, the time 9:30 am (UTC) is returned on the third calendar day after the reference time. ►NOTE◄ A text for the Custom time entered once in the configuration is retained (ineffectively) if a Type other than 'Custom' is selected. It will therefore reappear if the 'Custom' Type is selected again later. If no time calculation pattern is specified as the Custom time, then the reference time, i.e. either the input value or the system time, if necessary taking into account the selected Time Zone, is output. |
Time calculation pattern
A time calculation pattern defines a string of space-separated sequence of tokens for manipulations that are intended to incrementally change an original date value.
If a time calculation pattern provides for more than one manipulation, each subsequent step receives the result of the previous manipulations as 'input'.
A list of the predefined patterns per Type is shown on the Date time type page.
Manipulation types
Absolute manipulation
The combination of an unsigned integer with a code letter defines an absolute target value for the component identified by the code letter.
Example: The token 10M defines that the component 'month in the year' (M) should be assigned the tenth month, i.e. 'October', while other components apply unchanged.
If integers outside the nominal value range are assigned to a component, the assignment usually indirectly causes changes in one or more parent components.
Example: The token 13M defines that the thirteenth 'month in the year' (M) is assigned. Effectively this refers to January of the following year.
Relative manipulation
The combination of a signed integer with a code letter defines a relatively specific target value (offset) for the component identified by the code letter.
Example: The token +2M causes an offset of the monthly component by two calendar months, which may or may not cause a change to the following calendar year depending on the current month.
Special case: Since calendar months have different numbers of days, it is possible that a month offset for different 'days of the month' results in the same target value.
Example: The token +2M is applied to the date 12/31/2020. Since the 02/31/2020 is not defined, the last defined day of the target month (here: 02/28/2021) is returned. Initial values between December 28 and 31 return the same value.
Code letters
The following table gives an overview of the meaning of the supported code letters:
Code letter |
Target component |
Meaning |
Nominal value range (for absolute assignments) |
Hierarchical date components (year > month > day > hours > minute > second > millisecond) |
|||
y |
Year |
Year |
1 to 9999 |
M |
Month |
Month of year |
1 (January) to 12 (December) |
d |
Day |
Day of the month |
1 to number of days in the month in question |
H/h |
Hour |
Hour of the day |
0 to 23 |
m |
Minute |
Minute of the hour |
0 to 59 |
s |
Second |
Second of the minute |
0 to 59 |
S |
Millisecond |
Milliseconds per second |
0 to 999 |
Special date components |
|||
D |
Day |
Day of the year |
1 to number of days in the given year |
E/F |
Day of the week |
1 (Monday) to 7 (Sunday) |
|
q |
Quarter/Day |
First day of the quarter |
1 to 4 |
Q |
Last day of the quarter |
1 to 4 |
Examples
Simple use case: Comparison value for a field constraint
An overview (see Custom overviews) should list all Users whose 'Password expiration date' (passwordExpiryDate) has passed or will pass by the end of the current month.
The screenshot on the right shows the configuration for a Restriction that takes this criterion into account:
|
|
►NOTE◄ Corresponding restrictions can also be used to define a search for an Import profile in Lobster_data. The XML structure on the right shows how easy it is to access a predefined 'Relative date' (in this example: END_THIS_MONTH) via the DateTimeValue object (here as the value element of a Field restriction) within a Search. |
<?xml version="1.0" encoding="UTF-8"?> |
The following variant covers the case that all Users are listed whose 'Password expiry date' (passwordExpiryDate) is exceeded or will be exceeded in the next 14 days.
The screenshot on the right shows the configuration for a Restriction that takes this criterion into account:
►NOTE◄ Here, a Time Zone is explicitly specified for the calculation. If the 'Password expiry date' was entered in a different time zone, the field projection still provides the decisive 'UTC milliseconds'. |
|
Simple use case: Assign a calculated appointment
When copying accounts for Guest users, an event handling should automatically limit their validity to 36 hours from the beginning of the next calendar day.
Event handling responds to the event 'Copy' (see Common action event) as a Triggering event. With this trigger, event handling becomes active immediately when a user executes the 'Copy' ribbon command. Therefore, the data object created as a copy can be initialized before the user gets access to it via the already opened data input form. The Validating rule uses Check type to ensure that actions are performed only if the copied entity is a guest user account. A set value event action is executed here as an Action on passed rule:
►NOTE◄ Instead of concatenation, it is possible to use only a Relative date with time value resolver that concatenates the expression for 'Begin of next day' in the Custom time parameter (see Date time type) with the expression for the offset: 0h 0m 0s 0S +1d +36H ... or the equivalent result ... |
|
►NOTE◄ The explicitly assigned time zone 'Europe/Kiev' in the upper right corner is taken over for the calculation and the finally assigned value, because the concatenated Relative date with time value resolver does not use an explicit selection for the Time Zone parameter. |
|
With the adaptation of the existing configuration shown on the right the time zone 'Europe/Kiev' is used for the calculation, but in the 'Valid to' (validTo) field the time zone already entered in the copied guest user account is retained:
|
|