DateTime module

The DateTime module contains functions for working with datetime values. Most of the functions are declared as self functions: by opening the DateTime module in a script step, you can use dot notation to call the functions on datetime values.

// Example 1: access the datetime module without opening it
return DateTime.addYears(now(), 1);

// Example 2: open the DateTime module and use it.
open DateTime;
return now().addYears(1);

Advanced: Time zones

All datetime values contain a Time Zone Offset. This ensures that values created on different devices "mean" the same absolute time.

Creating and Parsing datetime values

createDate

Signature: createDate(year: number, month: number, day: number) -> datetime

Returns a datetime value with the given year, month and day. The time portion of the datetime will be set to 00:00:00. The offset will be set to the local time zone.

createDateAndTime

Signature: createDateAndTime(year: number, month: number, day: number, hour: number, minute: number, second: number) -> datetime

Returns a datetime value with the given year, month, day, hour (in 24-hour time), minute and second.

the offset will be set to the local time zone.

isValidDate

Signature: isValidDate(input: any) -> boolean

Returns true if the input value can be converted to a valid date. Arguments that returns true can be used with the Date function to create a datetime value.

return isValidDate("2012-04-05") // returns true

Modifying datetime values

addSeconds

Signature: addSeconds(self input: datetime, seconds: number) -> datetime

Returns a new date obtained by adding the specified number of seconds to the input date. You can pass a negative number to subtract seconds.

addMinutes

Signature: addMinutes(self input: datetime, minutes: number) -> datetime

Returns a new date obtained by adding the specified number of minutes to the input date. You can pass a negative number to subtract minutes.

addHours

Signature: addHours(self input: datetime, hours: number) -> datetime

Returns a new date obtained by adding the specified number of hours to the input date. You can pass a negative number to subtract hours.

addDays

Signature: addDays(self input: datetime, days: number) -> datetime

Returns a new date obtained by adding the specified number of days to the input date. You can pass a negative number to subtract days.

addMonths

Signature: addMonths(self input: datetime, months: number) -> datetime

Returns a new date obtained by adding the specified number of months to the input date. You can pass a negative number to subtract months.

addYears

Signature: addYears(self input: datetime, months: number) -> datetime

Returns a new date obtained by adding the specified number of years to the input date. You can pass a negative number to subtract years.

setTime

Signature: setTime(date: datetime, hour: number, minute: number, second: number) -> datetime

Returns a new date obtained from the given date with the hours, minutes and second set by the provided arguments.

open DateTime;
let d = Date("2021-03-11 00:00:00");

return format(setTime(d,12,10,55), "G") // returns "03/11/2021 12:10:55"

toUtc

Signature: toUtc(self date: datetime) -> datetime

`Returns the given date converted to UTC.

open DateTime;
let easternTime = Date("2021-03-11 05:00:00 -05:00");

return format(easternTime.toUTC(), "g") // returns "03/11/2021 10:00"

toLocal

Signature: toLocal(self date: datetime) -> datetime

Returns the given date converted to local time.

open DateTime;
let easternTime = Date("2021-03-11 05:00:00 -05:00");

return format(easternTime.toLocal(), "g") // returns "03/11/2021 11:00" in GMT+1

Retrieving data from datetime values

getSecond

Signature: getSecond(self input: datetime) -> number

Returns the second component of the datetime value.

getMinute

Signature: getMinute(self input: datetime) -> number

Returns the minute component of the datetime value.

getHour

Signature: getHour(self input: datetime) -> number

Returns the hour component of the datetime value, in 24-hour time.

getDayOfMonth

Signature: getDayOfMonth(self input: datetime) -> number

Returns the day component of the datetime value.

getDayOfWeek

Signature: getDayOfWeek(self input: datetime) -> text

Returns the day of week for the given datetime value. Return values are English-laguage text values "monday", "tuesday" etc.

getMonth

Signature: getMonth(self input: datetime) -> number

Returns the month component of the datetime value.

getYear

Signature: getYear(self input: datetime) -> number

Returns the year component of the datetime value.

getTimeOffset

Signature: getTimeZoneOffset(self input: datetime) -> number

Returns the offset from UTC of the datetime value.

Comparing dates

differenceInDays

Signature: differenceInDays(fromDate: datetime, toDate: datetime) -> number

Returns the difference in days between two dates.

let yesterDay = Now().AddDays(-1);
let today = Now();

return Datime.differenceInDays(today, yesterDay) // will return 1

let easternTime = Date("2021-03-11 00:00:00 -05:00");
let pacificTime = Date("2021-03-10 21:00:00 -08:00");

return DateTime.differenceInDays(easternTime, pacificTime)
// will return 0 due to being the same time but in different timezones

differenceInSeconds

Signature: differenceInSeconds(fromDate: datetime, toDate: datetime) -> number

Returns the difference in seconds between two dates.

open DateTime;

let aMinuteAgo = Now().addMinutes(-1);
let currentTime = Now();

return differenceInSeconds(currentTime, aMinuteAgo) // will return -60

let easternTime = Date("2021-03-11 00:00:00 -05:00");
let pacificTime = Date("2021-03-10 21:00:30 -08:00");

return DateTime.differenceInSeconds(easternTime, pacificTime) 
// will return 30 due to being in different time zones.

HHMM text

createHHMMText

Signature: createHHMMText(input: datetime) -> text

Returns a text representation of datetime value hours and minutes

let d = DateTime.CreateDateAndTime(2023, 03, 09, 22, 34, 22)

return DateTime.CreateHHMMText(d) // returns "22:34"

getMinuteFromHHMMText

Signature: getMinuteFromHHMMText(input: text) -> number

Returns the number of minutes from a HHMM formatted text.

return DateTime.getMinuteFromHHMMText("22:34") // returns 34

getHourFromHHMMText

Signature: getHourFromHHMMText(input: text) -> number

Returns the number of hours from a HHMM formatted text.

return DateTime.getHourFromHHMMText("22:34") // returns 22