Documentation Journey Optimizer Journey Optimizer Guide

Date Time Functions

Last update: October 29, 2025

Topics:
Personalization

CREATED FOR:

Experienced
Developer

Date and time functions are used to perform date and time operations on values within Journey Optimizer.

Add Days

The addDays function adjusts a given date by a specified number of days, using positive values to increment and negative values to decrement.

Syntax

{%= addDays(date, number) %}

Example

Input: {%= addDays(stringToDate("2024-11-01T17:19:51Z"),10) %}
Output: 2024-11-11T17:19:51Z

Add Hours

The addHours function adjusts a given date by a specified number of hours, using positive values to increment and negative values to decrement.

Syntax

{%= addHours(date, number) %}

Example

Input: {%= addHours(stringToDate("2024-11-01T17:19:51Z"),1) %}
Output: 2024-11-01T18:19:51Z

Add Minutes

The addMinutes function adjusts a given date by a specified number of minutes, using positive values to increment and negative values to decrement.

Syntax

{%= addMinutes(date, number) %}

Example

Input: {%= addMinutes(stringToDate("2024-11-01T17:59:51Z"),10) %}
Output: 2024-11-01T18:09:51Z

Add Months

The addMonths function adjusts a given date by a specified number of months, using positive values to increment and negative values to decrement.

Syntax

{%= addMonths(date, number) %}

Example

Input: {%= addMonths(stringToDate("2024-11-01T17:19:51Z"),2) %}
Output: 2025-01-01T17:19:51Z

Add Seconds

The addSeconds function adjusts a given date by a specified number of seconds, using positive values to increment and negative values to decrement.

Syntax

{%= addSeconds(date, number) %}

Example

Input: {%= addSeconds(stringToDate("2024-11-01T17:19:51Z"),10) %}
Output: 2024-11-01T17:20:01Z

Add Years

The addYears function adjusts a given date by a specified number of years, using positive values to increment and negative values to decrement.

Syntax

{%= addYears(date, number) %}

Example

Input: {%= addYears(stringToDate("2024-11-01T17:19:51Z"),2) %}
Output: 2026-11-01T17:19:51Z

Age

The age function is used to retrieve the age from a given date.

Syntax

 {%= age(datetime) %}

Age In Days

The ageInDays function calculates the age of a given date in days, i.e. the number of days elapsed between the given date and the current date, negative for future dates and positive for past dates.

Syntax

{%= ageInDays(date) %}

Example

currentDate = 2025-01-07T12:17:10.720122+05:30 (Asia/Kolkata)

Input: {%= ageInDays(stringToDate("2025-01-01T17:19:51Z"))%}
Output: 5

Age In Months

The ageInMonths function calculates the age of a given date in months, i.e. the number of months elapsed between the given date and the current date , negative for future dates and positive for past dates.

Syntax

{%= ageInMonths(date) %}

Example

currentDate = 2025-01-07T12:22:46.993748+05:30(Asia/Kolkata)

Input: {%=ageInMonths(stringToDate("2024-01-01T00:00:00Z"))%}
Output: 12

Compare Dates

The compareDates function compares the first input date with the other. Returns 0 if date1 is equal to date2, -1 if date1 comes before date2 and 1 if date1 comes after date2.

Syntax

{%= compareDates(date1, date2) %}

Example

Input: {%=compareDates(stringToDate("2024-12-02T00:00:00Z"), stringToDate("2024-12-03T00:00:00Z"))%}
Output: -1

Convert ZonedDateTime

The convertZonedDateTime function converts a date-time to a given timezone.

Syntax

{%= convertZonedDateTime(dateTime, timezone) %}

Example

Input: {%=convertZonedDateTime(stringToDate("2019-02-19T08:09:00Z"), "Asia/Tehran")%}
Output: 2019-02-19T11:39+03:30[Asia/Tehran]

Current time in milliseconds

The currentTimeInMillis function is used to retrieve current time in epoch milliseconds.

Syntax

{%= currentTimeInMillis() %}

Date difference

The dateDiff function is used to retrieve the difference between two dates in number of days.

Syntax

{%= dateDiff(datetime,datetime) %}

Day of month

The dayOfMonth returns the number representing the day of the month.

Syntax

{%= dayOfMonth(datetime) %}

Example

Input: {%= dayOfMonth(stringToDate("2024-11-05T17:19:51Z")) %}
Output: 5

Day of week

The dayOfWeek function is used to retrieve the day of week.

Syntax

{%= dayOfWeek(datetime) %}

Day of year

The dayOfYear function is used to retrieve the day of year.

Syntax

{%= dayOfYear(datetime) %}

Diff In Seconds

The diffInSeconds function returns the difference between two dates in terms of seconds.

Syntax

{%= diffInSeconds(endDate, startDate) %}

Example

Input: {%=diffInSeconds(stringToDate("2024-11-01T17:19:51Z"), stringToDate("2024-11-01T17:19:01Z"))%}
Output: 50

Extract Hours

The extractHours function extracts the hour component from a given timestamp.

Syntax

{%= extractHours(date) %}

Example

Input: {%= extractHours(stringToDate("2024-11-01T17:19:51Z"))%}
Output: 17

Extract Minutes

The extractMinutes function extracts the minute component from a given timestamp.

Syntax

{%= extractMinutes(date) %}

Example

Input: {%= extractMinutes(stringToDate("2024-11-01T17:19:51Z"))%}
Output: 19

Extract Months

The extractMonth function extracts the month component from a given timestamp.

Syntax

{%= extractMonths(date) %}

Example

Input: {%=extractMonth(stringToDate("2024-11-01T17:19:51Z"))%}
Output: 11

Extract Seconds

The extractSeconds function extracts the second component from a given timestamp.

Syntax

{%= extractSeconds(date) %}

Example

Input: {%=extractSeconds(stringToDate("2024-11-01T17:19:51Z"))%}
Output: 51

Format date

The formatDate function is used to format a date time value. The format should be a valid Java DateTimeFormat pattern.

Syntax

{%= formatDate(datetime, format) %}

Where the first string is the date attribute and the second value is how you would like the date to be converted and displayed.

NOTE

If a date pattern is invalid the date will fallback to ISO standard format.

You can use Java date formatting functions as summarized in Oracle documentation

Example

The following operation will return the date in the following format: MM/DD/YY.

{%= formatDate(profile.timeSeriesEvents._mobile.hotelBookingDetails.bookingDate, "MM/dd/YY") %}

Pattern characters

Some pattern letters may look similar but represent different concepts.

Pattern

Meaning

Example (for 2023-12-31T10:15:30Z)

y

Calendar year (standard year)

2023

Y

Week-based year (ISO 8601). May differ at year boundaries.

2024 (since Dec 31, 2023 falls in the first week of 2024)

M

Month-of-year (1–12 or text like Jan, January)

12 or Dec

m

Minute-of-hour (0–59)

15

d

Day-of-month (1–31)

31

D

Day-of-year (1–366)

365

Format date with locale support

The formatDate function can be used to format a date time value into its corresponding language sensitive representation, i.e in a desired locale. The format should be a valid Java DateTimeFormat pattern.

Syntax

{%= formatDate(datetime, format, locale) %}

Where the first string is the date attribute, second value is how you would like the date to be converted and displayed and the third value represents the locale in string format.

NOTE

If a date pattern is invalid the date will fallback to ISO standard format.

You can use Java date formatting functions as summarized in Oracle documentation.

You can use formatting and valid locales as summarized in Oracle documentation and Supported locales.

Example

The following operation will return the date in the following format: MM/dd/YY and locale FRANCE.

{%= formatDate(profile.timeSeriesEvents._mobile.hotelBookingDetails.bookingDate, "MM/dd/YY", "fr_FR") %}

Get CurrentZonedDateTime

The getCurrentZonedDateTime function returns the current date and time with time zone information.

Syntax

{%= getCurrentZonedDateTime() %}

Example

Input: {%= getCurrentZonedDateTime() %}
Output: 2024-12-06T17:22:02.281067+05:30[Asia/Kolkata]

Hours Difference

The diffInHours function returns the difference between two dates in terms of hours.

Syntax

{%= diffInHours(endDate, startDate) %}

Example

Input: {%= diffInHours(stringToDate("2024-11-01T17:19:51Z"), stringToDate("2024-11-01T07:19:51Z"))%}
Output: 10

Minutes Difference

The diffInMinutes function is used to return the difference between two dates in terms of minutes.

Syntax

{%= diffInMinutes(endDate, startDate) %}

Example

Input: {%= diffInMinutes(stringToDate("2024-11-01T17:19:51Z"), stringToDate("2024-11-01T16:19:51Z"))%}
Output: 60

Months Difference

The diffInMonths function returns the difference between two dates in terms of months.

Syntax

{%= diffInMonths(endDate, startDate) %}

Example

Input: {%=diffInMonths(stringToDate("2024-11-01T17:19:51Z"), stringToDate("2024-08-01T17:19:51Z"))%}
Output: 3

Set days

The setDays function is used to set the day of the month for the given date-time.

Syntax

{%= setDays(datetime, day) %}

Set hours

The setHours function is used to set the hour of the date-time.

Syntax

{%= setHours(datetime, hour) %}

To Date Time

The ToDateTime function converts string to date. It returns the epoch date as output for invalid input.

Syntax

{%= toDateTime(string, string) %}

Example

Input: {%=toDateTime("2024-11-01T17:19:51Z")%}
Output: 2024-11-01T17:19:51Z

To UTC

The toUTC function is used to convert a datetime to UTC.

Syntax

{%= toUTC(datetime) %}

Truncate to Start Of Day

The truncateToStartOfDay function is used to modify a given date-time by setting it to the start of the day with the time set to 00:00.

Syntax

{%= truncateToStartOfDay(date) %}

Example

Input: {%= truncateToStartOfDay(stringToDate("2024-11-01T17:19:51Z")) %}
Output: 2024-11-01T00:00Z

truncateToStartOfQuarter

The truncateToStartOfQuarter function is used to truncate a date-time to the first day of its quarter (e.g., Jan 1, Apr 1, Jul 1, Oct 1) at 00:00.

Syntax

{%= truncateToStartOfQuarter(dateTime) %}

Example

Input: {%=truncateToStartOfQuarter(stringToDate("2024-11-01T17:19:51Z"))%}
Output: 2024-10-01T00:00Z

truncateToStartOfWeek

The truncateToStartOfWeek function modifies a given date-time by setting it to the start of the week(Monday at 00:00).

Syntax

{%= truncateToStartOfWeek(dateTime) %}

Example

Input: {%= truncateToStartOfWeek(stringToDate("2024-11-19T17:19:51Z"))%} // tuesday
Output: 2024-11-18T00:00Z // monday

truncateToStartOfYear

The truncateToStartOfYear function is used to modify a given date-time by truncating it to the first day of the year (January 1st) at 00:00.

Syntax

{%= truncateToStartOfYear(dateTime) %}

Example

Input: {%=truncateToStartOfYear(stringToDate("2024-11-01T17:19:51Z"))%}
Output: 2024-01-01T00:00Z

Week of year

The weekOfYear function is used to retrieve the week of the year.

Syntax

{%= weekOfYear(datetime) %}

Years Difference

The diffInYears function is used to return the difference between two dates in terms of years.

Syntax

{%= diffInYears(endDate, startDate) %}: int

Example

Input: {%=diffInYears(stringToDate("2024-11-01T17:19:51Z"), stringToDate("2019-10-01T17:19:51Z"))%}
Output: 5

recommendation-more-help