See also: Date range type (Dynamic enumeration), Date/Time (Value resolver)

Value resolver – Abstract

Purpose: Returns a 'Date range with time' calculated by predefined or user-defined time calculation patterns relative to the system time or the input value (only for 'Custom').

images/download/attachments/78256094/image2022-9-16_18-49-40-version-1-modificationdate-1663346981142-api-v2.png

The Relative date range with time value resolver provides a 'Date range 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 (with the same value for 'From' and 'To') 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 range with time'	`core:DateRange`	'From' (`start`) – 'To' (`end`) field	'Time zone' (`timeZone`) field is taken into account for the return value only if there is no selection for the Time zone parameter.
'Date with time'	`core:DateTime`	'Date value' (`dateValue`) field for 'From' and 'To'
'Long'	`java.lang.Long`	Input value for 'From' and 'To'	n/a
'Timestamp'	`java.sql.Timestamp`
'Date'	`java.util.Date`

The return value is determined depending on the selected Type (see Date range type) starting from the reference time by a time calculation pattern for Custom start ('From' time) and Custom end ('To' time):

Type

Configuration example

Return value calculation

'Custom'

images/download/attachments/78256094/image2022-9-16_18-52-35-version-1-modificationdate-1663347155109-api-v2.png

The time calculation patterns defined in the Custom start and Custom end parameters are applied to the reference time (either suitable input value or the system time).

In the example, starting from the system time or a suitable input value, the period that begins at 10:00 p.m. on the calendar day before the 'From' date and ends at 6:00 a.m. on the calendar day following the To' date is calculated.

►IMPORTANT◄ The time zone applicable for the return value is also decisive for the interpretation of the time calculation patterns. 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 the interval from 12/19/2020 at 22:00 to 12/21/2020 at 6:00 (in Manila) as the return value.
With 'Europe/Berlin' in the Time zone parameter, the period from 12/18/20/20 at 22:00 to 12/20/20 at 6:00 (in Berlin) would be returned instead. This corresponds to the period from 12/19/2020 at 05:00 to 12/20/20 at 13:00 in Manila. The return value is therefore 17 hours before the original result (see above).
- The input value is first converted to the Berlin time zone (12/19/2020 17:00).
- The offsets for Custom start (-1) and Custom end (+1d) are applied 'in Berlin time'. After that the local time is set.

All other types

images/download/attachments/78256094/image2022-9-16_18-53-14-version-1-modificationdate-1663347194471-api-v2.png

The time calculation pattern stored for the selected Type in the Date range 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 range type, 'Next day') in the Time zone 'Europe/Lisbon' is returned.

The time calculation patterns for 'Next day' are 0h 0m 0s 0S +1d (for the 'Custom start') and 23h 59m 59s 999S +1d (for the 'Custom end').
Since 'Europe/Lisbon' is selected as Time zone, the time period for the next calendar day in this time zone is output. This may be different from the calendar day that would be considered the 'next day' 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 'Date range with time' or a value that can be interpreted as a date must be present.

Parameter	Configuration	Description
Type		The Type parameter allows static single selection of a value from the Date range type dynamic enumeration. As shown in the image (left), the selection is supported by a search function. Dynamische Aufzählungsfilter 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 date range system time – system time is always returned.
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 patterns applied at runtime. The selected Time zone is also 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 start and Custom end		The Custom start and Custom end parameters support the input of a static text each, which is interpreted at runtime as a time calculation pattern (see Relative date with time, the section 'Time calculation patterns' for details). ►NOTE◄ These parameters only appear if the 'Custom' (`CUSTOM`) Type is selected. For all other types, suitable time calculation patterns for 'Start' and 'End' should be stored in the Date range type dynamic enumeration. Custom types with specific time calculation patterns can also be added there. In the example, the Custom start refers to the beginning of a calendar day in the Time zone 'Asia/Tokyo', which is determined either by the system time, the input value or the 'From' field contained therein, depending on the reference time. The Custom end is determined as the beginning of the quarter in the same Time zone that starts after the end of the reference time (determined by system time, input value or 'To' field contained therein). If no time calculation pattern is specified as Custom start or Custom end , then the corresponding component from the reference time is output, if necessary, taking into account the selected Time zone.

Examples

Simple use case: Delimiting a search by a relative date range

In an overview for Event handling it is easy to find out which of the displayed Event handling were last modified yesterday by using filters or sorting for the column 'Last modified' (lastModified).

Runtime example:

images/download/attachments/78256094/image2022-9-16_19-0-30-version-1-modificationdate-1663347630707-api-v2.png

In the dropdown for filtering for the 'Last modified' column, the 'Date range types' defined via the dynamic enumeration Date range type appear for selection, because this is how it is intended for the data type of the column (Timestamp).
In the image, 'Previous day' has been selected, so that the list will only list Event handling as rows whose 'Last modified' date is in the date range that is considered 'Yesterday' by the current system time.

The definition for the relative date range 'Previous day' (YESTERDAY) predefined by the system is now also used to set up a row formatting for the overview, which shades all rows with 'modified yesterday' Event handling yellow.

Configuration:

The screenshot on the right shows the Row formatter configuration added within the existing data grid settings for the Event handling context:

The row formatting has been assigned the Format name 'MODIFIED_YESTERDAY'.
The only Condition here is a field restriction for the 'Last modified' (lastModifiied) field, which is accessed by a Property projection on the left.
For the comparison value on the right side of the Feld Einschränkung, the Relative date range with time value resolver is used:
- As Type – similar to the interactively set filter in the runtime example above – 'Previous day' (YESTERDAY) is selected here.
- A Time zone is not specified.
The decisive factor is the selection of the comparison operator between, which enables the comparison between the time (left side) and the period (right side). Effectively, the Format settings of the Row Formatter 'MODIFIED_YESTERDAY' are considered to be assigned exactly to the rows that are recognized as 'modified yesterday', because the 'Last modified' is in the relative date range 'Previous day' (with reference to the current system time)

images/download/attachments/78256094/image2022-9-16_19-1-35-version-1-modificationdate-1663347695880-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 predefined date ranges (here: YESTERDAY) via the DateRangeValue object (here as the value element of a Feld Einschränkung) 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="lastModified"/>
<compareType>between</compareType>
<value type="YESTERDAY" xsi:type="core:DateRangeValue"/>
</core:PropertySearch>

Use case: Defining the appointment confirmation 'Almost there!'

If a shipment is assigned the working state 'Almost there!' (ON_FINAL) a deliverySlot variable should be assigned a date range object that starts immediately – i.e. with the current system time – and ends 15 minutes later.

Configuration:

Within an event handler, a Set value event action is configured as shown on the right:

On the left side, a Variable deliverySlot is determined as the target of the assignment, in which the calculated 'Date range with time' is held before other event actions are executed.
On the right, a Relative date range with time value resolver is used to calculate date range starting from the system time (assumption: the input value in the context is not a date range or time) to quantify the commitment 'Almost there!':
- Since no time calculation pattern was specified for the Custom start, the system time is set.
- The Custom end is determined by an offset of 15 minutes (+15), which is calculated taking into account the seconds and milliseconds relative to the system time.
- The selection of the Time zone has no influence on the calculation here. However, it is explicitly assigned to the 'Date range with time' in the return value.

images/download/attachments/78256094/image2022-9-16_18-57-37-version-1-modificationdate-1663347457659-api-v2.png

In the next step, the configuration is optimized so that the date range for the deliverySlot is no longer calculated relative to the system time, but relative to the 'Date with time' value in the 'Realization time' (realization) field for the relevant working state entry.

The existing configuration is adapted for this purpose as shown on the right:

The left side can be taken over unchanged. The target of the assignment is again the deliverySlot variable.
On the right side, an input value for the Relative date range with time value resolver is obtained by concatenation above it. Since the value resolver is executed with the working state of the shipment (from the currentWorkingstate field; not shown in the image) as the reference object, its 'Realization time' (realization) field can be accessed directly via an Object property value resolver.
- The parameters for the Relative date range with time value resolver can be kept unchanged, since the 'Realization time' is the input value for the Custom start and the Custom end is the 'Reference time'.

►NOTE◄ If no 'Realization time' is specified for the working state entry when adding a working state, Lobster Data Platform / Orchestration automatically assigns the current system time as the 'Realization time'. Therefore, this field should never be empty for a working state entry when event handling is triggered when setting a working state (see Working state (Events)). In general, however, it must be taken into account that a Relative date range with time value resolver with the 'Custom' Type will fall back to the system time if the input value is empty or just unsuitable by type.

images/download/attachments/78256094/image2022-9-16_18-58-37-version-1-modificationdate-1663347517447-api-v2.png