. Omnistudio Date and Time Functions

You are here:

Omnistudio Date and Time Functions

Functions that operate on dates and times.

Omnistudio ADDDAY Function
Returns a date and time after adding a specified number of days.
Omnistudio ADDMONTH Function
Returns a date and time after adding a specified number of months.
Omnistudio ADDYEAR Function
Returns a date and time after adding a specified number of years.
Omnistudio AGE Function
Returns the age in years for a specified birth date.
Omnistudio AGEON Function
Returns the age in years for a specified birth date on a specified date.
Omnistudio DATEDIFF Function
Returns the difference in number of days between two specified dates as an integer value.
Omnistudio DATETIMETOUNIX Function
Returns the number of milliseconds in UNIX time for a specified date and time.
Omnistudio DAY Function
Returns the day for a specified date as an integer value.
Omnistudio EOM Function
Returns the date and time of the last day of the month for a specified date.
Omnistudio FORMATDATETIME Function
Returns a date and time as a string in a specified format and time zone.
Omnistudio FORMATDATETIMEGMT Function
Returns a date and time as a string in a specified format and in the GMT time zone.
Omnistudio HOUR Function
Returns the hour for a specified time as an integer value.
Omnistudio MINUTE Function
Returns the minute for a specified time as an integer value.
Omnistudio MONTH Function
Returns the month for a specified date as an integer value.
Omnistudio NOW Function
Returns the current date and time in a specified format.
Omnistudio SECOND Function
Returns the second for a specified time as an integer value.
Omnistudio TIMEDIFF Function
Returns the difference in number of milliseconds between two specified times as an integer.
Omnistudio TODAY Function
Returns the current date.
Omnistudio UNIXTODATETIME Function
Returns the date and time for a number of seconds or milliseconds specified in UNIX time.
Omnistudio YEAR Function
Returns the year for a specified date as an integer value.

Omnistudio ADDDAY Function

Returns a date and time after adding a specified number of days.

If you specify a date and time, use the date format "YYYY-MM-DD" to preserve the input time. Use the date format "MM/DD/YYYY" to reset the time to 00:00:00.

Signature

ADDDAY(date, days)

Return Value

Datetime

Parameters

Parameter	Data Type	Necessity	Description
`date`	Datetime	Required	A date specified as a string in Day.js format. You can specify a date and time.
`days`	Integer	Required	The number of days to be added to the specified date. Use a negative number to subtract days from the date.

Add Days Example

Formula: ADDDAY("2025-01-01", 31)

Formula: ADDDAY("01/01/2025", 31)

Formula: ADDDAY("01/01/2025T12:00:00Z", 31)

Return value: "2025-02-01T00:00:00.000Z"

Add Days Example

Formula: ADDDAY("2025-01-01T12:00:00Z", 31)

Return value: "2025-02-01T12:00:00.000Z"

Subtract Days Example

Formula: ADDDAY("2025-01-01", -100)

Formula: ADDDAY("2025-01-01T00:00:00Z", -100)

Return value: "2024-09-23T00:00:00.000Z"

Omnistudio ADDMONTH Function

Returns a date and time after adding a specified number of months.

If you specify a date and time, use the date format "YYYY-MM-DD" to preserve the input time. Use the date format "MM/DD/YYYY" to reset the time to 00:00:00.

Signature

ADDMONTH(date, months)

Return Value

Datetime

Parameters

Parameter	Data Type	Necessity	Description
`date`	Datetime	Required	A date specified as a string in Day.js format. You can specify a date and time.
`months`	Integer	Required	The number of months to be added to the specified date. Use a negative number to subtract months from the date.

Add Months Example

Formula: ADDMONTH('2025-25-01', 15)

Formula: ADDMONTH("01/25/2025", 15)

Formula: ADDMONTH("01/25/2025T16:35:30Z", 15)

Return value: "2026-04-25T00:00:00.000Z"

Add Months Example

Formula: ADDMONTH("2025-01-25T16:35:30Z", 15)

Return value: "2026-04-25T16:35:30.000Z"

Subtract Months Example

Formula: ADDMONTH("01/25/2025", -15)

Formula: ADDMONTH('01/25/2025T16:35:30Z', -15)

Return value: "2023-10-25T00:00:00.000Z"

Omnistudio ADDYEAR Function

Returns a date and time after adding a specified number of years.

If you specify a date and time, use the date format "YYYY-MM-DD" to preserve the input time. Use the date format "MM/DD/YYYY" to reset the time to 00:00:00.

Signature

ADDYEAR(date, years)

Return Value

Datetime

Parameters

Parameter	Data Type	Necessity	Description
`date`	Datetime	Required	A date specified as a string in Day.js format. You can specify a date and time.
`years`	Integer	Required	The number of years to be added to the specified date. Use a negative number to subtract years from the date.

Add Years Example

Formula: ADDYEAR("2025-01-01", 10)

Formula: ADDYEAR("01/01/2025", 10)

Formula: ADDYEAR("01/01/2025T16:35:30", 10)

Return value: "2035-01-01T00:00:00.000Z"

Add Years Example

Formula: ADDYEAR("2025-01-01T16:35:30", 10)

Return value: "2035-01-01T16:35:30.000Z"

Subtract Years Example

Formula: ADDYEAR("2025-01-01", -10)

Formula: ADDYEAR("2025-01-01T00:00:00", -10)

Return value: "2015-01-01T00:00:00.000Z"

Omnistudio AGE Function

Returns the age in years for a specified birth date.

Signature

AGE(birthDate)

Return Value

Integer

Parameters

Parameter	Data Type	Necessity	Description
`birthDate`	Datetime	Required	A date specified as a string in Day.js format. You can specify a date and time.

Date String Example

Formula: AGE("02/15/2002")

Formula: AGE("2002-02-15")

Return value: 23

Date and Time String Example

Formula: AGE("2002-02-15T16:35:30")

Formula: AGE("2002-02-15T16:35:30Z")

Return value: 23

Omnistudio AGEON Function

Returns the age in years for a specified birth date on a specified date.

The function calculates an age based only on dates; it ignores times. The function returns 0 if the specified date is less than a year from or is earlier than the birthDate.

Signature

AGEON(birthDate, date)

Return Value

Integer

Parameters

Parameter	Data Type	Necessity	Description
`birthDate`	Datetime	Required	The birth date for which the age is to be calculated. Specify a date as a string in Day.js format. You can specify a date and time.
`date`	Datetime	Required	A date for which the function is to calculate an age based on the birth date. Specify a date as a string in Day.js format. You can specify a date and time.

Date and Time String Example

Formula: AGEON("02/15/2002T16:35:30Z", "2030-02-28")

Formula: AGEON("2002-02-15", "2030-02-28T16:35:30Z")

Return value: 28

JSON Object Example

Sample data:

"BirthDate": "6/25/2004T09:05:00 GMT -0500 (EDT)"
"FutureDate1": "02/28/2030",
"FutureDate2": "2030-02-28"

Formula: AGEON(%Birthdate%, %FutureDate1%)

Formula: AGEON("BirthDate%, %FutureDate2%)

Return value: 25

Omnistudio DATEDIFF Function

Returns the difference in number of days between two specified dates as an integer value.

The first date is subtracted from the second date. If the first date is greater than the second date, the function returns a negative integer.

If you include a time, the function considers it in its calculation. If you specify a time zone, the function considers it in its calculation.

Signature

DATEDIFF(firstDate, secondDate)

Return Value

Integer

Parameters

Parameter	Data Type	Necessity	Description
`firstDate`	Date	Required	A date specified as a string in Day.js format. You can specify a date and time.
`secondDate`	Date	Required	A date for which the function is to calculate the difference in number of days between the first date. Specify a date as a string in Day.js format. You can specify a date and time.

Positive Days Example

Formula: DATEDIFF("02/01/2000", "2001-02-01")

Return value: 366

Negative Days Example

Formula: DATEDIFF("2001-02-01", "02/01/2000")

Return value: -366

Date and Time Example

Formula: DATEDIFF("2025-02-04T00:00:00", "2025-03-04T00:00:00")

Return value: 28

Date and Time Example

Formula: DATEDIFF("2025-02-04T12:00:00", "2025-03-04T11:59:59")

Return value: 27

Date and Time with Time Zone Example

Formula: DATEDIFF("2025-02-04T12:00:00-0500", "2025-03-04T11:59:59+0000")

Return value: 28

JSON Object Examples

Sample data:

"Account": [
  {
    "Cases": [
      {
        "Case1": {
          "CreatedDate": "2/1/2024T16:35:30 GMT -0500 (EDT)",
          "LastUpdate": "2/8/2024T09:15:00 GMT -0500 (EDT)"
        }
      },
      {
        "Case2": {
          "CreatedDate": "2/2/2025T11:05:05 GMT -0500 (EDT)",
          "LastUpdate": "2/3/2025T15:50:57 GMT -0500 (EDT)"
        }
      }
    ]
  }
]

Formula: DATEDIFF(Account:Cases:Case1:CreatedDate, Account:Cases:Case1:LastUpdate)

Return value: 7

Formula: DATEDIFF(%Account:Cases:Case2:CreatedDate%, TODAY())

Return value: 8

Omnistudio DATETIMETOUNIX Function

Returns the number of milliseconds in UNIX time for a specified date and time.

UNIX time is the number of non-leap seconds that have passed since 00:00:00 on 1 January 1970, Coordinated Universal Time (UTC). UTC is the same as Greenwich Mean Time (GMT). The value is referred to as the UNIX epoch.

Signature

DATETIMETOUNIX(datetime)

Return Value

Integer

Parameters

Parameter	Data Type	Necessity	Description
`datetime`	Datetime	Required	A date and time specified as a string in Day.js format. You can also specify just a date.

Date and Time Example

Formula: DATETIMETOUNIX("2002-02-01T16:35:30:000Z")

Formula: DATETIMETOUNIX("2002-02-01T16:35:30:000")

Formula: DATETIMETOUNIX("2002-02-01T16:35:30")

Formula: DATETIMETOUNIX("02/01/2002T16:35:30")

Return value: 1012581330000

Date And Zero Time Example

Formula: DATETIMETOUNIX("2002-02-01")

Formula: DATETIMETOUNIX("02/01/2002")

Formula: DATETIMETOUNIX("2002-02-01T00:00:00")

Formula: DATETIMETOUNIX("02/01/2002T00:00:00")

Formula: DATETIMETOUNIX("2002-02-01T00:00:00Z")

Formula: DATETIMETOUNIX("02/01/2002T00:00:00Z")

Return value: 1012521600000

Omnistudio DAY Function

Returns the day for a specified date as an integer value.

Signature

DAY(date)

Return Value

Integer

Parameters

Parameter	Data Type	Necessity	Description
`date`	Datetime	Required	A date specified as a string in Day.js format. You can specify a date and time.

Date String Example

Formula: DAY("2025-01-31")

Formula: DAY("01/31/2025")

Formula: DAY("1/31/2025")

Return value: 31

JSON Object Example

Sample data: "Birthdate": "2002-02-15T16:35:30 GMT -0500 (EDT)"

Formula: DAY(Birthdate)

Return value: 15

Omnistudio EOM Function

Returns the date and time of the last day of the month for a specified date.

Signature

EOM(date)

Return Value

Datetime

Parameters

Parameter	Data Type	Necessity	Description
`date`	Datetime	Required	A date specified as a string in Day.js format. You can specify a date and time.

Date Example

Formula: EOM("2024-02-01")

Formula: EOM("02/01/2024")

Return value: "2024-02-29T00:00:00.000Z"

Date and Time Example

Formula: EOM("02/01/2024T16:35:30")

Formula: EOM("02/01/2024T16:35:30Z")

Return value: "2024-02-29T00:00:00.000Z"

Omnistudio FORMATDATETIME Function

Returns a date and time as a string in a specified format and time zone.

Greenwich Mean Time (GMT) is the same as Coordinated Universal Time (UTC), which serves as the basis of UNIX time and the UNIX epoch.

Signature

FORMATDATETIME(datetime, format, timezone)

Return Value

String

Parameters

Parameter	Data Type	Necessity	Description
`datetime`	Datetime	Required	A date and time specified as a string in Day.js format. You can specify just a date or time. If you specify only a date, the default time is `00:00:00`. If you specify only a time, the default date is `1970-01-01` (the UNIX epoch).
`format`	String	Optional	A string that specifies the format in which to return the date and time. Use Java SimpleDateFormat notation to specify the format of the response. By default, the function returns the date and time in the format `"MM/DD/YY HH:mm aaa"`.
`timezone`	String	Optional	A string that indicates the time zone in which to return the date and time. By default, the function returns the date and time in the caller's time zone. To use a different time zone, specify a time zone identifier, for example, `America/New_York`. For a complete list of time zone identifiers, see IANA (TZDB) time zone information. If you specify a `timezone`, you must also specify a `format`.

Date with No Time, Format, or Time Zone Example

Formula: FORMATDATETIME("01/31/2025")

Return value: "1/30/25 4:00 PM"

Datetime with No Format or Time Zone Example

Formula: FORMATDATETIME("01/31/2025T12:00:00")

Return value: "1/31/25 4:00 AM"

Datetime with No Time Zone Example

Formula: FORMATDATETIME("01/31/2025T12:00:00", "yyyy-MM-dd'T'HH:mm:ssZ")

Return value: "2025-01-31T04:00:00-0800"

Datetime Example

Formula: FORMATDATETIME("01/31/2025T12:00:00", "yyyy-MM-dd'T'HH:mm:ssZ", "America/Los_Angeles")

Return value: "2025-01-31T04:00:00-0800"

Datetime Example

Formula: FORMATDATETIME("01/31/2025T12:00:00", "yyyy-MM-dd'T'HH:mm:ssZ", "America/New_York")

Return value: "2025-01-31T07:00:00-0500"

Omnistudio FORMATDATETIMEGMT Function

Returns a date and time as a string in a specified format and in the GMT time zone.

Greenwich Mean Time (GMT) is the same as Coordinated Universal Time (UTC), which serves as the basis of UNIX time and the UNIX epoch.

Signature

FORMATDATETIMEGMT(datetime, timezone, format)

Return Value

String

Parameters

Parameter	Data Type	Necessity	Description
`datetime`	Datetime	Required	A date and time specified as a string in Day.js format. You can specify just a date or time. If you specify only a date, the default time is `00:00:00`. If you specify only a time, the default date is `1970-01-01` (the UNIX epoch).
`timezone`	String	Optional	A string that indicates the time zone of the specified date and time. By default, the function uses the caller's time zone. To use a different time zone, specify a time zone identifier, for example, `America/New_York`. For a complete list of time zone identifiers, see IANA (TZDB) time zone information.
`format`	String	Optional	A string that specifies the format in which to return the date and time. Use Java SimpleDateFormat notation to specify the format of the response. By default, the function returns the date and time in the format `"MM/DD/YY HH:mm aaa"`. If you specify a `format`, you must also specify a `timezone`.

Date with No Time, Time Zone, or Format Example

Formula: FORMATDATETIMEGMT("01/31/2025")

Return value: "2025-01-31T08:00:00.000Z"

Datetime with No Time Zone or Format Example

Formula: FORMATDATETIMEGMT("01/31/2025T12:00:00")

Return value: "2025-01-31T20:00:00.000Z"

Datetime with No Format Example

Formula: FORMATDATETIMEGMT("01/31/2025T12:00:00", "America/Los_Angeles")

Return value: "2025-01-31T20:00:00.000Z"

Datetime Example

Formula: FORMATDATETIMEGMT("01/31/2025T12:00:00", "America/Los_Angeles", "yyyy-MM-dd'T'HH:mm:ssZ")

Return value: "2025-01-31T20:00:00+0000"

Datetime Example

Formula: FORMATDATETIMEGMT("01/31/2025T12:00:00", "America/New_York", "yyyy-MM-dd'T'HH:mm:ssZ")

Return value: "2025-01-31T17:00:00+0000"

Omnistudio HOUR Function

Returns the hour for a specified time as an integer value.

Signature

Hour(time)

Return Value

Integer

Parameters

Parameter	Data Type	Necessity	Description
`time`	Datetime	Required	A time specified as a string in Day.js format. You can specify a date and time.

Time Example

Formula: HOUR("08:00:00")

Formula: HOUR("T08:00:00")

Return value: 8

Date and Time Example

Formula: HOUR("2004-02-01T08:00:00Z")

Formula: HOUR("02/01/2004T08:00:00Z")

Return value: 8

JSON Object Example

Sample data: "DateField": "2003-02-01T16:35:30Z"

Formula: HOUR(%DateField%)

Return value: 16

Omnistudio MINUTE Function

Returns the minute for a specified time as an integer value.

Signature

MINUTE(time)

Return Value

Integer

Parameters

Parameter	Data Type	Necessity	Description
`time`	Datetime	Required	A time specified as a string in Day.js format. You can specify a date and time.

Time Example

Formula: MINUTE("08:17:00")

Formula: MINUTE("T08:17:00")

Return value: 17

Date and Time Example

Formula: MINUTE("2004-02-01T08:17:00Z")

Formula: MINUTE("02/01/2004T08:17:00Z")

Return value: 17

JSON Object Example

Sample data: "DateField": "2003-02-01T16:35:30Z"

Formula: MINUTE(DateField)

Return value: 35

Omnistudio MONTH Function

Returns the month for a specified date as an integer value.

Signature

MONTH(date)

Return Value

Integer

Parameters

Parameter	Data Type	Necessity	Description
`date`	Datetime	Required	A date specified as a string in Day.js format. You can specify a date and time.

Date String Example

Formula: MONTH("2025-01-01")

Formula: MONTH("01/01/2025")

Formula: MONTH("1/1/2025")

Return value: 1

JSON Object Example

Sample data: "Birthdate": "2007-06-25T08:35:00Z"

Formula: MONTH(%Birthdate%)

Return value: 6

Omnistudio NOW Function

Returns the current date and time in a specified format.

By default, the function returns the date and time in Coordinated Universal Time (UTC). UTC is the same as Greenwich Mean Time (GMT). Use the $Vlocity.NOW environment variable to apply the time zone of the user or org.

You can use the NOW function with other functions to specify a date and time relative to the current date and time.

Signature

NOW(format)

Return Value

Datetime

Parameters

Parameter	Data Type	Necessity	Description
`format`	String	Optional	A format string in SimpleDateFormat notation that specifies the format of the response. By default, the function returns the date and time in the format `"yyyy-MM-dd'T'HH:mm:ss:SSS"` UTC (GMT).

No Format Example

Formula: NOW()

Return value: "2025-03-08T22:01:46.684Z"