Date and time with Luxon#

Luxon is a JavaScript library that makes it easier to work with date and time. For full details of how to use Luxon, refer to Luxon's documentation.

SMS-iT Workflow passes dates between nodes as strings, so you need to parse them. Luxon makes this easier.

Python support

Luxon is a JavaScript library. The two convenience variables created by SMS-iT Workflow are available when using Python in the Code node, but their functionality is limited:

  • You can't perform Luxon operations on these variables. For example, there is no Python equivalent for $today.minus(...).
  • The generic Luxon functionality, such as Convert date string to Luxon, isn't available for Python users.

Variables#

SMS-iT Workflow uses Luxon to provide two custom variables:

  • now: a Luxon object containing the current timestamp. Equivalent to DateTime.now().
  • today: a Luxon object containing the current timestamp, rounded down to the day. Equivalent to DateTime.now().set({ hour: 0, minute: 0, second: 0, millisecond: 0 }).

Note that these variables can return different time formats when cast as a string. This is the same behavior as Luxon's DateTime.now().

1
2
3
4
5
6
{{$now}}
// SMS-iT Workflow displays the ISO formatted timestamp
// For example 2022-03-09T14:02:37.065+00:00
{{"Today's date is " + $now}}
// SMS-iT Workflow displays "Today's date is <unix timestamp>"
// For example "Today's date is 1646834498755"

1
2
3
4
5
6
$now
// SMS-iT Workflow displays <ISO formatted timestamp>
// For example 2022-03-09T14:00:25.058+00:00
let rightNow = "Today's date is " + $now
// SMS-iT Workflow displays "Today's date is <unix timestamp>"
// For example "Today's date is 1646834498755"

1
2
3
4
5
6
_now
# SMS-iT Workflow displays <ISO formatted timestamp>
# For example 2022-03-09T14:00:25.058+00:00
rightNow = "Today's date is " + str(_now)
# SMS-iT Workflow displays "Today's date is <unix timestamp>"
# For example "Today's date is 1646834498755"

SMS-iT Workflow provides built-in convenience functions to support data transformation in expressions for dates. Refer to Data transformation functions | Dates for more information.

Date and time behavior in SMS-iT Workflow#

Be aware of the following:

  • In a workflow, SMS-iT Workflow converts dates and times to strings between nodes. Keep this in mind when doing arithmetic on dates and times from other nodes.
  • With vanilla JavaScript, you can convert a string to a date with new Date('2019-06-23'). In Luxon, you must use a function explicitly stating the format, such as DateTime.fromISO('2019-06-23') or DateTime.fromFormat("23-06-2019", "dd-MM-yyyy").

Setting the timezone in SMS-iT Workflow#

Luxon uses the SMS-iT Workflow timezone. This value is either:

  • Default: America/New York
  • A custom timezone for your SMS-iT Workflow instance, set using the GENERIC_TIMEZONE environment variable.
  • A custom timezone for an individual workflow, configured in workflow settings.

Common tasks#

This section provides examples for some common operations. More examples, and detailed guidance, are available in Luxon's own documentation.

Convert date string to Luxon#

You can convert date strings and other date formats to a Luxon DateTime object. You can convert from standard formats and from arbitrary strings.

A difference between Luxon DateTime and JavaScript Date

With vanilla JavaScript, you can convert a string to a date with new Date('2019-06-23'). In Luxon, you must use a function explicitly stating the format, such as DateTime.fromISO('2019-06-23') or DateTime.fromFormat("23-06-2019", "dd-MM-yyyy").

If you have a date in a supported standard technical format:#

Most dates use fromISO(). This creates a Luxon DateTime from an ISO 8601 string. For example:

1
{{DateTime.fromISO('2019-06-23T00:00:00.00')}}

1
let luxonDateTime = DateTime.fromISO('2019-06-23T00:00:00.00')

Luxon's API documentation has more information on fromISO.

Luxon provides functions to handle conversions for a range of formats. Refer to Luxon's guide to Parsing technical formats for details.

If you have a date as a string that doesn't use a standard format:#

Use Luxon's Ad-hoc parsing. To do this, use the fromFormat() function, providing the string and a set of tokens that describe the format.

For example, you have SMS-iT Workflow's founding date, 23rd June 2019, formatted as 23-06-2019. You want to turn this into a Luxon object:

1
{{DateTime.fromFormat("23-06-2019", "dd-MM-yyyy")}}

1
let newFormat = DateTime.fromFormat("23-06-2019", "dd-MM-yyyy")

When using ad-hoc parsing, note Luxon's warning about Limitations. If you see unexpected results, try their Debugging guide.

Get n days from today#

Get a number of days before or after today.

For example, you want to set a field to always show the date seven days before the current date.

In the expressions editor, enter:

1
{{$today.minus({days: 7})}}

On the 23rd June 2019, this returns [Object: "2019-06-16T00:00:00.000+00:00"].

This example uses SMS-iT Workflow's custom variable $today for convenience. It's the equivalent of DateTime.now().set({ hour: 0, minute: 0, second: 0, millisecond: 0 }).minus({days: 7}).

For example, you want a variable containing the date seven days before the current date.

In the code editor, enter:

1
let sevenDaysAgo = $today.minus({days: 7})

On the 23rd June 2019, this returns [Object: "2019-06-16T00:00:00.000+00:00"].

This example uses SMS-iT Workflow's custom variable $today for convenience. It's the equivalent of DateTime.now().set({ hour: 0, minute: 0, second: 0, millisecond: 0 }).minus({days: 7}).

For more detailed information and examples, refer to:

Create human-readable dates#

In Get n days from today, the example gets the date seven days before the current date, and returns it as [Object: "yyyy-mm-dd-T00:00:00.000+00:00"] (for expressions) or yyyy-mm-dd-T00:00:00.000+00:00 (in the Code node). To make this more readable, you can use Luxon's formatting functions.

For example, you want the field containing the date to be formatted as DD/MM/YYYY, so that on the 23rd June 2019, it returns 23/06/2019.

This expression gets the date seven days before today, and converts it to the DD/MM/YYYY format.

1
{{$today.minus({days: 7}).toLocaleString()}}

1
let readableSevenDaysAgo = $today.minus({days: 7}).toLocaleString()

You can alter the format. For example:

1
{{$today.minus({days: 7}).toLocaleString({month: 'long', day: 'numeric', year: 'numeric'})}}

On 23rd June 2019, this returns "16 June 2019".

1
let readableSevenDaysAgo = $today.minus({days: 7}).toLocaleString({month: 'long', day: 'numeric', year: 'numeric'})

On 23rd June 2019, this returns "16 June 2019".

Refer to Luxon's guide on toLocaleString (strings for humans) for more information.

Get the time between two dates#

To get the time between two dates, use Luxon's diffs feature. This subtracts one date from another and returns a duration.

For example, get the number of months between two dates:

1
{{DateTime.fromISO('2019-06-23').diff(DateTime.fromISO('2019-05-23'), 'months').toObject()}}

This returns [Object: {"months":1}].

1
let monthsBetweenDates = DateTime.fromISO('2019-06-23').diff(DateTime.fromISO('2019-05-23'), 'months').toObject()

This returns {"months":1}.

Refer to Luxon's Diffs for more information.

A longer example: How many days to Christmas?#

This example brings together several Luxon features, uses JMESPath, and does some basic string manipulation.

The scenario: you want a countdown to 25th December. Every day, it should tell you the number of days remaining to Christmas. You don't want to update it for next year - it needs to seamlessly work for every year.

1
{{"There are " + $today.diff(DateTime.fromISO($today.year + '-12-25'), 'days').toObject().days.toString().substring(1) + " days to Christmas!"}}

This outputs "There are <number of days> days to Christmas!". For example, on 9th March, it outputs "There are 291 days to Christmas!".

A detailed explanation of what the expression does:

  • {{: indicates the start of the expression.
  • "There are ": a string.
  • +: used to join two strings.
  • $today.diff(): This is similar to the example in Get the time between two dates, but it uses SMS-iT Workflow's custom $today variable.
  • DateTime.fromISO($today.year + '-12-25'), 'days': this part gets the current year using $today.year, turns it into an ISO string along with the month and date, and then takes the whole ISO string and converts it to a Luxon DateTime data structure. It also tells Luxon that you want the duration in days.
  • toObject() turns the result of diff() into a more usable object. At this point, the expression returns [Object: {"days":-<number-of-days>}]. For example, on 9th March, [Object: {"days":-291}].
  • .days uses JMESPath syntax to retrieve just the number of days from the object. For more information on using JMESPath with SMS-iT Workflow, refer to our JMESpath documentation. This gives you the number of days to Christmas, as a negative number.
  • .toString().substring(1) turns the number into a string and removes the -.
  • + " days to Christmas!": another string, with a + to join it to the previous string.
  • }}: indicates the end of the expression.
1
let daysToChristmas = "There are " + $today.diff(DateTime.fromISO($today.year + '-12-25'), 'days').toObject().days.toString().substring(1) + " days to Christmas!";

This outputs "There are <number of days> days to Christmas!". For example, on 9th March, it outputs "There are 291 days to Christmas!".

A detailed explanation of what the code does:

  • "There are ": a string.
  • +: used to join two strings.
  • $today.diff(): This is similar to the example in Get the time between two dates, but it uses SMS-iT Workflow's custom $today variable.
  • DateTime.fromISO($today.year + '-12-25'), 'days': this part gets the current year using $today.year, turns it into an ISO string along with the month and date, and then takes the whole ISO string and converts it to a Luxon DateTime data structure. It also tells Luxon that you want the duration in days.
  • toObject() turns the result of diff() into a more usable object. At this point, the expression returns [Object: {"days":-<number-of-days>}]. For example, on 9th March, [Object: {"days":-291}].
  • .days uses JMESPath syntax to retrieve just the number of days from the object. For more information on using JMESPath with SMS-iT Workflow, refer to our JMESpath documentation. This gives you the number of days to Christmas, as a negative number.
  • .toString().substring(1) turns the number into a string and removes the -.
  • + " days to Christmas!": another string, with a + to join it to the previous string.