Use work time calendars in time-related calculations

When creating calculated fields, you can use calendars as input for certain operators in time-related calculations. The code editor provides various scripting operators that you can use with calendars as operands.

Please find a description of the operators including samples below.

Prerequisite

You created at least one work time calendar.

Procedure. Procedure

Open a data set.
Click Analysis model in the Data set panel. The Analysis model section opens.
In the Model panel, select the object, for example, the Activity or Case object, to which you want to add the new field.
Click New field.
Enter a name for the new field in the corresponding input box.
Select Code editor to define the calculation rule. The code editor opens.
Define a calculation rule in the editor.
Click Add.

You created a time-related calculation based on a calendar definition.

Operators

For more details on operators, see the Scripting operators and operands chapter.

UTC and time zones

The operators use the UTC (Coordinated Universal Time) as default time if no specific time zone is specified in the operators.

ARIS Process Mining internally stores all timestamps in the process data normalized to the UTC. If timestamp data does not have any time zone information, the UTC is used, otherwise the timestamp is converted. The definition of the work time calendar does not contain a time zone. For the calculation of time spans using a work time calendar, a time zone can be specified in the operators. This time zone is used to apply the definition of the work time calendar in the correct time zone, that is, the work time calendar is converted to the UTC calendar.

The time zone is defined as a text literal according to the specification of the Java classes TimeZone and ZoneId. We recommend defining the time zone in the format GMT or UTC (for example, “GMT+2” or “UTC-0530” or “UTC+02:00”).

For the sake of simplicity, the same calendar is used for all calculation examples listed below and all calculations are using UTC as a time zone. The calendar is named “Workweek” and is defined as follows:

Example 129.

Shift start, Shift end

2023-01-02T08:00, 2023-01-02T16:00

2023-01-03T08:00, 2023-01-03T16:00

2023-01-04T08:00, 2023-01-04T16:00

2023-01-05T08:00, 2023-01-05T16:00

2023-01-06T08:00, 2023-01-06T16:00

2023-01-09T08:00, 2023-01-09T16:00

ADD_DAYS, ADD_HOURS, ADD_MINUTES, ADD_SECONDS, ADD_MILLIS, ADD_MILLIES

The existing operators were enhanced by two additional parameters Calendar and timeZone. The timeZone parameter can only be specified when the Calendar parameter is specified. If no Calendar is specified, the operators work as before without considering work time. If a Calendar parameter is specified, the operators return the result considering the work time in days, hours, minutes, seconds, or milliseconds.

Example 130.

The example is based on the operator ADD_HOURS(DateTime, AmountOfHours, Calendar, timeZone).


Tip 2023-01-02T06:00:00Z	Tip 4	Tip Workweek	Tip UTC	Tip 2023-01-02T12:00:00Z
Tip 2023-01-02T10:00:00Z	Tip 4	Tip Workweek	Tip UTC	Tip 2023-01-02T14:00:00Z
Tip 2023-01-02T14:00:00Z	Tip 4	Tip Workweek	Tip UTC	Tip 2023-01-03T10:00:00Z
Tip 2023-01-06T14:00:00Z	Tip 4	Tip Workweek	Tip UTC	Tip 2023-01-09T10:00:00Z
Tip 2023-01-09T14:00:00Z	Tip 4	Tip Workweek	Tip UTC	Tip No result
Tip 2023-01-03T10:00:00Z	Tip -4	Tip Workweek	Tip UTC	Tip 2023-01-02T14:00:00Z

ADD_WORKDAYS

The operator returns a date that is a result of adding a given amount of work days to a given date with reference to work time intervals defined in a calendar with respect to a given time zone (default is UTC). Each day with any work time interval is considered as workday. The time of day of the resulting date is the same than the time in the original date.

Example 131.

The example is based on the operator ADD_WORKDAYS(DateTime, AmountOfWorkdays, Calendar, timeZone).


Tip 2023-01-02T06:00:00Z	Tip 2	Tip Workweek	Tip UTC	Tip 2023-01-04T06:00:00Z
Tip 2023-01-02T10:00:00Z	Tip 2	Tip Workweek	Tip UTC	Tip 2023-01-04T10:00:00Z
Tip 2023-01-02T18:00:00Z	Tip 2	Tip Workweek	Tip UTC	Tip 2023-01-04T18:00:00Z
Tip 2023-01-05T16:00:00Z	Tip 2	Tip Workweek	Tip UTC	Tip 2023-01-09T16:00:00Z
Tip 2023-01-04T010:00:00Z	Tip -2	Tip Workweek	Tip UTC	Tip 2023-01-02T10:00:00Z

TIME_BETWEEN

The existing operators were enhanced by two additional parameters Calendar and timeZone. The timeZone parameter can only be specified if the Calendar parameter is specified. If no Calendar parameter is specified, the operators work as before without considering work time. If no timeZone parameter is specified, UTC is used as default time zone. If a Calendar parameter is specified, the operator returns the number of milliseconds between two dates with reference to work time intervals defined in the specified calendar and the given time zone.

Example

The example results of the operator TIME_BETWEEN(DateTime1, DateTime2, Calendar, timeZone)


Tip 2023-01-02T06:00:00Z	Tip 2023-01-02T20:00:00Z	Tip Workweek	Tip UTC	Tip 8 * 60 * 60 * 1000
Tip 2023-01-02T10:00:00Z	Tip 2023-01-02T12:00:00Z	Tip Workweek	Tip UTC	Tip 2 * 60 * 60 * 1000
Tip 2023-01-02T14:00:00Z	Tip 2023-01-04T18:00:00Z	Tip Workweek	Tip UTC	Tip 2 * 60 * 60 * 1000
Tip 2023-01-06T14:00:00Z	Tip 2023-01-09T14:00:00Z	Tip Workweek	Tip UTC	Tip 8 * 60 * 60 * 1000
Tip 2023-01-09T10:00:00Z	Tip 2023-01-06T10:00:00Z	Tip Workweek	Tip UTC	Tip -8 * 60 * 60 * 1000

WORKDAYS_BETWEEN

The operator returns a number of workdays between two dates with reference to work time intervals defined in a calendar and a time zone (default is UTC). Each day with any work time interval is considered as workday.

Example 132.

The example is based on operator WORKDAYS_BETWEEN(DateTime1, DateTime2, Calendar, timeZone).


Tip 2023-01-02T06:00:00Z	Tip 2023-01-02T20:00:00Z	Tip Workweek	Tip UTC	Tip 0
Tip 2023-01-02T06:00:00Z	Tip 2023-01-04T20:00:00Z	Tip Workweek	Tip UTC	Tip 2
Tip 2023-01-02T10:00:00Z	Tip 2023-01-04T12:00:00Z	Tip Workweek	Tip UTC	Tip 2
Tip 2023-01-02T14:00:00Z	Tip 2023-01-04T20:00:00Z	Tip Workweek	Tip UTC	Tip 2
Tip 2023-01-05T14:00:00Z	Tip 2023-01-09T20:00:00Z	Tip Workweek	Tip UTC	Tip 2
Tip 2023-01-05T10:00:00Z	Tip 2023-01-02T06:00:00Z	Tip Workweek	Tip UTC	Tip -3

IS_WORKING_TIME

The operator returns true if a date is in a work time interval defined in a calendar for a time zone, else false.

Example 133.