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:

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 UnitPossible 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:

UnitTokenOutput

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

Last updated