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 over 1 year ago