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:

Time Unit Values

There are many Airscript functions that require string input designating a unit of time. In order to be correctly parsed by the Airscript function, the given string must exactly match one of the possible values given in the following table:

Time Unit	Possible Values
Year	"year", "years", "y"
Month	"month", "months", "M"
Week	"week", "weeks", "w"
Day	"day", "days", "d"
Hour	"hour", "hours", "h"
Minute	"minute", "minutes", "m"
Second	"second", "seconds", "s"
Millisecond	"millisecond", "milliseconds", "ms"

Date and Time Formatting Options

There are many Airscript functions that require string input designating how a unit of time will be formatted. This by combining the tokens given in the following table:

Unit	Token	Output
Month	M	1 2 ... 11 12
	Mo	1st 2nd ... 11th 12th
	MM	01 02 ... 11 12
	MMM	Jan Feb ... Nov Dec
	MMMM	January February ... November December
Quarter	Q	1 2 3 4
	Qo	1st 2nd 3rd 4th
Day of Month	D	1 2 ... 30 31
	Do	1st 2nd ... 30th 31st
	DD	01 02 ... 30 31
Day of Year	DDD	1 2 ... 364 365
	DDDo	1st 2nd ... 364th 365th
	DDDD	001 002 ... 364 365
Day of Week	d	0 1 ... 5 6
	do	0th 1st ... 5th 6th
	dd	Su Mo ... Fr Sa
	ddd	Sun Mon ... Fri Sat
	dddd	Sunday Monday ... Friday Saturday
Day of Week (Locale)	e	0 1 ... 5 6
Day of Week (ISO)	E	1 2 ... 6 7
Week of Year	w	1 2 ... 52 53
	wo	1st 2nd ... 52nd 53rd
	ww	01 02 ... 52 53
Week of Year (ISO)	W	1 2 ... 52 53
	Wo	1st 2nd ... 52nd 53rd
	WW	01 02 ... 52 53
Year	YY	70 71 ... 29 30
	YYYY	1970 1971 ... 2029 2030
	Y	1970 1971 ... 9999 +10000 +10001
Week Year	gg	70 71 ... 29 30
	gggg	1970 1971 ... 2029 2030
Week Year (ISO)	GG	70 71 ... 29 30
	GGGG	1970 1971 ... 2029 2030
AM/PM	A	AM PM
	a	am pm
Hour	H	0 1 ... 22 23
	HH	00 01 ... 22 23
	h	1 2 ... 11 12
	hh	01 02 ... 11 12
	k	1 2 ... 23 24
	kk	01 02 ... 23 24
Minute	m	0 1 ... 58 59
	mm	00 01 ... 58 59
Second	s	0 1 ... 58 59
	ss	00 01 ... 58 59
Fractional Second	S	0 1 ... 8 9
	SS	00 01 ... 98 99
	SSS	000 001 ... 998 999
	SSSS ... SSSSSSSSS	000[0..] 001[0..] ... 998[0..] 999[0..]
Time Zone	z or zz	EST CST ... MST PST
	Z	-07:00 -06:00 ... +06:00 +07:00
	ZZ	-0700 -0600 ... +0600 +0700
Unix Timestamp	X	1360013296
Unix Millisecond Timestamp	x	1360013296123

For instance, the format of "September 28th, 2021, 4:52 PM" is "MMMM Do, YYYY, h:mm A".

Supported Time Zones

The following are a list of supported Time Zones that can be used with Airscript functions, such as NOW() ), UPDATE_TIMEZONE() , FORMAT_DATETIME() and other datetime functions.

Time Zones
Africa/Abidjan
Africa/Accra
Africa/Nairobi
Africa/Algiers
Africa/Lagos
Africa/Bissau
Africa/Maputo
Africa/Cairo
Africa/Casablanca
Africa/Ceuta
Africa/El_Aaiun
Africa/Johannesburg
Africa/Juba
Africa/Khartoum
Africa/Monrovia
Africa/Ndjamena
Africa/Sao_Tome
Africa/Tripoli
Africa/Tunis
Africa/Windhoek
America/Adak
America/Anchorage
America/Port_of_Spain
America/Araguaina
America/Argentina/Buenos_Aires
America/Argentina/Catamarca
America/Argentina/Cordoba
America/Argentina/Jujuy
America/Argentina/La_Rioja
America/Argentina/Mendoza
America/Argentina/Rio_Gallegos
America/Argentina/Salta
America/Argentina/San_Juan
America/Argentina/San_Luis
America/Argentina/Tucuman
America/Argentina/Ushuaia
America/Curacao
America/Asuncion
America/Atikokan
America/Bahia_Banderas
America/Bahia
America/Barbados
America/Belem
America/Belize
America/Blanc-Sablon
America/Boa_Vista
America/Bogota
America/Boise
America/Cambridge_Bay
America/Campo_Grande
America/Cancun
America/Caracas
America/Cayenne
America/Panama
America/Chicago
America/Chihuahua
America/Costa_Rica
America/Creston
America/Cuiaba
America/Danmarkshavn
America/Dawson_Creek
America/Dawson
America/Denver
America/Detroit
America/Edmonton
America/Eirunepe
America/El_Salvador
America/Tijuana
America/Fort_Nelson
America/Fort_Wayne
America/Fortaleza
America/Glace_Bay
America/Godthab
America/Goose_Bay
America/Grand_Turk
America/Guatemala
America/Guayaquil
America/Guyana
America/Halifax
America/Havana
America/Hermosillo
America/Indiana/Knox
America/Indiana/Marengo
America/Indiana/Petersburg
America/Indiana/Tell_City
America/Indiana/Vevay
America/Indiana/Vincennes
America/Indiana/Winamac
America/Inuvik
America/Iqaluit
America/Jamaica
America/Juneau
America/Kentucky/Louisville
America/Kentucky/Monticello
America/La_Paz
America/Lima
America/Los_Angeles
America/Maceio
America/Managua
America/Manaus
America/Martinique
America/Matamoros
America/Mazatlan
America/Menominee
America/Merida
America/Metlakatla
America/Mexico_City
America/Miquelon
America/Moncton
America/Monterrey
America/Montevideo
America/Toronto
America/Nassau
America/New_York
America/Nipigon
America/Nome
America/Noronha
America/North_Dakota/Beulah
America/North_Dakota/Center
America/North_Dakota/New_Salem
America/Ojinaga
America/Pangnirtung
America/Paramaribo
America/Phoenix
America/Port-au-Prince
America/Rio_Branco
America/Porto_Velho
America/Puerto_Rico
America/Punta_Arenas
America/Rainy_River
America/Rankin_Inlet
America/Recife
America/Regina
America/Resolute
America/Santarem
America/Santiago
America/Santo_Domingo
America/Sao_Paulo
America/Scoresbysund
America/Sitka
America/St_Johns
America/Swift_Current
America/Tegucigalpa
America/Thule
America/Thunder_Bay
America/Vancouver
America/Whitehorse
America/Winnipeg
America/Yakutat
America/Yellowknife
Antarctica/Casey
Antarctica/Davis
Antarctica/DumontDUrville
Antarctica/Macquarie
Antarctica/Mawson
Pacific/Auckland
Antarctica/Palmer
Antarctica/Rothera
Antarctica/Syowa
Antarctica/Troll
Antarctica/Vostok
Europe/Oslo
Asia/Riyadh
Asia/Almaty
Asia/Amman
Asia/Anadyr
Asia/Aqtau
Asia/Aqtobe
Asia/Ashgabat
Asia/Atyrau
Asia/Baghdad
Asia/Qatar
Asia/Baku
Asia/Bangkok
Asia/Barnaul
Asia/Beirut
Asia/Bishkek
Asia/Brunei
Asia/Kolkata
Asia/Chita
Asia/Choibalsan
Asia/Shanghai
Asia/Colombo
Asia/Dhaka
Asia/Damascus
Asia/Dili
Asia/Dubai
Asia/Dushanbe
Asia/Famagusta
Asia/Gaza
Asia/Hebron
Asia/Ho_Chi_Minh
Asia/Hong_Kong
Asia/Hovd
Asia/Irkutsk
Europe/Istanbul
Asia/Jakarta
Asia/Jayapura
Asia/Jerusalem
Asia/Kabul
Asia/Kamchatka
Asia/Karachi
Asia/Urumqi
Asia/Kathmandu
Asia/Khandyga
Asia/Krasnoyarsk
Asia/Kuala_Lumpur
Asia/Kuching
Asia/Macau
Asia/Magadan
Asia/Makassar
Asia/Manila
Asia/Nicosia
Asia/Novokuznetsk
Asia/Novosibirsk
Asia/Omsk
Asia/Oral
Asia/Pontianak
Asia/Pyongyang
Asia/Qostanay
Asia/Qyzylorda
Asia/Rangoon
Asia/Sakhalin
Asia/Samarkand
Asia/Seoul
Asia/Srednekolymsk
Asia/Taipei
Asia/Tashkent
Asia/Tbilisi
Asia/Tehran
Asia/Thimphu
Asia/Tokyo
Asia/Tomsk
Asia/Ulaanbaatar
Asia/Ust-Nera
Asia/Vladivostok
Asia/Yakutsk
Asia/Yekaterinburg
Asia/Yerevan
Atlantic/Azores
Atlantic/Bermuda
Atlantic/Canary
Atlantic/Cape_Verde
Atlantic/Faroe
Atlantic/Madeira
Atlantic/Reykjavik
Atlantic/South_Georgia
Atlantic/Stanley
Australia/Sydney
Australia/Adelaide
Australia/Brisbane
Australia/Broken_Hill
Australia/Hobart
Australia/Darwin
Australia/Eucla
Australia/Lord_Howe
Australia/Lindeman
Australia/Melbourne
Australia/Perth
CET
Pacific/Easter
CST6CDT
EET
EST
EST5EDT
Etc/GMT-0
Etc/GMT-1
Pacific/Port_Moresby
Etc/GMT-11
Pacific/Tarawa
Etc/GMT-13
Etc/GMT-14
Etc/GMT-2
Etc/GMT-3
Etc/GMT-4
Etc/GMT-5
Etc/GMT-6
Indian/Christmas
Etc/GMT-8
Pacific/Palau
Etc/GMT+1
Etc/GMT+10
Etc/GMT+11
Etc/GMT+12
Etc/GMT+3
Etc/GMT+4
Etc/GMT+5
Etc/GMT+6
Etc/GMT+7
Etc/GMT+8
Etc/GMT+9
Etc/UTC
Europe/Dublin
Europe/Amsterdam
Europe/Andorra
Europe/Astrakhan
Europe/Athens
Europe/London
Europe/Belgrade
Europe/Berlin
Europe/Prague
Europe/Brussels
Europe/Bucharest
Europe/Budapest
Europe/Zurich
Europe/Chisinau
Europe/Copenhagen
Europe/Gibraltar
Europe/Helsinki
Europe/Kaliningrad
Europe/Kiev
Europe/Kirov
Europe/Lisbon
Europe/Luxembourg
Europe/Madrid
Europe/Malta
Europe/Minsk
Europe/Monaco
Europe/Moscow
Europe/Paris
Europe/Riga
Europe/Rome
Europe/Samara
Europe/Saratov
Europe/Simferopol
Europe/Sofia
Europe/Stockholm
Europe/Tallinn
Europe/Tirane
Europe/Ulyanovsk
Europe/Uzhgorod
Europe/Vienna
Europe/Vilnius
Europe/Volgograd
Europe/Warsaw
Europe/Zaporozhye
HST
Indian/Chagos
Indian/Cocos
Indian/Kerguelen
Indian/Mahe
Indian/Maldives
Indian/Mauritius
Indian/Reunion
Pacific/Kwajalein
MET
MST
MST7MDT
Pacific/Chatham
Pacific/Apia
Pacific/Bougainville
Pacific/Chuuk
Pacific/Efate
Pacific/Enderbury
Pacific/Fakaofo
Pacific/Fiji
Pacific/Galapagos
Pacific/Gambier
Pacific/Guadalcanal
Pacific/Guam
Pacific/Honolulu
Pacific/Kiritimati
Pacific/Kosrae
Pacific/Majuro
Pacific/Marquesas
Pacific/Pago_Pago
Pacific/Nauru
Pacific/Niue
Pacific/Norfolk
Pacific/Noumea
Pacific/Pitcairn
Pacific/Pohnpei
Pacific/Rarotonga
Pacific/Tahiti
Pacific/Tongatapu
PST8PDT
WET