You can parse, format, and process the date and time within an expression. Dates use the ISO 8601 format in UTC.

Supported formats:

  • yyyy-MM-dd'T'HH:mm.ss[.SSS]X
  • yyyy-MM-ddX

Examples of valid dates:

  • 2021-01-01T23:59:59Z
  • 2021-01-01T23:59:59.001Z
  • 2021-01-01Z
Note:

If you input the ISO 8601 format incorrectly, the system returns null.

String Description Input Output
String addDays(String <inputDate>, int <days>)

where:

  • <inputDate> is the date in ISO 8601 format.
  • <days> is the number of days to add. Can be negative to decrement.

Adds a number of days to the date represented by the ISO 8601 string representation and returns the new date in the same ISO 8601 format. Returns null if inputDate is null, empty, blank, not a valid ISO 8601 format, or has an invalid date range or values.
  1. #datetime.addDays('2021-01-31T01:01:01Z', 1)
  2. #datetime.addDays('2021-03-01Z', -1)
  1. 2021-02-01T01:01:01Z
  2. 2021-02-28T00:00:00Z
String addMonths(String <inputDate>, int <months>)

where:

  • <inputDate> is the date in ISO 8601 format.
  • <months> is the number of months to add. Can be negative to decrement.

Adds a number of months to the date represented by the ISO 8601 string representation and returns the new Date in the same ISO 8601 format. Returns null if inputDate is null, empty, blank, not a valid ISO 8601 format, or has an invalid date range or values.
  1. #datetime.addMonths('2020-12-31T01:01:01.001Z', 2)
  2. #datetime.addMonths('2021-02-28T01:01:01Z', -1)
  1. 2021-02-28T01:01:01.001Z
  2. 2021-01-28T01:01:01Z
String addYears(String <inputDate>, int <years>)

where:

  • <inputDate> is the date in ISO 8601 format.
  • <years> is the number of years to add. Can be negative to decrement.

Adds a number of years to the date represented by the ISO 8601 string representation and returns the new Date in the same ISO 8601 format. Returns null if inputDate is null, empty, blank, not a valid ISO 8601 format, or has invalid date range or values.

 #datetime.addYears('2021-01-31T01:01:01Z', 1) 2022-01-31T01:01:01Z
String addHours(String <inputDate>, int <hours>)

where:

  • <inputDate> is the date in ISO 8601 format.
  • <hours> is the number of hours to add. Can be negative to decrement.

Adds a number of hours to the date represented by the ISO 8601 string representation and returns the new date in the same ISO 8601 format. Returns null if inputDate is null, empty, blank, not a valid ISO 8601 format, or has an invalid date range or values.

 #datetime.addHours('2020-12-31T23:59:59.001Z', 3) 2021-01-01T02:59:59.001Z
String addMinutes(String <inputDate>, int <minutes>)

where:

  • <inputDate> is the date in ISO 8601 format.
  • <minutes> is the number of minutes to add. Can be negative to decrement.

Adds a number of minutes to the date represented by the ISO 8601 string representation and returns the new date in the same ISO 8601 format. Returns null if inputDate is null, empty, blank, not a valid ISO 8601 format, or has an invalid date range or values.

 #datetime.addMinutes('2021-01-31T23:59:59Z', 10) 2021-02-01T00:09:59Z
String addSeconds(String <inputDate>, int <seconds>)

where:

  • <inputDate> is the date in ISO 8601 format.
  • <seconds> is the number of seconds to add. Can be negative to decrement.

Adds a number of seconds to the date represented by the ISO 8601 string representation and returns the new date in the same ISO 8601 format. Returns null if inputDate is null, empty, blank, not a valid ISO 8601 format or has invalid date range or values.

 #datetime.addSeconds('2021-02-28Z', 1) 2021-02-28T00:00:01Z
int getDayOfMonth(String <inputDate>)

where <inputDate> is the date in ISO 8601 format.

Returns day-of-month, a value from 1 to 31 for valid input or -1 if inputDate is null, empty, blank, not a valid ISO 8601 format, or has an invalid date range or values.

 #datetime.getDayOfMonth('2021-01-31T23:59:59Z') 31
int getMonth(String <inputDate>)

where <inputDate> is the date in ISO 8601 format.

Returns the month from 1 to 12 for valid input or -1 if inputDate is null, empty, blank, not a valid ISO 8601 format, or has an invalid date range or values.

 #datetime.getMonth('2021-02-28Z') 2
int getYear(String <inputDate>)

where <inputDate> is the date in ISO 8601 format.

Returns value for the year for valid input or -1 if inputDate is null, empty, blank, not a valid ISO 8601 format, or has an invalid date range or values.

 #datetime.getYear('2021-01-31T23:59:59Z') 2021
int getHour(String <inputDate>)

where <inputDate> is the date in ISO 8601 format.

Returns the hour of the day as a value between 0 and 23 for valid input or -1 if inputDate is null, empty, blank, not a valid ISO 8601 format, or has an invalid date range or values.

 #datetime.getHour('2021-01-31T23:59:59Z') 23
int getMinute(String <inputDate>)

where <inputDate> is the date in ISO 8601 format.

Returns the minute of the hour as a value between 0 to 59 for valid input or -1 if inputDate is null, empty, blank, not a valid ISO 8601 format, or has an invalid date range or values.

 #datetime.getMinute('2021-01-31T23:59:59Z') 59
int getSecond(String <inputDate>)

where <inputDate> is the date is ISO 8601 format.

Returns the second of the minute as a value between 0 to 59 for valid input or -1 if inputDate is null, empty, blank, not a valid ISO 8601 format, or has an invalid date range or values.

 #datetime.getSecond('2020-12-30T23:59:59.001Z') 59
String now()

Obtains the current date-time in ISO 8601 format.

 #datetime.now() <Current date and time in ISO 8601 format>
String toDateTime(int <year>, int <month>, int <dayOfMonth>, int <hour>, int <minute>, int <second>)

where:

  • <year> is the year to represent
  • <month> is the month-of-year to represent, from 1 (January) to 12 (December)
  • <dayOfMonth> is the day-of-month to represent, from 1 to 31
  • <hour> is the hour-of-day to represent, from 0 to 23
  • <minute> is the minute-of-hour to represent, from 0 to 59
  • <second> is the second-of-minute to represent, from 0 to 59

Obtains the date and time from the provided year, month, day, hour, minute and second and returns valid date and time in ISO 8601 format if the input is valid, or else returns null if value for any field is incorrect or out of range, such as day-of-month being invalid for the provided month or year.

 #datetime.toDateTime(2021, 1, 31, 10, 15, 0) 2021-01-31T10:15:00Z
String toDate(String <inputDate>)

where <inputDate> is the date in ISO 8601 format.

Transforms the date and time in ISO 8601 format to a date in the same format. Returns null if inputDate is null, empty, blank, not a valid ISO 8601 format, or has an invalid date range or values.

 #datetime.toDate('2021-02-28Z') 2021-02-28Z
String toTime(String <inputDate>)

where <inputDate> is the date in ISO 8601 format.

Transforms the date and time in ISO 8601 format to a time in the same format. Returns null if inputDate is null, empty, blank, not a valid ISO 8601 format, or has an invalid date range or values.

 #datetime.toTime('2021-01-31T23:59:59Z') 23:59:59Z
String format(String <inputDate>, String <pattern>)

where:

  • <inputDate> is the date in ISO 8601 format
  • <pattern> is a valid pattern supported by Java 8 DateTimeFormatter.

Transforms the date and time in ISO 8601 format to the date and time in the specified format. Returns null if the input dateTime or format is not valid. For more information, see the available formats in the Reference section. Returns null if inputDate is null, empty, blank, not a valid ISO 8601 format, has invalid date range or values, or if pattern is null or invalid.
  1. #datetime.format('2021-01-01T09:15:00Z', 'EEEE, dd MMMM; h:mm a')
  2. #datetime.format('2021-02-28Z', "QQQQ 'of year' yyyy")
  1. Friday, 01 January; 9:15 AM
  2. 1st quarter of year 2021
int compare(String <inputDateTime1>, String <inputDateTime2>)

where:

  • <inputDateTime1> is the primary date-time in ISO 8601 format to compare with
  • <inputDateTime2> is the other date-time in ISO 8601 format to compare to
Note:

Both values are treated as null if null, empty, blank, or not a valid ISO 8601 format.

Compares this date and time to another date and time, including the chronology. Returns 0 if they are the same, a negative number if the former date is earlier, and a positive number if the former date is later.
  1. #datetime.compare('2021-01-01T00:00:00Z', '2021-01-01T00:00:00Z')
  2. #datetime.compare('2021-01-01T00:00:01Z', '2021-01-01T00:00:00Z')
  1. 0
  2. 1
Number daysBetween(String <inputDateTime1>, String <inputDateTime2>, Number <defaultIfNotDate>)

where:

  • <inputDateTime1> is the primary date-time in ISO-8601 format to compare with
  • <inputDateTime2> is the other date-time in ISO-8601 format to compare to
  • <defaultIfNotDate> is the default value to return if either of the input date-time are null, empty, blank or not a valid ISO 8601 format
Note:

<inputDateTime1> and <inputDateTime2> are treated as null if null, empty, blank, or not a valid ISO 8601 format.

Calculates the number of days between input dates. The result is negative if <inputDateTime2> is before <inputDateTime1>. If either of the input date-time are null, empty, blank or not a valid ISO 8601 format, the value provided for <defaultIfNotDate> is returned.
  1. #datetime.daysBetween('2021-01-01T00:00:00Z', '2021-01-01T08:45:00Z', -1)
  2. #datetime.daysBetween('2021-01-01T00:00:01Z', '2021-01-03T10:30:00Z', -1)
  3. #datetime.daysBetween('2021-01-03T00:00:01Z', '2021-01-01T10:30:00Z', -1)
  1. 0
  2. 2
  3. -2
Number weeksBetween(String <inputDateTime1>, String <inputDateTime2>, Number <defaultIfNotDate>)

where:

  • <inputDateTime1> is the primary date-time in ISO-8601 format to compare with
  • <inputDateTime2> is the other date-time in ISO-8601 format to compare to
  • <defaultIfNotDate> is the default value to return if either of the input date-time are null, empty, blank, or not a valid ISO 8601 format
Note:

<inputDateTime1> and <inputDateTime2> are treated as null if null, empty, blank, or not a valid ISO 8601 format.

Calculates the number of weeks between input dates. The result is negative if <inputDateTime2> is before <inputDateTime1>. If either of the input date-time are null, empty, blank or not a valid ISO 8601 format, the value provided for <defaultIfNotDate> is returned.
  1. #datetime.weeksBetween('2021-01-01T00:00:00Z', '2021-01-01T08:45:00Z', -1)
  2. #datetime.weeksBetween('2021-01-01T00:00:01Z', '2021-01-15T10:30:00Z', -1)
  3. #datetime.weeksBetween('2021-01-15T00:00:01Z', '2021-01-01T10:30:00Z', -1)
  1. 0
  2. 2
  3. -2
Number monthsBetween(String <inputDateTime1>, String <inputDateTime2>, Number <defaultIfNotDate>)

where:

  • <inputDateTime1> is the primary date-time in ISO-8601 format to compare with
  • <inputDateTime2> is the other date-time in ISO-8601 format to compare to
  • <defaultIfNotDate> is the default value to return if either of the input date-time are null, empty, blank, or not a valid ISO 8601 format
Note:

<inputDateTime1> and <inputDateTime2> are treated as null if null, empty, blank, or not a valid ISO 8601 format.

Calculates the number of months between input dates. The result is negative if <inputDateTime2> is before <inputDateTime1>. If either of the input date-time are null, empty, blank or not a valid ISO 8601 format, the value provided for <defaultIfNotDate> is returned.
  1. #datetime.monthsBetween('2021-01-01T00:00:00Z', '2021-01-01T08:45:00Z', -1)
  2. #datetime.monthsBetween('2021-01-01T00:00:01Z', '2021-02-01T10:30:00Z', -1)
  3. #datetime.monthsBetween('2021-02-01T00:00:01Z', '2021-03-01T10:30:00Z', -1)
  1. 0
  2. 1
  3. 1
Number yearsBetween(String <inputDateTime1>, String <inputDateTime2>, Number <defaultIfNotDate>)

where:

  • <inputDateTime1> is the primary date-time in ISO-8601 format to compare with
  • <inputDateTime2> is the other date-time in ISO-8601 format to compare to
  • <defaultIfNotDate> is the default value to return if either of the input date-time are null, empty, blank, or not a valid ISO 8601 format
Note:

<inputDateTime1> and <inputDateTime2> are treated as null if null, empty, blank, or not a valid ISO 8601 format.

Calculates the number of years between input dates. The result is negative if <inputDateTime2> is before <inputDateTime1>. If either of the input date-time are null, empty, blank or not a valid ISO 8601 format, the value provided for <defaultIfNotDate> is returned.
  1. #datetime.yearsBetween('2021-01-01T00:00:00Z', '2021-01-01T08:45:00Z', -1)
  2. #datetime.yearsBetween('2021-01-01T00:00:01Z', '2022-01-01T10:30:00Z', -1)
  3. #datetime.yearsBetween('2022-01-01T00:00:01Z', '2021-01-01T10:30:00Z', -1)
  1. 0
  2. 1
  3. -1
String periodBetween(String <inputDateTime1>, String <inputDateTime2>, String <defaultIfNotDate>)

where:

  • <inputDateTime1> is the primary date-time in ISO-8601 format to compare with. The value is inclusive.
  • <inputDateTime2> is the other date-time in ISO-8601 format to compare to. The value is exclusive.
  • <defaultIfNotDate> is the default value to return if either of the input date-time are null, empty, blank, or not a valid ISO 8601 format
Note:

<inputDateTime1> and <inputDateTime2> are treated as null if null, empty, blank, or not a valid ISO 8601 format.

Calculates the period between input dates represented as amount of time in years, months, and days using ISO-8601 period format P[nY][nM][nD].

The letter P starts the period, [n] is an integer representing the number of years, months, and days, represented by Y, M, and D, respectively.

A zero period is represented as zero days, or P0D. The result is negative if <inputDateTime2> is before <inputDateTime1>. If either of the input date-time is null, empty, blank or not a valid ISO 8601 format, value provided for <defaultIfNotDate> is returned.

The period is calculated by removing complete months, then calculating the remaining number of days, adjusting to ensure that both have the same sign. The number of months is then split into years and months based on a 12 month year.
  1. #datetime.periodBetween('2021-01-01T00:00:00Z', '2021-01-01T00:00:00Z', -1)
  2. #datetime.periodBetween('2021-01-01Z', '2022-02-11Z', -1)
  1. P0D
  2. P1Y1M10D
String toUnixTimestamp(String <inputDateTime>)

where <inputDateTime> is date-time in ISO 8601 format.

Note:

<inputDateTime> is treated as null if null, empty, blank, or not a valid ISO 8601 format.

Transforms the date-time in ISO-8601 format to the number of seconds from the epoch of 1970-01-01T00:00:00Z. This returns null if <inputDateTime> is null, empty, blank, or not a valid ISO 8601 format.
  1. #datetime.toUnixTimestamp('2020-12-31Z')
  2. #datetime.toUnixTimestamp('2020-12-31T23:59:59Z')
  3. #datetime.toUnixTimestamp('2020-12-31T23:59:59.001Z')
  1. 1609372800
  2. 1609459199
  3. 1609459199
String fromUnixTimestamp(Number <epochSeconds>)

where <epochSeconds> is the number of seconds from the epoch of 1970-01-01T00:00:00Z.

Builds date-time in ISO-8601 format using the number of seconds from the epoch of 1970-01-01T00:00:00Z. This returns null if <epochSeconds> is null.

 #datetime.fromUnixTimestamp(1609459199) 2020-12-31T23:59:59Z
String parse(String <inputDateTime>, String <format>, Object <options>)

where:

  • <inputDateTime> is the date with or without time to parse in a format other than ISO-8601
  • <format> is the custom format supported by Java DateTimeFormatter used for the specified <inputDateTime>
  • <options> is an optional Json object with default values for allowed date-time fields which cannot be obtained from the <inputDateTime> format. Supported fields are zoneid - if <inputDateTime> doesn't contain any zone information, users can configure the zoneid to be used in the input options Json, or else UTC will be used.
Note:

<inputDateTime> is treated as null if null, empty, blank, or not a valid ISO 8601 format.

Parses <inputDateTime> in a format other than ISO8601 as specified by <format>, and uses any default values specified in <options> if required to transform it to a date-time in ISO8601 format. Will return null if <inputDateTime> is null, not in a valid format or cannot be transformed to ISO8601 if it lacks any required fields such as day, month, year, or if any of those fields are out of range.
Parsing date with format yyyy-MM-dd without zone information which uses UTC as default zone
#datetime.parse('2022-01-01', 'yyyy-MM-dd', null)
Parsing date with format yyyy-MM-dd without zone information but with zone defaults configured using options
#datetime.parse('2022-01-01', 'yyyy-MM-dd', {'zoneid': 'America/Vancouver'})
Parsing date with format yyyy-MM-dd z with zone information
#datetime.parse('2022-01-01 PST', 'yyyy-MM-dd z', null)
Parsing date with format dd/MM/yyyy HH:mm:ss without zone information which uses UTC as default zone
#datetime.parse('03/12/2021 09:30:45', 'dd/MM/yyyy HH:mm:ss', null)
  1. 2022-01-01T00:00:00Z
  2. 2022-01-01T08:00:00Z
  3. 2022-01-01T08:00:00Z
  4. 2021-12-03T09:30:45Z