Working with Dates and Times
Airkit stores data regarding dates and times in specialized data types: the objects Date, Time, and DateTime. Using these specialized objects in tandem with the Airkit platform allows Airkit to handle the notorious complexities of time-tracking under the hood.
Dates
A Date object represents a particular calendar day. It consists of three properties:
- day (
number) - the day of a month, where indexing begins at 1 with January - month (
number) - the month of a year, where 1 represents January, whereas 12 represents December - year (
number) - a year
For example, a Date representing June 16, 2022 would be given as:
{
"day": 16,
"month": 6,
"year": 2022
}
Basic Applications
For the sake of example, assume all the following Airscript expressions have access to the following Date, example_date, which represents December 30th, 2021:
example_date = {
"day": 30,
"month": 12,
"year": 2021
}
On the surface, example_date behaves like any other object, the properties of which are accessible via dot notation. For instance, the value of the "day" property is accessible as follows:
example_date.day -> 30
However, the true power of Date objects is in using them in tandem with parts of the Airkit platform that expect not just any object, but the special data type, Date.
Date values can used to generate strings that represent the described date in a more intuitive manner. The following example uses the FORMAT_DATE function to generate "December 30th, 2021" from example_date:
FORMAT_DATE(example_date, "MMMM Do, YYYY") -> "December 30th, 2021"
Date values can be modified such that they automatically account for calendar configuration. For instance, if ADD_TO_DATE is used to add two days to example_date, this doesn't simply add 2 to the day attribute, it changes the month and year attributes to reference an appropriate date:
ADD_TO_DATE(example_date, 2, "days") -> {
"day": 1,
"month": 1,
"year": 2022
}
Times
A Time object represents a time of day. It consists of four properties:
- hour (
number) - an hour of a day represented by a 24-hour clock - minute (
number) - the number of minutes into the hour - second (
number) - the number of seconds into the minute - millisecond (
number) - the number of milliseconds into the second
For example, a Time representing 3:11 pm and 34 seconds would be given as:
{
"hour": 15,
"minute": 11,
"second": 34,
"millisecond": 0
}
Basic Applications
For the sake of example, assume all the following Airscript expressions have access to the following Time, example_time, which represents 11:15 pm and 30 seconds:
example_time = {
"hour": 23,
"minute": 15,
"second": 30,
"millisecond": 0
}
On the surface, example_time behaves like any other object, the properties of which are accessible via dot notation. For instance, the value of the "hour" property is accessible as follows:
example_time.hour -> 23
However, the true power of Time objects is in using them in tandem with parts of the Airkit platform that expect not just any object, but the special data type, Time.
For instance, Time values can used to generate strings that represent the described date in a more intuitive manner. The following example uses the FORMAT_TIME function to generate "11:15 pm" from example_time:
FORMAT_TIME(example_time, "h:mm a") -> "11:15 pm"
DateTimes
A DateTime object represents a single moment in time: a certain time on a certain date. It can serve the same functions as a timestamp.
A DateTime object consists of three properties:
- date (
Date) - a Date object, consisting of "day", "month", and "year" properties - time (
Time) - a Time object, consisting of "hour", "minute", "second", and "millisecond" properties - timeZone (
string, timezone abbreviation) - the timezone to which the date and time properties refer, tends to default to "UTC".
For example, a DateTime representing June 21, 2022, 9:34am and 48 seconds in UTC would be given as:
{
"date": {
"day": 21,
"month": 6,
"year": 2022
},
"time": {
"hour": 9,
"minute": 34,
"second": 48,
"millisecond": 0
},
"timeZone": "UTC"
}
Basic Applications
For the sake of example, assume all the following Airscript expressions have access to the following Date, example_datetime, which represents June 21, 2022, 9:34am and 48 seconds in UTC:
example_datetime = {
"date": {
"day": 21,
"month": 6,
"year": 2022
},
"time": {
"hour": 9,
"minute": 34,
"second": 48,
"millisecond": 0
},
"timeZone": "UTC"
}
On the surface, example_datetime behaves like any other object, the properties of which are accessible via dot notation. For instance, the value of the "hour" property nested under the "time" property is accessible as follows:
example_datetime.time.hour -> 9
However, the true power of DateTime objects is in using them in tandem with parts of the Airkit platform that expect not just any object, but the special data type, DateTime.
DateTime values can used to generate strings that represent the described moment in time in a more intuitive manner. The following example uses the FORMAT_DATETIME function to generate "06/21/22 9:34 AM UTC" from example_datetime:
FORMAT_DATETIME(example_datetime, "MM/DD/YY h:mm A z") -> "06/21/22 9:34 AM UTC"
DateTime objects can also be converted into strings that display the described moment in time in a more relevant timezone. The following example takes example_datetime and returns the described date and time not in UTC, but CDT:
FORMAT_DATETIME(
example_datetime,
"MM/DD/YY h:mm A z",
"en-EN",
"America/Chicago"
) -> "06/21/22 4:34 AM CDT"
Note how the time changes to reflected the changes in timezone. DateTime objects are a special time of object, capable of handling the complexities of timezone changes under the hood.
This allows DateTime objects to serve the same functions as timestamps. In fact, a DateTime can be easily converted into a timestamp by giving it as input to the function TIMESTAMP_FROM_DATETIME – no other input required:
TIMESTAMP_FROM_DATETIME(example_datetime) -> 1655804088000
Similarly, the DATETIME_FROM_TIMESTAMP function can be used to convert a timestamp to a DateTime, which allows timestamps collected by external systems to be used in Airkit apps.
Timers
Timers can be used to schedule Actions to take place at some future time. The Execution Time can be defined as a Custom Expression, which expects a DateTime object as input.
To define a DateTime in relation to the current instant in time, you can use the NOW function in tandem with the ADD_TO_DATETIME function. The NOW function returns the DateTime at the instant it was called, and ADD_TO_DATETIME returns a DateTime at some specified instant after the given DateTime. For instance, the following example will return a DateTime specifying an instant in time five minutes from when the expression is called:
ADD_TO_DATETIME(NOW(), 5, "minute")
Timers can also be set in relation to a future instant in time. For instance, say you've save the time of a future appointment to a DateTime variable called appointment_time. To set a Timer for one hour before the appointment – perhaps to send a reminder Notification – you can use the appointment_time variable in tandem with the SUBTRACT_FROM_DATETIME function, as follows:
SUBTRACT_FROM_DATETIME(appointment_time, 1, "hour")
Scheduling
Scheduler Web Controls allow users to select appointment slots. They automatically save both the start and end time of the appointments as DateTime objects.
When stored as local variables, these start and end DateTime values can be used like any other DateTime object to, for instance:
- Set a Timer to issue a reminder SMS Notification a short time before the appointment.
- Confirm the appointment time in a Label by using it as input in FORMAT_DATETIME.
- Use a Timer to schedule a follow-up Email Notification once the appointment is finished.
Additional Resources
Want to learn by building? 🛠️ Check out our long-form tutorial on scheduling and proactive service:
Updated almost 2 years ago