Date Module

Everything your workflow needs to read, parse, format, compare, and calculate dates and times — without writing code.

The Date Module adds twenty-three single-purpose Tasks: read the current time, normalize user-typed dates, format dates for messages in the customer's language and time zone, add and subtract durations, route on business hours and SLA deadlines, and turn raw timestamps into friendly phrases like "in 3 days". Environment configuration is optional — every setting has a sensible default and every Task can override it.

How it works

Read this once; every Task on this page follows the same rules.

• Accepted input formats. Every date field accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
• Every output is ISO-8601 UTC. Whatever you feed in, date outputs are stored in the Session as ISO-8601 UTC (for example 2026-03-25T10:00:00Z), so any later Task can read them without guessing the format. Only FormatDate, HumanizeDuration, RelativeTimePhrase, and ExtractDatePart produce human-readable text instead.
• All times use the 24-hour clock. Type 17:00, not 5:00 PM — in schedule fields, format patterns (HH is the 24-hour hour), and date strings alike.
• Locale fallback chain. Wherever a Locale field exists: if empty, the platform uses this field → the conversation language → the module's Default locale → en-US.
• Weekend and holiday day names are English. Fields that list days of the week take comma-separated English day names, e.g. Saturday,Sunday, regardless of locale. Holiday dates are yyyy-MM-dd.
• Natural-language input is not supported. Phrases like tomorrow or next Friday are rejected. Use ParseDate on real date strings, or build relative dates with Now + AddDuration.
• Show advanced settings. Most Tasks keep their optional overrides (time zone, locale, weekend days, holidays, test anchors) hidden behind a Show advanced settings switch in the Task configuration. Leave it off to use the module defaults; turn it on to reveal and override those fields. The property tables below list the advanced fields — they appear once the switch is on.

Configuration

Per-Environment defaults. Every Task accepts the same fields as overrides; when a Task leaves them empty, these defaults apply.

Field	Required	Default	Example	Description
Default time zone	No	UTC	Europe/Rome	IANA or Windows time zone id used when a Task does not specify one. Leave blank for UTC.
Default locale	No	en-US	en-US	Language/region tag used when a Task's Locale field is empty and the conversation has no language.
Week starts on	No	Monday	Monday	First day of the week for StartOf / EndOf (week). Options: Monday, Sunday, Saturday.
Weekend days	No	Saturday,Sunday	Saturday,Sunday	Comma-separated English day names treated as weekend by business-day Tasks. Day names are always English regardless of locale.
Holiday calendar (yyyy-MM-dd)	No	empty	2026-01-01,2026-04-25,2026-12-25	Dates to treat as non-working days, yyyy-MM-dd, comma- or newline-separated. Used by IsBusinessDay, AddBusinessDays, NextBusinessDay, SLADeadline, and IsWithinSchedule when their Holidays field is empty.

All Tasks in this module are generic — they behave the same on every Channel.

Tasks

Now

Reads the current instant and writes it to a Session variable — the seed for any downstream date arithmetic, SLA timer, or audit stamp.

Properties

Property	Required	Example	Notes
Format	No	iso	Default: iso (ISO-8601 UTC). Built-in: iso, iso-local, unix, unix-ms, rfc1123, date, long-date, time, long-time — or any custom .NET format string such as dd MMM yyyy HH:mm (HH is the 24-hour hour). Times use the 24-hour clock (type 17:00, not 5:00 PM).
Time zone (optional)	No	Europe/Rome	IANA or Windows time zone id used when Format is locale-aware (e.g. date, long-date). Default: the module's Default time zone (UTC).
Locale (optional)	No	en-US	Used by locale-aware formats. Language/region tag, e.g. en-US, it-IT. If empty, the platform uses: this field → the conversation language → the module's Default locale → en-US.
Output variable	Yes	now	Variable name (no braces) that receives the formatted current datetime. Later Tasks read it as {now}.

Behavior

1. The Task reads the current time.
2. It renders it using Format, Time zone, and Locale.
3. It writes the result to the output variable.

Example

Format iso, output variable now. When the Task runs at 08:30 UTC on 10 June 2026, {now} becomes 2026-06-10T08:30:00Z. A later AddDuration Task can then compute {now} + 24 hours for a reminder.

ParseDate

Turns a free-form date string — typically typed by a user — into a clean ISO-8601 UTC value that every later Task can rely on.

Properties

Property	Required	Example	Notes
Input	Yes	25/12/2026 18:00 or {userInput}	The raw date string to normalize. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Explicit format (optional)	No	dd/MM/yyyy HH:mm	Strict contract: when set, the input must match this exact pattern or the Task fails — use it when you know exactly how the date arrives. When blank, the parser auto-detects. Times use the 24-hour clock (type 17:00, not 5:00 PM).
Source time zone	No	Europe/Rome	Time zone the input is expressed in — used only when the string itself has no zone indicator. Default: the module's Default time zone (UTC).
Locale	No	it-IT	Used to interpret culture-formatted inputs (month names, separators). Language/region tag, e.g. en-US, it-IT. If empty, the platform uses: this field → the conversation language → the module's Default locale → en-US.
Output variable	Yes	parsedDate	Variable name (no braces) that receives the ISO-8601 UTC string.

Behavior

1. The Task reads the Input string (resolving any {variable} placeholders).
2. It detects the format — or enforces Explicit format when set — and interprets zone-less values in the Source time zone.
3. It writes the normalized ISO-8601 UTC value to the output variable.

Example

Input 25/12/2026 18:00, Locale it-IT, Source time zone Europe/Rome, output variable parsedDate. Result: {parsedDate} = 2026-12-25T17:00:00Z (18:00 in Rome is 17:00 UTC in December).

warning

Natural-language phrases like tomorrow, next Friday, or domani are not supported and will fail to parse. Build relative dates with Now + AddDuration instead.

BuildDate

Assembles an ISO-8601 UTC datetime from individual year / month / day / hour / minute / second values — each can come from a {variable}.

Properties

Property	Required	Example	Notes
Year	Yes	2026 or {year}	Four digits.
Month	Yes	12 or {month}	1–12.
Day	Yes	25 or {day}	1–31; must exist in the chosen month.
Hour	No	18 or {hour}	0–23, 24-hour clock. Times use the 24-hour clock (type 17:00, not 5:00 PM). Default: 0.
Minute	No	30 or {minute}	0–59. Default: 0.
Second	No	0 or {second}	0–59. Default: 0.
Time zone	No	Europe/Rome	IANA or Windows time zone id the supplied components are expressed in. Default: the module's Default time zone (UTC).
Output variable	Yes	builtDate	Variable name (no braces) that receives the ISO-8601 UTC datetime.

Behavior

1. The Task resolves each component (numbers or {variables}).
2. It combines them into a datetime in the given Time zone.
3. It converts to UTC and writes the ISO-8601 value to the output variable.

Example

Year 2026, Month 12, Day 25, Hour 18, Time zone Europe/Rome, output variable builtDate. Result: {builtDate} = 2026-12-25T17:00:00Z.

FormatDate

Renders a stored datetime as a user-facing string. Use it immediately before placing a date into an SMS, email, voice prompt, or chat reply so the customer sees their local time and language.

Properties

Property	Required	Example	Notes
Input date	Yes	2026-03-25T10:00:00Z or {appointmentUtc}	The datetime to format. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Pattern	No	dd MMM yyyy HH:mm or long-date	Default: long-date. Built-in: iso, iso-local, unix, unix-ms, rfc1123, date, long-date, time, long-time — or any .NET format string (HH is the 24-hour hour). Times use the 24-hour clock (type 17:00, not 5:00 PM).
Time zone	No	Europe/Rome	Time zone the output should reflect. Default: the module's Default time zone (UTC).
Locale	No	it-IT	Used for month names, weekday names, separators. Language/region tag, e.g. en-US, it-IT. If empty, the platform uses: this field → the conversation language → the module's Default locale → en-US.
Output variable	Yes	prettyDate	Variable name (no braces) that receives the formatted string.

Behavior

1. The Task parses Input date.
2. It converts it to the requested Time zone.
3. It renders it with Pattern and Locale and writes the string to the output variable.

Example

Input date {appointmentUtc} = 2026-05-25T12:30:00Z, Pattern dddd d MMMM HH:mm, Locale it-IT, Time zone Europe/Rome, output variable prettyDate. Result: {prettyDate} = lunedì 25 maggio 14:30 — ready to drop into a message.

ConvertTimeZone

Re-expresses a datetime in another time zone — for when an upstream system reports times in one zone and a downstream system expects another.

Properties

Property	Required	Example	Notes
Input date	Yes	2026-12-25T17:00:00Z or {eventUtc}	The datetime to convert. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
From time zone	No	UTC	Used only when the input string has no zone indicator. Default: the module's Default time zone (UTC).
To time zone	Yes	America/New_York	IANA or Windows time zone id the output should reflect.
Output variable	Yes	localTime	Variable name (no braces) that receives the converted ISO-8601 datetime, written with the target zone's offset (or Z when the target is UTC).

Behavior

1. The Task parses Input date, applying From time zone if the value has no zone indicator.
2. It converts the instant to To time zone.
3. It writes the ISO-8601 result, including the target offset, to the output variable.

Example

Input date 2026-12-25T17:00:00Z, To time zone America/New_York, output variable localTime. Result: {localTime} = 2026-12-25T12:00:00-05:00.

ExtractDatePart

Pulls one component out of a datetime — the year, the quarter, the localized weekday name, and so on.

Properties

Property	Required	Example	Notes
Input date	Yes	2026-03-25T10:00:00Z or {now}	The datetime to inspect. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Part	Yes	WeekdayName	Default: Year. Options: Year, Month, Day, Hour, Minute, Second, Weekday, WeekdayName, Quarter, IsoWeek, DayOfYear. WeekdayName is localized text; everything else is a number.
Time zone	No	Europe/Rome	Zone the part is computed in, so Day reflects local midnight. Default: the module's Default time zone (UTC).
Locale	No	it-IT	Used for WeekdayName. Language/region tag, e.g. en-US, it-IT. If empty, the platform uses: this field → the conversation language → the module's Default locale → en-US.
Output variable	Yes	weekday	Variable name (no braces) that receives the part value.

Behavior

1. The Task parses Input date and converts it to the given Time zone.
2. It extracts the requested Part.
3. It writes the value (number, or localized weekday name) to the output variable.

Example

Input date 2026-05-25T12:30:00Z, Part WeekdayName, Locale it-IT, output variable weekday. Result: {weekday} = lunedì.

AddDuration

Shifts a datetime forward (or backward, with a negative amount) by a number of seconds, minutes, hours, days, weeks, months, or years.

Properties

Property	Required	Example	Notes
Input date	Yes	2026-03-25T10:00:00Z or {appointmentUtc}	The datetime to shift. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Amount	Yes	24 or {hoursToAdd}	Signed integer; may be negative. Supports {variables}.
Unit	Yes	Hours	Default: Hours. Options: Seconds, Minutes, Hours, Days, Weeks, Months, Years.
Output variable	Yes	shiftedDate	Variable name (no braces) that receives the shifted ISO-8601 UTC datetime.

Behavior

1. The Task parses Input date and the Amount.
2. It adds Amount × Unit. Months and Years use calendar arithmetic — 31 January + 1 month is 28/29 February, not "30 days later".
3. It writes the shifted ISO-8601 UTC value to the output variable.

Example

A 24-hour reminder: Input date {appointmentUtc} = 2026-03-25T10:00:00Z, Amount -1, Unit Days, output variable remindAt. Result: {remindAt} = 2026-03-24T10:00:00Z.

SubtractDuration

Shifts a datetime backward by a positive amount — the same as AddDuration with a negative amount, kept separate so the diagram reads naturally.

Properties

Property	Required	Example	Notes
Input date	Yes	2026-03-25T17:00:00Z or {deadline}	The datetime to shift backwards. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Amount	Yes	2 or {hoursBack}	Positive integer. Supports {variables}.
Unit	Yes	Hours	Default: Hours. Options: Seconds, Minutes, Hours, Days, Weeks, Months, Years.
Output variable	Yes	cutoff	Variable name (no braces) that receives the shifted ISO-8601 UTC datetime.

Behavior

1. The Task parses Input date and the Amount.
2. It subtracts Amount × Unit, using calendar arithmetic for Months and Years.
3. It writes the shifted ISO-8601 UTC value to the output variable.

Example

Escalation cutoff two hours before a deadline: Input date {deadline} = 2026-03-25T17:00:00Z, Amount 2, Unit Hours, output variable cutoff. Result: {cutoff} = 2026-03-25T15:00:00Z.

DateDiff

Measures the distance between two datetimes (Date B minus Date A) in the unit you choose.

Properties

Property	Required	Example	Notes
Date A (from)	Yes	2026-03-18T10:00:00Z or {createdAt}	Start datetime. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Date B (to)	Yes	2026-03-25T16:00:00Z or {now}	End datetime. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Unit	Yes	Days	Default: Days. Options: Seconds, Minutes, Hours, Days, Weeks, Months, Years. Fixed units can return fractions (e.g. 7.25 days); Months / Years walk the calendar.
Mode	No	Signed	Default: Signed (B − A, can be negative). Absolute returns the unsigned magnitude.
Precision	No	2	Default: 2. Decimal places kept, 0–6. Precision 0 returns an integer (truncated toward zero).
Output variable	Yes	daysOpen	Variable name (no braces) that receives the numeric difference (a number, not text).

Behavior

1. The Task parses both dates.
2. It computes Date B minus Date A in the chosen Unit, applies Mode and Precision.
3. It writes the number to the output variable.

Example

Date A (from) {createdAt} = 2026-03-18T10:00:00Z, Date B (to) {now} = 2026-03-25T16:00:00Z, Unit Days, Mode Signed, Precision 2, output variable daysOpen. Result: {daysOpen} = 7.25.

RoundDate

Snaps a datetime onto a regular grid — time slots, top of the hour, whole days.

Properties

Property	Required	Example	Notes
Input date	Yes	2026-03-25T10:07:42Z or {event}	The datetime to round. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Nearest amount	Yes	15	Default: 15. Size of the rounding interval, 1–1440, in Nearest unit.
Nearest unit	Yes	Minutes	Default: Minutes. Options: Seconds, Minutes, Hours, Days.
Direction	No	nearest	Default: nearest (closest boundary). down always rounds earlier (floor); up always rounds later (ceiling).
Output variable	Yes	slot	Variable name (no braces) that receives the rounded ISO-8601 UTC datetime.

Recipes

Goal	Nearest amount	Nearest unit
Nearest 15 minutes (09:00, 09:15, 09:30, …)	15	Minutes
Top of the hour	1	Hours
Whole day	1	Days

To round to a unit boundary, use amount 1 of the bigger unit — top of the hour is 1 Hours, not "Minutes nearest 00".

Behavior

1. The Task parses Input date.
2. It snaps it onto the grid defined by Nearest amount × Nearest unit, in the chosen Direction.
3. It writes the rounded ISO-8601 UTC value to the output variable.

Example

Input date 2026-03-25T10:07:42Z, Nearest amount 15, Nearest unit Minutes, Direction nearest, output variable slot. Result: {slot} = 2026-03-25T10:15:00Z (07:42 past the hour is closer to 10:15 than 10:00).

StartOf

Returns the start of the day, week, month, quarter, or year that contains a datetime — the anchor for "this month so far" reports and recurring windows.

Properties

Property	Required	Example	Notes
Input date	Yes	2026-06-10T08:30:00Z or {now}	The datetime to bucket. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Period	Yes	week	Default: day. Options: day → 00:00 of the same day; week → start of week (see Week starts on); month → the 1st at 00:00; quarter → first day of the quarter at 00:00; year → 1 January at 00:00.
Week starts on	No	Monday	Used only when Period = week. Options: Monday, Sunday, Saturday. Default: the module's Week starts on (Monday).
Time zone	No	Europe/Rome	Zone the boundary is computed in, so day aligns to local midnight. Default: the module's Default time zone (UTC).
Output variable	Yes	weekStart	Variable name (no braces) that receives the period-start ISO-8601 UTC datetime.

Behavior

1. The Task parses Input date and converts it to the given Time zone.
2. It finds the start of the containing Period.
3. It writes that instant, converted back to ISO-8601 UTC, to the output variable.

Example

Input date {now} = 2026-06-10T08:30:00Z (a Wednesday), Period week, Week starts on Monday, Time zone Europe/Rome, output variable weekStart. Result: {weekStart} = 2026-06-07T22:00:00Z — Monday 8 June at 00:00 in Rome, expressed in UTC.

EndOf

Returns the end of the day, week, month, quarter, or year that contains a datetime — the last instant before the next period begins.

Properties

Property	Required	Example	Notes
Input date	Yes	2026-06-10T08:30:00Z or {now}	The datetime to bucket. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Period	Yes	month	Default: day. Options: day → last instant of the same day; week → last instant of the week (see Week starts on); month, quarter, year → last instant of that period.
Week starts on	No	Monday	Used only when Period = week. Options: Monday, Sunday, Saturday. Default: the module's Week starts on (Monday).
Time zone	No	Europe/Rome	Zone the boundary is computed in. Default: the module's Default time zone (UTC).
Output variable	Yes	monthEnd	Variable name (no braces) that receives the period-end ISO-8601 UTC datetime.

Behavior

1. The Task parses Input date and converts it to the given Time zone.
2. It finds the last instant of the containing Period (the familiar 23:59:59.9999999 shape — one tick before the next period starts).
3. It writes that instant, converted back to ISO-8601 UTC, to the output variable.

Example

Input date {now} = 2026-06-10T08:30:00Z, Period month, Time zone UTC, output variable monthEnd. Result: {monthEnd} = 2026-06-30T23:59:59.9999999Z.

CompareDates

A gateway Task: compares two datetimes and routes the Token to one of four branches — a one-step replacement for DateDiff + SwitchTask.

Branches

Route value	Fires when
within	Tolerance amount is greater than 0 and the two dates are no further apart than the tolerance (checked first).
before	Date A is earlier than Date B.
after	Date A is later than Date B.
equal	The two dates are exactly the same instant.

Label each outgoing Sequence Flow with the matching route value.

Properties

Property	Required	Example	Notes
Date A	Yes	2026-03-25T10:00:00Z or {deadline}	First datetime — before means A is earlier than B. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Date B	Yes	2026-03-25T10:03:00Z or {now}	Second datetime. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Tolerance amount	No	5	Default: 0 (tolerance check disabled). When greater than 0, dates closer than the tolerance route to within.
Tolerance unit	No	Minutes	Default: Minutes. Options: Seconds, Minutes, Hours, Days.

Behavior

1. The Task parses both dates.
2. If a tolerance is set and the dates are within it, the Token leaves on within.
3. Otherwise the Token leaves on before, after, or equal.

Example

Date A {deadline} = 2026-03-25T10:00:00Z, Date B {now} = 2026-03-25T10:03:00Z, Tolerance amount 5, Tolerance unit Minutes. The dates are 3 minutes apart — within the ±5-minute tolerance — so the Token leaves on the within branch.

IsExpired

A gateway Task: checks whether a validity window measured from a reference datetime has run out — a one-Task replacement for OTP, invite-link, and abandoned-cart checks.

Branches

Route value	Fires when
expired	Now minus Reference is at least the TTL.
valid	The window is still open.

Properties

Property	Required	Example	Notes
Reference	Yes	2026-03-25T10:00:00Z or {otpSentAt}	Moment the countdown starts from (e.g. when the OTP was sent). Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
TTL amount	Yes	5	Default: 5. How long the reference stays valid, in TTL unit.
TTL unit	Yes	Minutes	Default: Minutes. Options: Seconds, Minutes, Hours, Days, Weeks, Months, Years.
Now (optional)	No	2026-03-25T10:06:00Z or {now}	Test/override anchor — fixes the instant "now" is measured from. Leave blank to use the actual current time. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Time zone (optional)	No	Europe/Rome	Applied to Reference / Now values that have no zone indicator. Default: the module's Default time zone (UTC).

Behavior

1. The Task parses Reference (and Now, when set).
2. It compares the elapsed time against TTL amount × TTL unit.
3. The Token leaves on expired or valid.

Example

An OTP check: Reference {otpSentAt} = 2026-03-25T10:00:00Z, TTL amount 5, TTL unit Minutes. When the user replies at 10:06 UTC, 6 minutes have elapsed — the Token leaves on expired and the workflow asks for a new code.

IsWithinSchedule

A gateway Task: tests whether an instant falls inside a recurring weekly window — the go-to pattern for business-hours routing of inbound calls and messages.

Branches

Route value	Fires when
inside	The instant falls on an active weekday, between Start time and End time, and not on a holiday.
outside	Any other time — including holidays, even when the weekly window would be open.

Properties

Property	Required	Example	Notes
Time zone	Yes	Europe/Rome	Zone the Start/End times and weekdays are evaluated in.
Weekdays	No	Monday,Tuesday,Wednesday,Thursday,Friday	Comma-separated English day names the schedule is active on. Day names are always English regardless of locale. Default: empty = every day.
Start time	Yes	09:00	Local time the window opens, HH:mm. Default: 09:00. Times use the 24-hour clock (type 17:00, not 5:00 PM).
End time	Yes	17:00	Local time the window closes, HH:mm. Default: 17:00. Use 24:00 for end-of-day; when End is earlier than Start, the window wraps past midnight. Times use the 24-hour clock (type 17:00, not 5:00 PM).
Holidays (yyyy-MM-dd, optional)	No	2026-12-25,2026-01-01	Dates to treat as non-working days, yyyy-MM-dd, comma- or newline-separated, e.g. 2026-12-25. Empty = module default holiday calendar.
When (optional)	No	2026-06-10T14:00:00Z or {now}	Instant to test. Test/override anchor — fixes the instant "now" is measured from. Leave blank to use the actual current time. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.

Behavior

1. The Task takes the instant (When, or the moment the Task runs) and converts it to the schedule's Time zone.
2. If the local date is a holiday, the Token leaves on outside.
3. Otherwise it checks the weekday and the Start–End window and leaves on inside or outside.

Example

Office-hours routing: Time zone Europe/Rome, Weekdays Monday,Tuesday,Wednesday,Thursday,Friday, Start time 09:00, End time 17:00, Holidays 2026-12-25,2026-01-01. A call arrives on Wednesday 10 June 2026 at 14:00 UTC — that is 16:00 in Rome, inside the window — so the Token leaves on inside and the call is routed to a live agent; calls at any other time leave on outside and are handled by the bot.

IsBusinessDay

A gateway Task: classifies the calendar day an instant falls on — business day, weekend, or holiday. Use it to hold non-urgent sends until a working day.

Branches

Route value	Fires when
holiday	The local date is in the holiday list (checked first — a holiday on a Saturday routes here).
weekend	The day of the week is in the weekend set.
business	Any other day.

Properties

Property	Required	Example	Notes
Input date	Yes	2026-12-25T10:00:00Z or {now}	The datetime to test. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Time zone	No	Europe/Rome	Zone that decides which calendar day the instant falls on. Default: the module's Default time zone (UTC).
Weekend days	No	Saturday,Sunday	Comma-separated English day names, e.g. Saturday,Sunday. Day names are always English regardless of locale. Empty = module default.
Holidays (yyyy-MM-dd, optional)	No	2026-12-25,2026-01-01	Dates to treat as non-working days, yyyy-MM-dd, comma- or newline-separated, e.g. 2026-12-25. Empty = module default holiday calendar.

Behavior

1. The Task converts the instant to the given Time zone to find the local calendar day.
2. It checks holidays first, then weekend days.
3. The Token leaves on holiday, weekend, or business.

Example

Input date {now} = 2026-12-25T10:00:00Z, Time zone Europe/Rome, Holidays 2026-12-25,2026-01-01. 25 December is in the holiday list, so the Token leaves on holiday and the send is deferred.

AddBusinessDays

Shifts a datetime by a number of working days. Days configured as weekend or holiday are skipped and not counted — "3 business days" from a Wednesday lands on Monday, not Saturday. The local time-of-day is preserved.

Properties

Property	Required	Example	Notes
Input date	Yes	2026-06-10T09:00:00Z or {now}	The datetime the walk starts from. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Business days	Yes	3	Default: 1. Signed integer, −3650 to 3650; a negative value walks backwards.
Time zone	No	Europe/Rome	Zone that decides which calendar day each step lands on. Default: the module's Default time zone (UTC).
Weekend days	No	Saturday,Sunday	Comma-separated English day names, e.g. Saturday,Sunday. Day names are always English regardless of locale. Empty = module default.
Holidays (yyyy-MM-dd, optional)	No	2026-12-25	Dates to treat as non-working days, yyyy-MM-dd, comma- or newline-separated, e.g. 2026-12-25. Empty = module default holiday calendar.
Output variable	Yes	dueDate	Variable name (no braces) that receives the shifted ISO-8601 UTC datetime.

Behavior

1. The Task parses Input date and walks the calendar one day at a time in the given Time zone.
2. Every day that is a configured weekend day or holiday is skipped and does not count toward the total.
3. It writes the landing datetime — same local clock time — to the output variable as ISO-8601 UTC.

Example

"Reply within 3 business days": Input date {now} = 2026-06-10T09:00:00Z (a Wednesday), Business days 3, Weekend days Saturday,Sunday, output variable dueDate. The walk counts Thursday (1), Friday (2), skips Saturday and Sunday without counting them, and lands on Monday (3). Result: {dueDate} = 2026-06-15T09:00:00Z.

NextBusinessDay

Rolls a datetime forward to the next working day — for deferring non-urgent reminders that would otherwise fire on a weekend or holiday.

Properties

Property	Required	Example	Notes
Input date	Yes	2026-06-13T09:00:00Z or {remindAt}	The datetime to roll forward. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
If already a business day	No	same	Default: same — keep the input when it is already a business day. next always moves forward at least one business day.
Time zone	No	Europe/Rome	Zone that decides which calendar day each step lands on. Default: the module's Default time zone (UTC).
Weekend days	No	Saturday,Sunday	Comma-separated English day names, e.g. Saturday,Sunday. Day names are always English regardless of locale. Empty = module default.
Holidays (yyyy-MM-dd, optional)	No	2026-12-25	Dates to treat as non-working days, yyyy-MM-dd, comma- or newline-separated, e.g. 2026-12-25. Empty = module default holiday calendar.
Output variable	Yes	sendAt	Variable name (no braces) that receives the resolved ISO-8601 UTC datetime.

Behavior

1. The Task checks whether the input's local calendar day is a business day.
2. With same, an input already on a business day is returned unchanged; with next, it always moves forward at least one business day.
3. It writes the resulting datetime — same local clock time — to the output variable.

Example

Input date 2026-06-13T09:00:00Z (a Saturday), If already a business day same, output variable sendAt. Result: {sendAt} = 2026-06-15T09:00:00Z — Monday, same clock time.

SLADeadline

A gateway Task: computes a deadline (start + SLA window), stores it in a variable, and immediately routes on whether the deadline has been met — one Task replaces a manual add-then-compare pair.

Branches

Route value	Fires when
met	Now is at or before the computed deadline.
breached	Now is past the computed deadline.

Properties

Property	Required	Example	Notes
Start	Yes	2026-06-12T15:00:00Z or {ticketCreatedAt}	Moment the SLA clock starts. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
SLA amount	Yes	8	Default: 24. Length of the SLA window, in SLA unit.
SLA unit	Yes	Hours	Default: Hours. Options: Minutes, Hours, Days.
Mode	No	business	Default: calendar (every hour counts). business skips configured weekend days and holidays while accruing the SLA; in business mode use Days or Hours (minutes are treated as calendar time).
Time zone	No	Europe/Rome	Zone that decides which calendar day each business-mode step lands on. Default: the module's Default time zone (UTC).
Now (optional)	No	2026-06-15T10:00:00Z or {now}	Test/override anchor — fixes the instant "now" is measured from. Leave blank to use the actual current time. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Weekend days	No	Saturday,Sunday	Comma-separated English day names, e.g. Saturday,Sunday. Day names are always English regardless of locale. Empty = module default. Used by business mode.
Holidays (yyyy-MM-dd)	No	2026-12-25	Dates to treat as non-working days, yyyy-MM-dd, comma- or newline-separated, e.g. 2026-12-25. Empty = module default holiday calendar. Used by business mode.
Deadline variable	Yes	slaDeadline	Variable name (no braces) that receives the computed deadline as ISO-8601 UTC.

Behavior

1. The Task computes Start + SLA amount × SLA unit — counting every hour in calendar mode, or skipping weekends and holidays in business mode.
2. It writes the deadline to the deadline variable.
3. It compares the deadline against now (or the Now override) and the Token leaves on met or breached.

Example

A 2-business-day response SLA: Start {ticketCreatedAt} = 2026-06-12T15:00:00Z (a Friday), SLA amount 2, SLA unit Days, Mode business, Deadline variable slaDeadline. The walk skips Saturday and Sunday, so {slaDeadline} = 2026-06-16T15:00:00Z (Tuesday). If the Task runs on Monday, the Token leaves on met; on Wednesday it leaves on breached and the workflow escalates.

HumanizeDuration

Renders a duration as a friendly, localized phrase — "2 hours and 5 minutes", "2 ore e 5 minuti" — ready to drop into a chat or SMS reply. Feed it either a number of seconds or two datetimes.

Properties

Property	Required	Example	Notes
Seconds (optional)	One of	7500 or {ttlSeconds}	Duration in seconds — typically a {variable} produced by an earlier Task (e.g. DateDiff in Seconds). Leave blank to use Date A → Date B instead.
Date A (optional)	One of	2026-03-25T10:00:00Z or {from}	Start of the span, used with Date B when Seconds is empty. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Date B (optional)	One of	2026-03-25T12:05:00Z or {to}	End of the span, used with Date A when Seconds is empty. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Precision	No	2	Default: 2. How many components to render, 1–4: 1 → "2 hours"; 2 → "2 hours and 5 minutes".
Locale	No	it-IT	Language/region tag, e.g. en-US, it-IT. If empty, the platform uses: this field → the conversation language → the module's Default locale → en-US. Built-in wording covers en, it, fr, es, de; other locales render in English.
Output variable	Yes	expiresIn	Variable name (no braces) that receives the phrase.

Behavior

1. The Task takes the duration from Seconds, or computes Date B minus Date A when Seconds is empty.
2. It renders the duration with the requested Precision and Locale.
3. It writes the phrase to the output variable.

Example

Telling a user how long their code lasts: a DateDiff Task first computes the seconds between now and {otpExpiresAt} (Unit Seconds, Precision 0) into ttlSeconds, which lands on 7500. HumanizeDuration with Seconds {ttlSeconds}, Precision 2, Locale en-US, output variable expiresIn produces {expiresIn} = 2 hours and 5 minutes — so the reply reads "Your code expires in 2 hours and 5 minutes."

RelativeTimePhrase

Renders a datetime as a phrase relative to now — "in 3 days", "5 minutes ago", "tra 3 giorni".

Properties

Property	Required	Example	Notes
Input date	Yes	2026-06-13T08:30:00Z or {nextFireAt}	The datetime the phrase describes: future dates render as "in …", past dates as "… ago". Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Now (optional)	No	2026-06-10T08:30:00Z or {now}	Test/override anchor — fixes the instant "now" is measured from. Leave blank to use the actual current time. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Locale	No	it-IT	Language/region tag, e.g. en-US, it-IT. If empty, the platform uses: this field → the conversation language → the module's Default locale → en-US. Built-in wording covers en, it, fr, es, de.
Output variable	Yes	whenPhrase	Variable name (no braces) that receives the localized phrase.

Behavior

1. The Task measures the distance between Input date and now (or the Now override).
2. It renders a localized relative phrase.
3. It writes the phrase to the output variable.

Example

Input date {nextFireAt} = 2026-06-13T08:30:00Z, Locale en-US, output variable whenPhrase. Run on 10 June 2026 at 08:30 UTC, {whenPhrase} = in 3 days. The Now field is only a test/override anchor — leave it blank in production so the phrase tracks real time.

AgeInUnits

Returns how old a reference datetime is, as a whole number in the unit you pick — a person's age in years, an account's age in days.

Properties

Property	Required	Example	Notes
Reference	Yes	1994-03-25T00:00:00Z or {birthday}	Moment the age is measured from (birthday, signup, creation time). Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Unit	Yes	Years	Default: Years. Options: Seconds, Minutes, Hours, Days, Weeks, Months, Years.
As of (optional)	No	2026-06-10T00:00:00Z or {now}	Test/override anchor — fixes the instant "now" is measured from. Leave blank to use the actual current time. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Output variable	Yes	age	Variable name (no braces) that receives the integer age (a number, truncated toward zero — 32 years and 11 months is 32).

Behavior

1. The Task parses Reference (and As of, when set).
2. It measures the elapsed time in the chosen Unit and truncates to a whole number.
3. It writes the number to the output variable.

Example

Reference {birthday} = 1994-03-25T00:00:00Z, Unit Years, output variable age. Run on 10 June 2026, {age} = 32 — ready for an age-gate branch with a SwitchTask.

DateValidationGuard

A gateway Task: validates a user-supplied date in one step — parse it, check it against an allowed window, store the clean value, and route on the outcome.

Branches

Route value	Fires when
valid	The input parses and is inside the allowed window. The clean ISO-8601 UTC value is written to the output variable.
invalid	The input is empty or cannot be parsed as a date.
outOfRange	The input parses but falls before Min date or after Max date.

Properties

Property	Required	Example	Notes
Input	Yes	25/12/1989 or {userDob}	The date string to validate, typically user-supplied. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Explicit format (optional)	No	dd/MM/yyyy	Strict contract: when set, the input must match this exact pattern or the Token leaves on invalid — use it when you know exactly how the date arrives. Times use the 24-hour clock (type 17:00, not 5:00 PM).
Source time zone	No	Europe/Rome	Zone applied to inputs with no zone indicator. Default: the module's Default time zone (UTC).
Locale	No	it-IT	Used to interpret culture-formatted inputs (month names, separators). Language/region tag, e.g. en-US, it-IT. If empty, the platform uses: this field → the conversation language → the module's Default locale → en-US.
Min date (optional)	No	1900-01-01	The earliest date that still counts as valid — the bound itself is accepted (inclusive); anything earlier leaves on outOfRange. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Max date (optional)	No	{today}	The latest date that still counts as valid — the bound itself is accepted (inclusive); anything later leaves on outOfRange. Accepts: ISO-8601 (2026-03-25T10:00:00Z), unix seconds or milliseconds, RFC 1123, a locale-formatted date (set Locale), or a {variable}.
Output variable	Yes	dob	Variable name (no braces) that receives the parsed ISO-8601 UTC value — written only on the valid branch.

Behavior

1. The Task parses the Input (honoring Explicit format, Source time zone, and Locale).
2. Unparseable or empty input routes invalid; a parsed date outside [Min date, Max date] routes outOfRange.
3. On success it writes the clean ISO-8601 UTC value to the output variable and routes valid.

Example

Validating a date of birth: Input {userDob} = 25/12/1989, Locale it-IT, Min date 1900-01-01, Max date {today}, output variable dob. The input parses, 25 December 1989 is between the bounds, so {dob} = 1989-12-25T00:00:00Z and the Token leaves on valid. A typo like 25/13/1989 would leave on invalid; a future date like 25/12/2030 would leave on outOfRange — wire each branch to its own re-prompt message.

Common recipes

Escalate a ticket when its SLA is breached

Compute a business-hours response deadline for a ticket, tell the customer when to expect a reply, and hand the Session to a live agent the moment the deadline is missed — using the Standard Module's OutputTask and the Aculab Module's SendToAgentTask.

1. SLADeadline — Start {ticketCreatedAt}, SLA amount 8, SLA unit Hours, Mode business, Deadline variable slaDeadline. Label the two outgoing Sequence Flows met and breached.
2. met branch — FormatDate — Input date {slaDeadline}, Pattern dddd d MMMM HH:mm, Time zone Europe/Rome, Locale it-IT, output variable dueText.
3. OutputTask (Standard Module) — message: We're on it — you'll hear from us by {dueText}.
4. breached branch — SendToAgentTask (Aculab Module) — hands the Session to a live agent so a human picks up the overdue ticket immediately.

Remind a customer before their appointment

Validate a user-typed appointment date and schedule a reminder 24 hours before it, using the Standard Module's InputTask/OutputTask and the Scheduler Module's ScheduleReminder.

1. Now — Format iso, output variable now — captures the current instant to use as the validity lower bound.
2. InputTask (Standard Module) — asks "When is your appointment?" and stores the reply in appointmentDate.
3. DateValidationGuard — Input {appointmentDate}, Locale it-IT, Min date {now}, output variable appointment. Label the outgoing Sequence Flows valid, invalid, and outOfRange.
4. valid branch — ScheduleReminder (Scheduler Module) — When should it fire? Before another date, Amount 24, Unit Hours, Reference date variable {appointment} — fires a new Session 24 hours before the appointment.
5. OutputTask (Standard Module) — confirms: Done — we'll remind you the day before.
6. invalid / outOfRange branches — OutputTask (Standard Module) — replies That date doesn't look right — please type it again, e.g. 25/12/2026 18:00 and loops back to the InputTask.

Troubleshooting

• "Could not parse '…' as a date/time." What you typed (or what the variable contained) is not one of the accepted formats — ISO-8601, unix seconds/milliseconds, RFC 1123, or a date written in the resolved locale. Check the variable's actual value in the Session details; if the date always arrives in one known shape, set Explicit format so the Task enforces it. Remember that natural-language phrases like tomorrow are not supported.
• "Unknown time zone '…'." The time zone field contains a value the platform doesn't recognize. Use an IANA id such as Europe/Rome or America/New_York (Windows ids like W. Europe Standard Time also work). Plain abbreviations like CET or EST do not.
• The result is off by a few hours. Your input had no zone indicator (no Z or offset) and was interpreted in the wrong zone. Set Source time zone (or From time zone) to the zone the value is actually expressed in.
• The output variable was never written. The output field must contain a variable name. Open the Task, type the name (no braces), and save. For DateValidationGuard, also remember the output is written only on the valid branch.
• A gateway Token took an unexpected path. Check that each outgoing Sequence Flow label matches the route values exactly as documented per Task (inside, outside, met, breached, …) — labels are case-sensitive.
• "Unknown unit '…'." The unit value isn't one of the documented options. This normally can't happen from the form's dropdowns — re-select the unit and save.

Best practices

1. Normalize once, early. Run ParseDate (or DateValidationGuard) right after collecting a user-supplied date so every later Task works with clean ISO-8601 UTC.
2. Store UTC, format late. Keep dates in Session variables as ISO-8601 UTC and call FormatDate only at the last moment before showing the date to a person.
3. Set the module defaults for your audience. Configure Default time zone, Default locale, Weekend days, and the Holiday calendar once per Environment instead of repeating them in every Task.
4. Always label every gateway branch. Each gateway Task documents its exact route values — wire one Sequence Flow per value, including the unhappy ones (invalid, outOfRange, breached).
5. Use the Now / As of override only for testing. It freezes "now" — great for verifying branch logic, wrong in production.

Error codes

Code	Name	Description
3005	TaskInvalidData	A required field is empty, a date could not be parsed, a time zone or unit is not recognized, or the output field is not a valid variable name. See full details