Date and math workflow helpers

See related

No related articles

Last Update: Dec 2024 • Est. Read Time: 4 MIN

To check plan availability, see the pricing page.

Date and math helpers allow you to build, format, and make calculations, based on dates and numbers, within your workflows.

Date

The {{date}} workflow helper generates a date based on the current time, using the standard date object format of YYYY-MM-DDTHH:MM:SS.SSSZ. This is commonly used for time comparison. For example, conversations configured to send an auto-response might use a custom date attribute to track when an auto-response was last sent.

Below are examples of different options for generating dates and how they can be adjusted to fit your needs:

{{date 'days' count=0}} resolves to the current day
{{date 'days' count=1}} resolves to 1 day ago
{{date 'hour' count=-24}} resolves to 24 hours from now

The following longhand units of time are supported:

year or years
day or days
hour or hours
minute or minutes

In Business Hours

The /#fn:inBusinessHours function helper checks whether a date falls within a team's operational business hours, as defined in Settings > Administration > Business Schedules. It is commonly used in condition steps to help determine if and when specific actions should be executed.

This helper accepts two optional parameters: A date (in standard date-object notation), and a business schedule ID.

Given steps.1.createdAt = "2034-01-01T00:00:00.000Z", AND a business schedule ID of "61785fb332a97930e6ab85d2"
/#fn:inBusinessHours,steps.1.createdAt,61785fb332a97930e6ab85d2 resolves to the boolean value false ,if Sundays are excluded from the business schedule

If no date is provided, the helper compares against the current time. If no business schedule ID is provided, the helper will compare against the organization’s default schedule.

/#fn:inBusinessHours
/#fn:inBusinessHours,steps.1.createdAt
/#fn:inBusinessHours,61785fb332a97930e6ab85d2

Date Format (with Moment.js)

Date objects and other recognized date formats can be converted into a desire formats using Moment.js, a library that parses, validates, manipulates, and displays dates. You can customize the output by using any of the formatting parameters listed in their documentation.

You can find information on Moment.JS, including a wide variety of notated formatting options, in the following resources:

The {{dateFormat}} helper can be used to convert a date into a more user-friendly format. For example, an order date given in standard date-object notation can be converted into a format that is easier to read.

Given steps.1.attributes.data.orderDate = "2018-05-04T20:01:51.031Z"
{{dateFormat steps.1.attributes.data.orderDate}} resolves to the string "May 4, 2018", leveraging the “LL” format from moment.js as default.

The date given to the helper does not need to be in standard date-object notation to be reformatted, so long as it is in a recognized moment.js format. Any unrecognized format will simply result in the output of an empty string.

{{dateFormat '05/04/2018'}} resolves to the string "May 4, 2018"

An optional format parameter can be included to specify alternate output formats. All moment.js format notations are supported, and can even be strung together to build custom outputs, inserting additional text inside [brackets].

{{dateFormat 'May 4, 2018' format='dddd'}} resolves to the string "Friday"
{{dateFormat '5.4.18' format='dddd [the] Do [of] MMMM'}} resolves to the string "Friday the 4th of May"
{{dateFormat '2018-05-04 20:01' format='YYYY-MM-DD[T]HH:mm:ss.SSS[Z]]'}} resolves to the standard date object "2018-05-04T20:01:00.000Z"

Because dates are interpreted in Universal Coordinated Time (UTC), and output in a United States format by default, this helper may not display a date output in your desired timezone or language. To account for this, optional parameters for timezone, inputTimezone, and locale can also be utilized. timezone accepts a timezone abbreviation or region, and adjusts the input date for that timezone, inputTimezone identifies the input date as something other than UTC when making conversions (also by timezone abbreviation or region), and locale allows for outputs in non-English languages or regional conventions.

{{dateFormat '2018-05-04 20:01' format='MMMM Do YYYY, h:mma z' timezone='America/New_York' inputTimezone='GMT' locale='en-us'}} resolves to the string "May 4th 2018, 4:01pm EDT"
{{dateFormat '2018-05-04 20:01' format='MMMM Do YYYY, h:mma z' timezone='America/New_York' inputTimezone='GMT' locale='es'}} resolves to the string "mayo 4º 2018, 4:01pm EDT"

A variant /#fn:dateFormat function helper is also available, which outputs dates in date-object notation by default.

Given steps.1.attributes.data.orderDate = "2018-5-4"
/#fn:dateFormat,steps.1.attributes.data.orderDate resolves to the date object strong "2018-05-04T00:00:00.000Z"

Moment.js notation can be used for date formatting with this variant helper.

Given steps.1.attributes.data.orderDate = "05.04.18"
/#fn:dateFormat,steps.1.attributes.data.date,MMMM [the] Do, YYYY resolves to the string "May the 4th, 2018"

Date Diff

The {{dateDiff}} helper compares two dates (in standard date object notation) and calculates the difference between them. It outputs the result as a string based on the specified unit of time using the format {{dateDiff 'unit_of_time' from=date_1 to=date_2}}.

Within this helper, the from parameter is always subtracted from the to parameter. If either parameter is omitted from the statement, that value will default to the current time.

{{dateDiff 'years' from='2000-01-01T00:00:00.000Z' to='3000-01-01T00:00:00.000Z'}} resolves to the string "1000"
{{dateDiff 'years' from='3000-01-01T00:00:00.000Z' to='2000-01-01T00:00:00.000Z'}} resolves to the string "-1000"
{{dateDiff 'days' from=steps.1.lastDone.createdAt}} resolves to the stringified number of full days between the last done time and the current time.

This helper only counts fully elapsed units, and does not round up.

{{dateDiff 'days' from='2000-01-01T00:00:00.000Z' to='2000-01-01T23:59:59.999Z'}} resolves to the string "0"

The following longhand units of time are supported:

years
months
weeks
days
hours
minutes
seconds
milliseconds

Math

The {{math}} workflow helper allows basic arithmetic operations to be performed within a workflow step. The result is calculated by accepting two numbers (or their string representations) and an operator as arguments, and output as a stringified numerical value.

Given steps.1.custom = {"num9": 9, "num4": 4}
{{math steps.1.custom.num9 '+' steps.1.custom.num4}} resolves to the string "13"
{{math 9 '-' 4}} resolves to the string "5"
{{math 9 '*' '4'}} resolves to the string "36"

The following operators are supported:

+ (addition)
- (subtraction)
* (multiplication)
/ (division)
% (modulo)

To convert a stringified number to an literal number value, see the /#fn:parseInt and /#fn:parseFloat functions helpers under JSON Data Helpers. JSON data helpers.

Format Currency

The {{formatCurrency}} helper takes a literal or stringified number and outputs a string value using standard currency code formatting. An optional currency parameter defaults to "USD", and an optional locale parameter can be used to customize the format according to region.

{{formatCurrency 1234.56}} resolves to the string "$1,234.56"
{{formatCurrency 1234.56 currency='EUR'}} resolves to the string "€1,234.56"
{{formatCurrency '1234.56' currency='EUR' locale='de-DE'}} resolves to the string "1.234,56 €"

Numbers with decimal values outside the included range of the specified format will be rounded up or down to that format’s nearest accepted value.

Given steps.1.custom = {"number": 1234.56, "currency": "JPY"}
{{formatCurrency steps.1.custom.number currency=steps.1.custom.currency}} resolves to the string "¥1,235"

This helper will only format the numeric portion of a string up to the first non-numeric character (excluding a decimal point).

{{formatCurrency '1,234.56'}} resolves to the string "$1.00"
{{formatCurrency '#1234.56'}} resolves to an empty string

Workflow helpers