Date/Time Plugin

The plugin provides functionality to generate, modify and validate date/time.

Installation

  1. Copy the below line to dependencies section of the project build.gradle file

    Please make sure to use the same version for all VIVIDUS dependencies.
    Example 1. build.gradle
    implementation(group: 'org.vividus', name: 'vividus-plugin-datetime')

  2. If the project was imported to the IDE before adding new dependency, re-generate the configuration files for the used IDE and then refresh the project in the used IDE.

Properties

Required

There are no required properties for the plugin.

Optional

location.zone-id - Defines time zone which will be used. The default is set to a system default timezone. Time zone format

Expressions

The expression parameters marked with bold are mandatory.

generateDate

Generates the date using current date as a baseline.

 #{generateDate($period, $outputFormat)}

Properties

Property name Acceptable values Default Description

expression.generate-date.locale

2-letter language code followed by underscore _ and then 2-letter country code

en_US

The locale used for formatting of the resulting date.

For example, the date '2022-08-11' with format 'EEE, dd MMM yyyy' will be displayed as

  • 'Mon, 15 Aug 2022' for en_US locale

  • 'lun., 15 août 2022' for fr_FR locale

Let’s imagine the current date is 2020-11-23 and the time is 00:10:01. Here is a set of examples with the results and comments.

Table 1. Examples of the expressions generating dates
Expression Result Comment

#{generateDate(P)}

2020-11-23

Current date.

#{generateDate(P1DT2h)}

2020-11-24T02:10:01

Current date +1 day and +2 hours

#{generateDate(-P1D}

2020-11-22

Current date -1 day

#{generateDate(P1M)}

2020-12-23

Current date + 1 month

#{generateDate(-PT10M)}

2020-11-23T00:00:01

Current date time -10 mins

#{generateDate(P, yyyy-MM)}

2020-11

Current date with the custom output format

#{generateDate(P, MM/dd/yyyy)}

11/23/2020

Current date with a custom format

#{generateDate(P1D, yy-MM-dd)}

20-11-24

Current date +1 day with the custom output format

#{generateDate(P2D, yyyy\\,MM\\,dd)}

2020,11,25

Current date +2 day with the custom output format

#{generateDate(P3D, """yyyy,MM,dd""")}

2020,11,25

Current date +3 day with the custom output format

#{generateDate(P, yyyy-MM-dd'T'HH:mm:ssZ)}

2020-11-23T00:10:01+0300

Current date with the custom output format including time zone offset

formatDate

Formats the input date to another format. Additionally, time zone can be changed in the output result.

#{formatDate($inputDate, $outputFormat, $outputTimeZone)}

  • $inputDate - the date to be formatted, it should be presented in the ISO-8601 format.

  • $outputFormat - the output format based on the date/time format.

  • $outputTimeZone - the time zone for the output result.

Properties

Property name Acceptable values Default Description

expression.format-date.locale

2-letter language code followed by underscore _ and then 2-letter country code

en_US

The locale used for fromatting of the resulting date.

For example, the expression #{formatDate(2023-09-21T00:00:00, EEE\, dd MMM yyyy)} will result in

  • 'Thu, 21 Sep 2023' for en_US locale

  • 'jeu., 21 sept. 2023' for fr_FR locale
Table 2. Examples of the expressions formatting dates
Expression Result

#{formatDate(2017-01-13T09:00:42.862Z, yyyy-MM-dd'T'HH:mm:ss.SSS)}

2017-01-13T09:00:42.862

#{formatDate(2017-01-13T09:00:42.862-05:00, yyyy-MM-dd'T'HH:mm:ss.SSS)}

2017-01-13T09:00:42.862

#{formatDate(2017-01-13T09:00:42.862-0500, yyyy-MM-dd'T'HH:mm:ss.SSS)}

Throw exception

#{formatDate(2017-01-13T09:00:42.862, yyyy-MM-dd'T'HH:mm:ss)}

2017-01-13T09:00:42

#{formatDate(2017-01-13T09:00:42.862Z, yyyy-MM-dd'T'HH:mm:ss)}

2017-01-13T09:00:42+0000

#{formatDate(2017-01-13T09:00:42.862Z, yyyy-MM-dd'T'HH:mm:ssZ)}

2017-01-13T09:00:42-05:00

#{formatDate(2017-01-13T09:00:42.862Z, yyyy-MM-dd)}

2017-01-13

#{formatDate(2017-01-13T09:00:42.862Z, yyyy\,MM\,dd)}

2017,01,13

#{formatDate(2017-01-13T09:00:42.862Z, """yyyy,MM,dd""")}

2017,01,13

#{formatDate(2017-01-13T09:00:42.862Z, yyyy-MM-dd'T'HH:mm:ss.SSSZ, -05:00)}

2017-01-13T04:00:42.862-0500

#{formatDate(2017-01-13T04:00:42.862-05:00, yyyy-MM-dd'T'HH:mm:ss.SSSZ, GMT)}

2017-01-13T09:00:42.862+0000

#{formatDate(2017-01-13T09:00:42.862Z, yyyy-MM-dd'T'HH:mm:ss.SSSZ, America/New_York)}

2017-01-13T04:00:42.862-0500

#{formatDate(2017:01:13T09:00:42.862Z, yyyy-MM-dd'T'HH:mm:ss.SSS)}

Error: invalid input data

#{formatDate(2017-01-13T09:00:42.862Z, BBByyyy-MM-dd'T'HH:mm:ss.SSS)}

Error: invalid output format

#{formatDate(2017-01-13T09:00:42.862Z, yyyy-MM-dd'T'HH:mm:ss.SSS, ABCD)}

Error: invalid output timezone

formatDateTo

Formats the input date to the desired format. The format of the input date should be provided in the second parameter.

#{formatDateTo($inputDate, $inputFormat, $outputFormat)}

  • $inputDate - the date to be formatted, it can be in any format but this format should be described in the second parameter

  • $inputFormat - the input date format based on the date/time format

  • $outputFormat - the output date format based on the date/time format

Table 3. Examples of the expressions formatting dates with the custom input format
Expression Result

#{formatDateTo("2017-03-31T07:20:43.808Z", "yyyy-MM-dd'T'HH:mm:ss.SSSVV", EEE\, dd MMM yyyy HH:mm:ss ZZZZ)}

Fri, 31 Mar 2017 07:20:43 GMT

#{formatDateTo(Fri\, 31 Mar 2017 07:20:43 GMT, EEE\, dd MMM yyyy HH:mm:ss zzz, yyyy-MM-dd'T'HH:mm:ss)}

2017-03-31T07:20:43

#{formatDateTo("""Fri, 31 Mar 2017 07:20:43 GMT""", """EEE, dd MMM yyyy HH:mm:ss zzz""", yyyy-MM-dd'T'HH:mm:ss)}

2017-03-31T07:20:43

shiftDate

Shifts the given input date for a given period in any direction (+/-).

#{shiftDate($inputDate, $inputFormat, $period)}

  • $inputDate - the date to be shifted, it can be in any format but this format should be described in the second parameter

  • $inputFormat - the input date format based on the date/time format

  • $period - the period by which the date will be shifted, it should be written in ISO-8601 Durations format.

Table 4. Examples of the expressions shifting dates
Expression Result

#{shiftDate(2019-03-19 03:40:00, yyyy-MM-dd HH:mm:ss, -P1Y)}

2018-03-19 01:40:00

#{shiftDate("""2019-03-19, 03:40:00""", """yyyy-MM-dd, HH:mm:ss""", -P1Y)}

2018-03-19, 01:40:00

#{shiftDate(Wed\, 10 Apr 2019 07:20:43 GMT, EEE\, dd MMM yyyy HH:mm:ss zzz, P1MT2H)}

Fri, 10 May 2019 09:20:43 GMT

#{shiftDate("Wed\, 10 Apr\, 2019\, 07:20:43 GMT", "EEE\, dd MMM\, yyyy\, HH:mm:ss zzz", P1MT2H)}

"Fri, 10 May, 2019, 09:20:43 GMT"

diffDate

Calculates the difference between two dates with given formats and returns result in ISO-8601 format.

#{diffDate($inputDate1, $inputDate1Format, $inputDate2, $inputDate2Format, chronoUnit)}

  • $inputDate1 - the first input date, it can be in any format but this format should be described in the second parameter

  • $inputDate1Format - the first input date format based on the date/time format

  • $inputDate2 - the second input date, it can be in any format but this format should be described in the second parameter

  • $inputDate2Format - the second input date format based on the date/time format

  • chronoUnit - [optional] the date period unit based on date periods units. Calculation of the amount of time between two dates will be done in terms of this unit.

Table 5. Examples of the expressions calculating dates difference
Expression Result

#{diffDate(2019-03-19 03:40:00, yyyy-MM-dd HH:mm:ss, 2019-03-19 03:40, yyyy-MM-dd HH:mm)}

PT0S

#{diffDate("""2019-03-19, 03:40:00""", """yyyy-MM-dd, HH:mm:ss""", 2019-03-19 03:40, yyyy-MM-dd HH:mm)}

PT0S

#{diffDate("Wed 10 Apr\, 2019\, 13:20:43 GMT", "EEE dd MMM\, yyyy\, HH:mm:ss zzz", "Wed 10 Apr\, 2019\, 09:20:43 America/New_York", "EEE dd MMM\, yyyy\, HH:mm:ss zzz")}

PT0S

#{diffDate(2019-03-19 03:40:00, yyyy-MM-dd HH:mm:ss, 3020-03-19 03:39:20, yyyy-MM-dd HH:mm:ss)}

PT8774591H59M20S

#{diffDate(2019-03-19 03:40:00, yyyy-MM-dd HH:mm:ss, 2019-03-19 04:40:00, yyyy-MM-dd HH:mm:ss, minutes)}

60

#{diffDate(2019-03-19 03:40:00, yyyy-MM-dd HH:mm:ss, 2019-03-19 04:40:00, yyyy-MM-dd HH:mm:ss, hours)}

1

#{diffDate(2019-03-19 03:00:00, yyyy-MM-dd HH:mm:ss, 2019-03-19 03:50:00, yyyy-MM-dd HH:mm:ss, hours)}

0

toEpochSecond

Converts the input date to the number of seconds from the epoch of 1970-01-01T00:00:00Z.

#{toEpochSecond($inputDate)}

  • $inputDate - the date to be converted in the ISO-8601 format.

Table 6. Examples of the expressions converting the input date to the Unix epoch time in seconds
Expression Result

#{toEpochSecond(1993-04-16T00:00:00)}

734918400

#{toEpochSecond(1993-04-16T00:00:00.123)}

734918400

#{toEpochSecond(2020-12-11T18:43:05+05:30)}

1607692385

#{toEpochSecond(2020-12-11T18:43:05.987+05:30)}

1607692385

toEpochMilli

Converts the input date to the number of milliseconds from the epoch of 1970-01-01T00:00:00Z.

#{toEpochMilli($inputDate)}

  • $inputDate - the date to be converted in the ISO-8601 format.

Table 7. Examples of the expressions converting the input date to the Unix epoch time in milliseconds
Expression Result

#{toEpochMilli(1993-04-16T00:00:00)}

734918400000

#{toEpochMilli(1993-04-16T00:00:00.123)}

734918400123

#{toEpochMilli(2020-12-11T18:43:05+05:30)}

1607692385000

#{toEpochMilli(2020-12-11T18:43:05.987+05:30)}

1607692385987

fromEpochSecond

Converts the input number of seconds from the epoch of 1970-01-01T00:00:00Z to the date in the ISO-8601 format.

#{fromEpochSecond($unixEpochTimeInSeconds)}

  • $unixEpochTimeInSeconds - the Unix epoch time in seconds to be converted to the ISO-8601 format.

Table 8. Examples of the expressions converting the Unix epoch time in seconds to the input date (UTC+00:00 time zone)
Expression Result

#{fromEpochSecond(734918400)}

1993-04-16T00:00:00

#{fromEpochSecond(1.669640468E9)}

2022-11-28T13:01:08

fromEpochMilli

Converts the input number of milliseconds from the epoch of 1970-01-01T00:00:00Z to the date in the ISO-8601 format.

#{fromEpochMilli($unixEpochTimeInMilliseconds)}

  • $unixEpochTimeInMilliseconds - the Unix epoch time in milliseconds to be converted to the ISO-8601 format.

Table 9. Examples of the expressions converting the Unix epoch time in milliseconds to the input date (UTC+00:00 time zone)
Expression Result

#{fromEpochSecond(734918400987)}

1993-04-16T00:00:00.987

#{fromEpochSecond(1.669640468123E12)}

2022-11-28T13:01:08.123

Steps

Compare date and current instant

Validates the difference between the current instant and the provided date in seconds.

Then the date '$date' is $comparisonRule current for $seconds seconds

  • $date - The date in the ISO-8601 format.

  • $comparisonRule - The comparison rule.

  • $seconds - The expected number of seconds between the current instant and the provided date.

Example 2. Validate the date is less than current for 10 seconds
Then the date '2020-06-16T15:25:29.516580Z' is less than current for 10 seconds

Compare two dates

Compares two dates according to the given comparison rule.

Then the date '$date1' is $comparisonRule the date '$date2'
Example 3. Compare dates
Then the date '2021-04-20T01:02:03.004Z' is greater than the date '2021-04-20T01:02:03.003Z'
Then the date '2021-04-19' is less than the date '2021-04-20'

Compare date with custom format and current instant

Validates the difference between the current instant and the provided date in seconds using the custom date format.

Then the date '$date' in the format '$format' is $comparisonRule current for $seconds seconds

  • $date - The date to validate.

  • $format - the date/time format.

  • $comparisonRule - The comparison rule.

  • $seconds - The expected number of seconds between the current instant and the provided date.

Example 4. Validate the date is greater than current for 10 seconds
Then the date '2020-06-25T00:19:58.890007Z' in the format 'uuuu-MM-dd'T'HH:mm:ss.nnnX' is > current for 10 seconds