Event delays

Delays allow you to postpone an action – such as the sending of an email, or the posting of a tweet – rather than doing it straight away.

Delays are provided as an aspect of the Event system, found in components such as the Data Entry Form and Shopping Cart.

When an event happens, (for example a Form record being submitted), this acts as a trigger, setting off a chain of actions: the system starts at the top of the event tree for that trigger, and if it comes across a Delay, it waits until the specified moment before proceeding.

So in a simple example, the Form submission could trigger a Delay of two hours, at which point an email would be sent.

A trigger can be linked to multiple actions, so you could set an email to be sent immediately, and another to be sent a week later, and another after three months, etc

Configuring the length of delay

There are a number of ways to specify how long the delay should be – or when the delay should end.

The first aspect is to define a moment when it should end:

• Now – (ie no delay – but is typically adjusted by a timespan – see below)
• Explicit date – an exact date and time when the delay should end.
• Start of Next… Day / Month  / Year
• Form field – use a date and time specified in a field in the form that was submitted.
• Query field – use a date and time specified in a field from a query (if the query returns multiple records, the value from the first record is used)

The second aspect is to adjust this by a timespan:

This can either be set to act earlier, or later, than the end-point defined above.

• Explicit Timespan - an explicit timespan can be entered, or
• Form field - a timespan can be taken from a timespan field in the form that was submitted
• Query field - a timespan can be taken from a field in a query query (if the query returns multiple records, the value from the first record is used)

To use no adjustment, choose Timespan and leave the timespan fields blank.

Using Queries to retrieve a date or timespan

To base the date or timespan on a query, first go to the Queries tab, and add the Query, specifying any criteria.

Then return to the Delay tab, and select the Query and the Field from the relevant dropdowns.

If the query results in multiple records, the value from the first record is used.

If the query results in no records, then it treats this as no delay or no adjustment, depending where the query is used.

Once the delay, with any adjustment has been computed, this results in a date and time, at which time the system return to the event tree, and looks to see what actions to take – sending email, etc.

If the moment turns out to be in the past, then this will happen straight away (although events are evaluated each minute so in practice there may be a delay of up to 60 seconds).

If a vast number of delays end at the same moment, the system will work through them as quickly as it can, but they won’t necessarily all happen at the same instant.

How delays affect when criteria are evaluated.

The event tree can contain multiple criteria objects, delay objects, and action objects.

The system starts at the top of the tree, and executes each object in turn. When a delay object is encountered, evaluation of objects further down the tree is postponed until the delay is over. This means that if the values that the criteria are based on change during the delay, the new values will be used for the subsequent evaluation, not the original values.

Cascading delays

You can chain multiple delays together to gain more flexibility than a single delay provides.

For example:

Imagine you want to allow a client to specify that they want to receive a reminder email n days before the end of the next month – where they can specify the number of days, and you want the email to be sent at 10am

First delay:

Delay until Start of next Month
Adjust earlier by Timespan from a Query field

Second delay:

Delay until Now
Adjust Later by 10 hours

Preservation of context

Despite the delays postponing execution of actions, actions retain access to the context of the original triggering action, including the user id, ip address of the user triggering the event.

Delays are persistent – that is, they will survive server reboot or downtime – any action scheduled for execution whist the server was off will be executed as soon as it returns to service

Cancelling a delayed action

Once a delay has been executed, and the evaluation will resume once the delay period is over. This of itself cannot be cancelled. However, you can add a Criteria action as child object of the delay, to be executed when the delay is over, and use this to determine whether the subsequent actions should be executed or not.

For example, if the delayed action is to send an email to prospective customers, you might want to add a criteria to see if they have in the meantime asked not to be emailed.

Timezones

The dates and times used in the delay system are based on the timezone of the server, which will normally be set to GMT / UTC

If you want to use a different timezone, you can simply use a delay to add the requisite number of hours. For example, to get to Eastern Standard Time, you would add a Delay of:

Delay Until: Now
Adjust Later by 5 hours

Timespan fields

If the Adjust is set to “Later”, then positive values against the various fields of the timespan work forward in time. However you can use negative values for some or all of the fields.

For example, to adjust later by a month less two days (perhaps to give two days notice of something happening in a month’s time), you would set a timespan of:
0 years, 1 months, -2 days, 0 hours, 0 minutes.

You can leave fields blank instead of entering zeros.

Changing the Adjust “Later” to Adjust “Earlier” silently reverses the sign of each field in the timespan field when it performs the calculations. This is useful if you need to set an “Earlier” adjustment, but want to allow a user to enter a timespan in a form field without worrying about having to enter it as a negative.

Making something happen 'earlier'

A common requirement is to make an action happen a set time before another action. The key to understanding how to configure this is to note that delays – even when configured to do something ‘earlier’ can only delay. There is no such thing as a negative delay (that would imply time-travel).

So to make one action happen before another you need to configure two delays, one of a shorter duration than the other. It is quite acceptable to include an ‘earlier’ aspect in the configuration, but for the time difference between the two actions to be maintained both delays must have some duration into the future.