DateTime API
DateTime is a special data type that stores date and time.
DateTime API contains a list of methods used to manipulate DateTime in order to:
- format date and time to show or read them to the user in responses,
- compare and change DateTime by adding or substracting years, months, days or minutes,
- get specific properties from DateTime as Numbers: a year, a month, a day, an hour or a minute.
Understanding and displaying DateTime
DateTime data type is, technically, a specific kind of Object. This Object contains all of the information needed to display and manipulate date and time.
But, there is no way to actually see this 'DateTime Object'. For example, if you print out the current DateTime using
{system.currentTime}in the response, the bot will respond with something like that:2023-05-24 13:36. This doesn't look like an Object - it's because this is actually an already formatted String which represents 'DateTime Object' stored insystem.currentTime.And so, the only way to access, manipulate, and format specific information from 'DateType Objects' is by using DateTime API methods listed below 👇
List of DateTime methods
DateTime methods listed below cannot be used on any data type except for DateTime, so make sure that you don't try using them on a String or a Number.
| DateTime method | Description | Result |
|---|---|---|
| getYear() | Returns the year for the given DateTime. | Number |
| getMonth() | Returns the Number of the month for the given DateTime. | Number (1-12) |
| getDay() | Returns the day of the month for the given DateTime. | Number (1-31) |
| getHour() | Returns the hour for the given DateTime in the 24-Hour Time Format. | Number (0-23) |
| getMinute() | Returns the minute for the given DateTime. | Number (0-59) |
| getDayOfWeek() | Returns the day of the week (as a Number) for the given DateTime. | Number (1-7) |
| formatAsTime() | Returns a String representing the time for the given DateTime in the HH:mm format. | String |
| formatAsDate() | Returns a String representing the date for the given DateTime in the yyyy-MM-dd format. | String |
| format(custom) | Returns a String representing the given DateTime in the custom format. | String |
| plusYears(Number) | Adds a Number of years to the given DateTime. | DateTime |
| minusYears(Number) | Subtracts a Number of years from the given DateTime. | DateTime |
| plusMonths(Number) | Adds a Number of months to the given DateTime. | DateTime |
| minusMonths(Number) | Subtracts a Number of months from the given DateTime | DateTime |
| plusDays(Number) | Adds a Number of days to the given DateTime. | DateTime |
| minusDays(Number) | Subtracts a Number of days from the given DateTime | DateTime |
| plusHours(Number) | Adds a Number of hours to the given DateTime | DateTime |
| minusHours(Number) | Subtracts a Number of hours from the given DateTim | DateTime |
| plusMinutes(Number) | Adds a Number of minutes to the given DateTime. | DateTime |
| minusMinutes(Number) | Subtracts a Number of minutes from the given DateTime | DateTime |
| isAfter(DateTime) | Is this DateTime after the DateTime passed in comparing solely by millisecond. | Boolean |
| isBefore(DateTime) | Is this DateTime before the DateTime passed in comparing solely by millisecond. | Boolean |
| withTimeAtStartOfDay() | Returns a copy of this DateTime with the time set to the start of the day. | DateTime |
| getMillis() | Gets the milliseconds of this DateTime that passed from 1970-01-01T00:00:00Z. | Number |
Obtaining and creating DateTime
You can only use DateTime methods on values of DateTime type, and not Strings nor Numbers. For example, "1998/04/04".getYear() will throw an error.
There are 3 ways to obtain or create DateTime:
Get current time with system.currentTime
system.currentTimeTo get current date and time, use system.currentTime. This System API property gets a current time and date as a DateTime. This is why you can use DateTime methods directly on it, eg. system.currentTime.formatAsTime().
Get DateTime from user input using NLU
To get date and time recognized in the user input, use nlu.variables.time.value. This NLU API property obtains a DateTime value from "time" entity recognized in the user input.
You can also use nlu.variablesList.filter(el=>el.name=time) to get an array of all of the "time" entities recognized in the user input.
Create DateTime with toDateTime()
toDateTime()toDateTime() is one of the String methods. It converts a String into a DateTime value. This is the only way to create DateTime value on your own. For this method to work, the given String has to have a specific format:
Date: YYYY-MM-DD
Date with time: YYYY-MM-DDTHH:mm
Full DateTime String: YYYY-MM-DDTHH:mm:ss.SSS+Z
Where:
YYYY - year
MM - month
DD - day of the month
HH - hours
mm - minutes
ss - seconds
SSS - miliseconds
Z - time zone offset
You can either specify both date and time (YYYY-MM-DDTHH:mm) or just a date (YYYY-MM-DD) . The following code snippet contains a few examples of correct expressions that use toDateTime() to convert Strings into DateTime:
"1990-10-30".toDateTime()
"1990-10-30T11:00".toDateTime()
("1990" + "-10-" + system.currentTime.getDay()).toDateTime()
When you get a date and time formatted as a String (eg. from REST API integration), you can use available String methods to achieve a format that is acceptable by toDateTime() method.
For example, to convert memory.response.date into DateTime if memory.response.date = "1997/07/20", use:
memory.response.date.replace("/","-").toDateTime()
DateTime methods
getYear()
Returns the year for the given DateTime.
Result: Number
//for:
//system.currentTime = "2023-05-24 13:36"
system.currentTime.getYear()
//Result:
1975
//for:
//system.currentTime = "2023-05-24 13:36"
//Response input:
The year is {system.currentTime.getYear()}.
//Bot's response:
"The year is 2023."
getMonth()
Returns the Number of the month for the given DateTime.
Result: Number from 1 to 12
//for:
//system.currentTime = "2023-05-24 13:36"
system.currentTime.getMonth()
//Result:
5
//for:
//system.currentTime = "2023-05-24 13:36"
//memory.months = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"]
//Response input:
The current month is the {system.currentTime.getMonth()}th month of the year.
In English, we call it {memory.months[system.currentTime.getMonth() - 1]}
//Bot's response:
"The current month is the 5th month of the year. In English, we call it May."
This method returns Numbers instead of month names so that it can be used with any language. To print out the name of the month:
- Create an array containing the names of the months (in any language imaginable).
- Access an element of the array by index with the index equal to
.getMonth() - 1.
Here is an example:
//for:
//system.currentTime = "2023-05-24 13:36"
//memory.months = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"]
memory.months[system.currentTime.getMonth() - 1]
//Result:
"May"
getDay()
Returns the day of the month for the given DateTime.
Result: Number from 1 to 31
//for:
//system.currentTime = "2023-05-24 13:36"
system.currentTime.getDay()
//Result:
24
//for:
//system.currentTime = "2023-05-24 13:36"
//Response input:
Today is {system.currentTime.getDay()}th day of the month.
//Bot's response:
"Today is 24th day of the month."
getHour()
Returns the hour for the given DateTime in the 24-Hour Time Format.
Result: Number from 0 to 23
//for:
//system.currentTime = "2023-05-24 13:36"
system.currentTime.getHour()
//Result:
13
//for:
//system.currentTime = "2023-05-24 13:36"
//Response input:
Your request will be reviewed in about an hour, until {system.currentTime.getHour() + 1}:{system.currentTime.getMinute()}.
//Bot's response:
"Your request will be reviewed in about an hour, until 14:36."
getMinute()
Returns the minute for the given DateTime.
Result: Number from 0 to 59
//for:
//system.currentTime = "2023-05-24 13:36"
system.currentTime.getMinute()
//Result:
36
//for:
//system.currentTime = "2023-05-24 13:36"
//Response input:
{system.currentTime.getMinute()} minutes have passed since 1pm.
//Bot's response:
"36 minutes have passed since 1pm."
getDayOfWeek()
Returns the day of the week (as a Number) for the given DateTime.
Result: Number from 1 to 7, where 1 is Monday and 7 is Sunday.
//for:
//system.currentTime = "2023-05-24 13:36"
system.currentTime.getDayOfWeek()
//Result:
3
//for:
//system.currentTime = "2023-07-25 15:20"
//memory.weekDays = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]
//memory.weekDayIndex = system.currentTime.getDayOfWeek()
//Response input:
Today is {memory.weekDays[memory.weekDayIndex - 1]}. It is the {memory.weekDayIndex}th day of the week.
//Bot's response:
"Today is Thursday. It is the 4th day of the week."
This method returns Numbers instead of weekday names so that it can be used with any language. To print out the name of the weekday:
- Create an array containing the names of the weekdays (in any language imaginable).
- Access an element of the array by index with the index equal to
.getDayOfWeek() - 1.
Here is an example:
//for:
//system.currentTime = "2023-05-24 13:36"
//memory.weekDays = ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"]
memory.weekDays[system.currentTime.getDayOfWeek() - 1]
//Result:
"Wednesday"
formatAsTime()
Returns a String representing the time for the given DateTime in the HH:mm format.
//for:
//system.currentTime = "2023-05-24 13:36"
system.currentTime.formatAsTime()
//Result:
"13:36"
//for:
//system.currentTime = "2023-05-24 13:36"
//Response input:
Your request has been sent at {system.currentTime.formatAsTime()}.
//Bot's response:
"Your request has been sent at 13:36."
formatAsDate()
Returns a String representing the date for the given DateTime in the yyyy-MM-dd format.
//for:
//system.currentTime = "2023-05-24 13:36"
system.currentTime.formatAsDate()
//Result:
"2023-05-24"
//for:
//system.currentTime = "2023-05-24 13:36"
//Response input:
Your request has been sent on {system.currentTime.formatAsDate()}.
//Bot's response:
"Your request has been sent on 2023-05-24."
format(custom)
Returns a String representing the given DateTime in a custom, pattern-based format.
The method's argument is a pattern (String) according to which DateTime will be formatted. For example, system.currentTime.format("dd.MM.yyyy") will return a String formatted like that: "24.05.2023".
If an argument is omitted, the method will return a full, unformatted String representing DateTime. For example, system.currentTime.format() will return such String: "2023-05-24T10:24:15.476+02:00"
The following tables contains all of the symbol patterns which you can use to custom format date and/or time. Below the table, you'll find many examples of using format() method.
Pattern-based formatting
| Date patterns | Meaning | Example |
|---|---|---|
y or yyyy | year (4-digit) | 2023 |
yy | year (2-digit) | 23 |
MMMM | month (full English name) | July |
MMM | month (shorten English name) | Jul |
MM | month (2-digit) | 06 |
M | month (1-digit or 2-digit) | 6 |
dd | day of month (2-digit) | 09 |
d | day of month (1-digit or 2-digit) | 9 |
e | day of week (digit) | 4 |
EEEE | day of week (full English name) | Thursday |
E | day of week (shorten English name) | Thu |
D | day of year (Number) | 145 |
w | week of year (Number) | 21 |
| Time patterns | Meaning | Example |
|---|---|---|
H | hour od day (Number 0-23) | 14 |
a | halfday of day (AM/PM) | PM |
h | hour of halfday (Number 1-12) | 2 |
mm | minute of hour (2-digit) | 08 |
m | minute of hour (1-digit or 2-digit) | 8 |
ss | second of minute (2-digit) | 05 |
s | second of minute (1-digit or 2-digit) | 5 |
SSS | miliseconds of second (3-digit) | 354 |
zzzz | time zone (full English name) | Central European Summer Time |
z | time zone (shortcut) | CEST |
ZZZ | time zone id | Europe/Warsaw |
ZZ | time zone offset | +02:00 |
Z | time zone offset | +0200 |
| Adding text to formatted String | Example |
|---|---|
Any non-alphabetical characters (eg. -, ., ,, :, Numbers etc.) will appear as a part of formatted String. | format("HH:mm") will return something like 13:00 |
To add letters to the formatted String, put them inside single quotes ''. | format("Dth") will throw an error, while format("D'th'") will return something like 24th |
Full list available on joda.org.
format(custom) examples
//for:
//system.currentTime = "2023-05-26 06:05"
system.currentTime.format("MMM yy")
//Result:
"May 26"
{system.currentTime.format("dd/MM/y")}
//Result:
"26/05/2023"
{system.currentTime.format("d/M (EEEE)")}
//Result:
"26/5 (Friday)"
{system.currentTime.format("'week' w 'of year' y")}
//Result:
"week 21 of year 2023"
{system.currentTime.format("D'th day of year' yy")}
//Result:
"146th day of year 23"
//for:
//system.currentTime = "2023-05-26 16:11"
{system.currentTime.format("H.mm")}
//Result:
"16.11"
{system.currentTime.format("h:mm a")}
//Result:
"4:11 PM"
{system.currentTime.format("after h a")}
//Result:
"after 4 PM"
{system.currentTime.format("m'th minute of an hour'")}
//Result:
"11th minute of an hour"
Any characters in the pattern that are not in the ranges of ['a'..'z'] and ['A'..'Z'] will be treated as quoted text. For instance, characters like ':', '.', ' ', '#' and '?' will appear in the resulting time text even they are not embraced within single quotes.
plusYears(Number)
Returns new DateTime increased by the Number of years given as an argument.
//for:
//system.currentTime = "2023-05-24 13:36"
system.currentTime.plusYears(1)
//Result:
"2024-05-24 13:36"
system.currentTime.plusYears(-2)
//Result:
"2021-05-24 13:36"
//for:
//system.currentTime = "2023-05-24 13:36"
//memory.courseYears = 5
//Response input:
If you start the course now, you will finish it in {system.currentTime.plusYears(memory.courseYears).getYear()}.
//Bot's response:
"If you start the course now, you will finish it in 2028."
minusYears(Number)
Returns new DateTime decreased by the Number of years given as an argument.
//for:
//system.currentTime = "2023-05-24 13:36"
system.currentTime.minusYears(1)
//Result:
"2022-05-24 13:36"
//for:
//system.currentTime = "2023-05-24 13:36"
//memory.subscriptionEndedYearsAgo = 5
//Response input:
Your subscription ended {system.currentTime.minusYears(memory.subscriptionEndedYearsAgo).getYear()} year(s) ago.
//Bot's response:
"Your subscription ended 5 year(s) ago
plusMonths(Number)
Returns new DateTime increased by the Number of months given as an argument.
//for:
//system.currentTime = "2023-05-24 13:36"
system.currentTime.plusMonths(5)
//Result:
"2023-10-24 13:36"
//for:
//system.currentTime = "2023-05-24 13:36"
//Response input:
The results of your application will be published on {system.currentTime.plusMonths(2).formatAsDate()}.
//Bot's response:
"The results of your application will be published on 2023-07-24".
minusMonths(Number)
Returns new DateTime decreased by the Number of months given as an argument.
//for:
//system.currentTime = "2023-05-24 13:36"
system.currentTime.minusMonths(5)
//Result:
"2022-12-24 13:36"
plusDays(Number)
Returns new DateTime increased by the Number of days given as an argument.
//for:
//system.currentTime = "2023-05-24 13:36"
system.currentTime.plusDays(10)
//Result:
"2023-06-03 13:36"
//for:
//system.currentTime = "2023-05-24 13:36"
//memory.dateGiven = "2023-06-03T00:00:00.000+02:00"
//Response input:
The date given is {if (system.currentTime.plusDays(7) < memory.dateGiven) "not " else ""}within the next week.
//Bot's response:
"The date given is within not the next week.
minusDays(Number)
Returns new DateTime decreased by the Number of days given as an argument
//for:
//system.currentTime = "2023-05-24 13:36"
system.currentTime.minusDays(5)
//Result:
"2023-05-19 13:36"
plusHours(Number)
Returns new DateTime increased by the Number of hours given as an argument.
//for:
//system.currentTime = "2023-05-24 13:36"
system.currentTime.plusHours(5)
//Result:
"2023-05-24 18:36"
minusHours(Number)
Returns new DateTime decreased by the Number of hours given as an argument.
//for:
//system.currentTime = "2023-05-24 13:36"
system.currentTime.minusHours(5)
//Result:
"2023-05-24 8:36"
plusMinutes(Number)
Returns new DateTime increased by the Number of minutes given as an argument.
//for:
//system.currentTime = "2023-05-24 13:36"
system.currentTime.plusMinutes(60)
//Result:
"2023-05-24 14:36"
//for:
//system.currentTime = "2023-05-24 13:36"
//Response input:
Your test results will be ready in two hours, until {system.currentTime.plusMinutes(120).formatAsTime()}.
//Bot's response:
Your test results will be ready in two hours, until 15:56.
minusMinutes(Number)
Returns new DateTime decreased by the Number of minutes given as an argument
//for:
//system.currentTime = "2023-05-24 13:36"
system.currentTime.minusMinutes(5)
//Result:
"2023-05-24 13:31"
isAfter(DateTime)
Returns Boolean indicating if this DateTime is after the DateTime passed in comparing solely by millisecond.
system.currentTime.plusMinutes(60).isAfter(system.currentTime)
//Result:
True
system.currentTime.plusMinutes(-60).isAfter(system.currentTime)
//Result:
False
//for:
//system.currentTime = "2024-02-20 10:36"
//memory.dateGiven = "2024-06-03T00:00:00.000+02:00"
//Response input:
The date given is {if (memory.dateGiven.isAfter(system.currenTime)) "" else "not "}after current time.
//Bot's response:
"The date given is not after current time."
isBefore(DateTime)
Returns Boolean indicating if this DateTime is before the DateTime passed in comparing solely by millisecond.
system.currentTime.plusMinutes(60).isBefore(system.currentTime)
//Result:
False
system.currentTime.plusMinutes(-60).isBefore(system.currentTime)
//Result:
True
//for:
//system.currentTime = "2024-02-20 10:36"
//memory.dateGiven = "2024-01-03T00:00:00.000+02:00"
//Response input:
The date given is {if (memory.dateGiven.isBefore(system.currenTime)) "" else "not "}before current time.
//Bot's response:
"The date given is before current time."
withTimeAtStartOfDay()
Returns a copy of this DateTime with the time set to the start of the day.
//for:
//system.currentTime = "2024-02-22 13:36"
system.currentTime.withTimeAtStartOfDay()
//Result:
"2024-02-22 00:00"
getMillis()
Gets the milliseconds of this DateTime that passed from 1970-01-01T00:00:00Z.
//for:
//system.currentTime = "2024-02-22 13:36"
system.currentTime.getMillis()
//Result:
1708605360000
Updated about 1 year ago
Learn more about Expression language and its methods & APIs: