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').


images/download/attachments/78256099/image2022-9-15_18-34-56-version-1-modificationdate-1663259697018-api-v2.png

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
(Milliseconds since 01/01/1970 UTC)

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'

images/download/attachments/78256099/image2022-9-15_18-35-43-version-1-modificationdate-1663259743567-api-v2.png

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.

  • The input value is a 'Date with time', which refers to 12/20/2020 at 00:00 in the 'Asia/Manila' time zone.

  • The sample configuration (without selection for the Time Zone) returns 12/22/2020 at 06:30 (in Manila).

  • With 'Europe/Berlin' in the Time Zone parameter, 12/21/2020 at 06:30 (in Berlin) would be returned instead, This corresponds to 13:30 (on 12/21/2020) in Manila. The return value is therefore 10.5 hours ahead of the original result (see above).

    • The input value is first converted to the Berlin time zone (12/19/2020 17:00).

    • The offset (+2) for the calendar day is applied 'in Berlin time'. After that the local time is set.

All other types

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

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.

  • The time calculation pattern for 'End of today' is: 23h 59m 59s 999S.

  • Since 'Europe/Lisbon' is selected as Time Zone, the end of the current calendar day in this time zone is output. This may be different from the calendar day that would be considered as 'Today' in the time zone applicable without selection for the Time Zone parameter. For example, when the system is in the 'Europe/Berlin' time zone and displays the time 00:30. Then, from Berlin's point of view, it is still 'yesterday' in Lisbon.

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

images/download/attachments/78256099/image2022-9-15_18-37-19-version-1-modificationdate-1663259839572-api-v2.png

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

images/download/attachments/78256099/image2022-9-15_18-42-33-version-1-modificationdate-1663260153494-api-v2.png

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:

  • 'Default time zone' field in the user account of the logged in session.

  • 'Default time zone' field in the company account of the logged in session.

  • Settings in the operating system relevant for the execution context (client/server).

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

images/download/attachments/78256099/image2022-9-15_18-43-37-version-1-modificationdate-1663260217719-api-v2.png

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)
NOTE0M refers to the last month in the previous year

d

Day

Day of the month

1 to number of days in the month in question
NOTE
0d refers to the last day of the previous month

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
NOTE0D refers to the last day of the previous year

E/F

Day of the week

1 (Monday) to 7 (Sunday)
IMPORTANTBy definition, the calendar week always starts on Mondays!
NOTE0E/0F refer to the Sunday of the previous week

q

Quarter/Day

First day of the quarter

1 to 4
NOTE0q refers to the first day in the last quarter of the previous year

Q

Last day of the quarter

1 to 4
NOTE0Q refers to the last day in the last quarter of the previous year

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:

  • Within a Field restriction, the left side per Property projection refers to the 'Password expiry date' field. This field is of the 'Date with time' type.

  • On the right side of the Field restriction, the Relative date with time value resolver is used to define the cut-off date for the comparison by the 'End of current month' Type.

  • The Matchers used here is a Compare with for which a '<' condition has been selected.

    NOTE◄ A Time Zone has not been specified here. Therefore, the default time zone applicable in the context of the session is taken into account for the delimitation of the month. The comparison is effectively made using the 'UTC milliseconds', so that the time zone of the expiration date can also have an influence on the display of users.

images/download/attachments/78256099/image2022-9-15_18-45-28-version-1-modificationdate-1663260328898-api-v2.png

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

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:

  • Within a Field restriction, the left side refers to the 'Password expiry date' field by Property projection. This field is of the 'Date with time' type.

  • On the right side of the Field restriction, the Relative date with time value resolver with the 'Custom' Type is used, since there is no predefined time 'in 14 days'. The start of the 15th day after today (in the 'Europe/Berlin' Time Zone) is calculated as the Custom time based on the current system time. This value is no longer accepted by the criterion in connection with the '<' comparison.

  • The Matchers used here is a Compare with for which a '<' condition has been selected.

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

images/download/attachments/78256099/image2022-9-15_18-48-15-version-1-modificationdate-1663260495736-api-v2.png

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:

  • On the left, an Object property value resolver defines the 'Valid to' (validTo) field as the target of the value assignment.

  • On the right, two instances of the Relative date with time value resolver are concatenated to schedule the expiration of the validity of the copied account:

    • The first Relative date with time value resolver initially determines the 'Begin of next day' based on the current system time (see Type parameter), but refers to the Time Zone 'Europe/Kiev'.

    • The Relative date with time value resolver concatenated below uses the 'Custom' Type to add the offset of 36 hours (+36) to the previous value.

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 ...
0h 0m 0s 0S +2d +12H ... or equally equivalent ...
12h 0m 0s 0S +2d

images/download/attachments/78256099/image2022-9-15_18-50-16-version-1-modificationdate-1663260616384-api-v2.png

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:

  • On the left and on the right, the 'Date value' (dateValue) field is accessed by concatenation with an Object property value resolver.

  • As a result, the assignment affects only the millisecond component of the 'Date with time' data object, while its time zone is ignored on the right and kept unchanged on the left.

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