PingOne

Date and time library

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

Examples of valid dates:

  • 2023-01-01T23:59:59Z

  • 2023-01-01T23:59:59.123Z

  • 2023-01-01T23:59:59.123456Z

  • 2023-01-01T23:59:59+800

Default output formats are in UTC:

  • 2023-01-01T23:59:59.001Z

  • 2023-01-01Z

  • 23:59:59Z

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

This library accepts DateTime with millisecond precision greater than 3, but the output always truncates to millisecond precision of 3.

Additional input formats not documented above are not officially supported and subject to change without notice.
String Description Input Output

String addDays(String <inputDate>, int <days>)

where:

  • <inputDate> is the date in a supported 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 a supported ISO 8601 string representation and returns the new date in the default ISO 8601 output format. Returns null if inputDate is null, empty, blank, not a supported 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:01.000Z

  2. 2021-02-28T00:00:00.000Z

String addMonths(String <inputDate>, int <months>)

where:

  • <inputDate> is the date in a supported 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 a supported ISO 8601 string representation and returns the new date in the default ISO 8601 output format. Returns null if inputDate is null, empty, blank, not a supported 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:01.000Z

String addYears(String <inputDate>, int <years>)

where:

  • <inputDate> is the date in a supported 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 a supported ISO 8601 string representation and returns the new date in the default ISO 8601 output format. Returns null if inputDate is null, empty, blank, not a supported ISO 8601 format, or has invalid date range or values.

#datetime.addYears('2021-01-31T01:01:01Z', 1)

2022-01-31T01:01:01.000Z

String addHours(String <inputDate>, int <hours>)

where:

  • <inputDate> is the date in a supported 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 a supported ISO 8601 string representation and returns the new date in the default ISO 8601 output format. Returns null if inputDate is null, empty, blank, not a supported 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 a supported 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 a supported ISO 8601 string representation and returns the new date in the default ISO 8601 output format. Returns null if inputDate is null, empty, blank, not a supported ISO 8601 format, or has an invalid date range or values.

#datetime.addMinutes('2021-01-31T23:59:59Z', 10)

2021-02-01T00:09:59.000Z

String addSeconds(String <inputDate>, int <seconds>)

where:

  • <inputDate> is the date in a supported 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 a supported ISO 8601 string representation and returns the new date in the default ISO 8601 output format. Returns null if inputDate is null, empty, blank, not a supported ISO 8601 format or has invalid date range or values.

#datetime.addSeconds('2021-02-28Z', 1)

2021-02-28T00:00:01.000Z

int getDayOfMonth(String <inputDate>)

where <inputDate> is the date in a supported 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 supported 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 a supported ISO 8601 format.

Returns the month from 1 to 12 for valid input or -1 if inputDate is null, empty, blank, not a supported 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 a supported ISO 8601 format.

Returns value for the year for valid input or -1 if inputDate is null, empty, blank, not a supported 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 a supported 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 supported 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 a supported 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 supported 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 supported 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 default ISO 8601 output format.

#datetime.now()

<Current date and time in default 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 default ISO 8601 output format.

Returns null if the 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:00.000Z

String toDate(String <inputDate>)

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

Transforms the date and time in a supported ISO 8601 format to a UTC date in the format yyyy-MM-ddX. Returns null if inputDate is null, empty, blank, not a supported 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 a supported ISO 8601 format.

Transforms the date and time in a supported ISO 8601 format to a UTC time in the format HH:mm:ss[.SSS]X. Returns null if inputDate is null, empty, blank, not a supported 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 a supported ISO 8601 format.

  • <pattern> is a valid pattern supported by Java 8 DateTimeFormatter.

Transforms the date and time in a supported 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 supported 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 a supported ISO 8601 format to compare with

  • <inputDateTime2> is the other date-time in a supported ISO 8601 format to compare to

Both values are treated as null if null, empty, blank, or not a supported 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 a supported ISO 8601 format to compare with

  • <inputDateTime2> is the other date-time in a supported 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 supported ISO 8601 format

<inputDateTime1> and <inputDateTime2> are treated as null if null, empty, blank, or not a supported 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 supported 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 a supported ISO 8601 format to compare with

  • <inputDateTime2> is the other date-time in a supported 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 supported ISO 8601 format

<inputDateTime1> and <inputDateTime2> are treated as null if null, empty, blank, or not a supported 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 supported 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 a supported ISO 8601 format to compare with

  • <inputDateTime2> is the other date-time in a supported 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 supported ISO 8601 format

<inputDateTime1> and <inputDateTime2> are treated as null if null, empty, blank, or not a supported 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 supported 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 a supported ISO 8601 format to compare with

  • <inputDateTime2> is the other date-time in a supported 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 supported ISO 8601 format

<inputDateTime1> and <inputDateTime2> are treated as null if null, empty, blank, or not a supported 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 supported 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 a supported ISO 8601 format to compare with. The value is inclusive.

  • <inputDateTime2> is the other date-time in a supported 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 supported ISO 8601 format.

<inputDateTime1> and <inputDateTime2> are treated as null if null, empty, blank, or not a supported 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 supported ISO 8601 format, the 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 the date-time in a supported ISO 8601 format.

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

Transforms the date-time in a supported 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 supported 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 using the number of seconds from the epoch of 1970-01-01T00:00:00Z to a UTC date-time in default ISO 8601 format. Returns null if <epochSeconds> is null.

#datetime.fromUnixTimestamp(1609459199)

2020-12-31T23:59:59.000Z

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.

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

Parses <inputDateTime> in a format other than ISO 8601 as specified by <format>, and uses any default values specified in <options> if required to transform it to a date-time in ISO 8601 format.

Will return null if <inputDateTime>:

  • Is null

  • Is not in a valid format

  • Cannot be transformed to ISO 8601 if it lacks any required fields such as day, month, or year

  • 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:00.000Z

  2. 2022-01-01T08:00:00.000Z

  3. 2022-01-01T08:00:00.000Z

  4. 2021-12-03T09:30:45.000Z

String toDateTimeInTimezone(String <inputDateTime>, String <timezone>, String <pattern>)

where:

  • <inputDateTime> is the date in a supported ISO 8601 format.

  • <timezone> is a valid zone ID supported by Java 8. Parsing matches the zone ID as follows:

    1. If the zone ID equals Z, the result is UTC.

    2. If the zone ID consists of a single letter, the zone ID is invalid.

    3. If the zone ID equals GMT, UTC, or UT, then the result is a timezone with the same ID and rules equivalent to UTC.

Zone IDs must match regular expression characters. If the zone ID is not in the Java 8 configured set of IDs, it is invalid. The detailed format of the region ID depends on the group supplying the data. The default set of data is supplied by the IANA Time Zone Database (TZDB).

IANA TZDB has region IDs of the form <area>/<city>, such as Europe/Paris or America/New_York. This is compatible with most IDs from Time Zone. * <pattern> is a pattern supported by Java 8 DateTimeFormatter. For available formats, see the References section.

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

Transforms the date-time in a supported ISO 8601 format to date-time in the specified timezone in the required format if specified, or the default format yyyy-MM-dd’T’HH:mm:ss[.SSS]Z.

Will return null if:

  • <inputDateTime> is null, empty, or blank

  • <inputDateTime> is not a supported ISO 8601 format, or has invalid dates or values

  • <timezone> or <pattern> are null or invalid
Change time zone to America/Vancouver with default pattern

#datetime.toDateTimeInTimezone('2023-01-01T04:30:30.000Z', 'America/Vancouver', null)

Change time zone to +100 with default pattern

#datetime.toDateTimeInTimezone('2023-01-01T04:30:30Z', '+0100', null)

Change time zone to America/Vancouver with custom pattern

#datetime.toDateTimeInTimezone('2023-01-01T04:30:30.123Z', 'America/Vancouver', 'dd-MM-YYYY hh:mm a')

  1. 2022-12-31T20:30:30-0800

  2. 2023-01-01T05:30:30.000+0100

  3. 31-12-2022 08:30 PM