Schedule Triggers

Sirveo provides flexible scheduling features to handle timing-related automation scenarios.

Periodic flow execution

Task and graph flows can be scheduled to run periodically. Standard cron expressions are supported (*/15 9-18 * * *) for precise and flexible scheduling. Alternatively, fixed-schedule expressions (@every 20m30s) can be used for simpler scheduling needs.

Periodic flow execution is configured using schedule triggers.

Flow-driven scheduling

Flows can schedule the execution of other flows. For example:

Flow A can schedule flow B to run immediately, and asynchronously
Flow A can schedule flow B to run after a delay (10 seconds and 90 days)
Flow A can (re)schedule itself to run an hour later
Flow A can schedule flow to run after 30 minutes, but not after 3 hours.

The latter case uses an expiry feature to cancel a scheduled flow execution after a certain duration if it hasn’t yet run. Typically because the Sirveo server encountered unexpected downtime.

Flow-driven scheduling uses once-off schedule triggers, which are created within flows via the schedule node.

Scheduling a flow

For this example, we’ll use a graph flow with:

An event node that creates a persistent, custom event (“scheduled.run”) with a 1-hour retention period.
A wait node that adds a 1-second delay before the flow finishes

Target flows of schedule triggers does not need to be active.

To schedule this graph flow, navigate to triggers/schedules, and click the “New” button. Give the new schedule trigger a name, a target flow, enable the “Active” option, and provide a Cron schedule, here @every 15s.

I’m also overriding the server’s default event retention period, to remove trigger-related events after 1 hour.

When the target flow is executed for the first time, the trigger schedule list indicates when last it was run, and how long the flow took to execute.

As expected, the wait node in the target flow introduces a 1-second delay.

Schedule triggers leverage Sirveo’s event system, in order to provide detailed execution information. After the target flow has run a few times, opening the event browser.

Seen here are events for the most recent 4 scheduled runs. When the target flow is executed, it first creates a user event (“scheduled-run”), and waits for 1 second. After the flow completes, the scheduler creates a system event (“trigger.schedule.ok”).

Looking at one of the system events shows various details about the trigger execution;

screenshot: trigger.schedule.ok event details

Schedule trigger configuration includes settings to disable certain system events, as well as override the server’s default event retention configuration.

Using the schedule node

Whenever an automation scenario requires some delay between one or more of it’s steps, a scheduling problem arises. Flows can use one or more wait nodes to create short delays up to 5 seconds. This approach is not suitable when automation steps must be delayed by minutes, hours or even days.

Such cases are easy to handle with the schedule node. It is used within flows to create once-off schedule triggers, which in turn runs other graph of task flows. Let’s see how this works.

Create a new task flow, and replace the default output node with a schedule node.

The schedule node’s configuration is similar to schedule trigger configuration. The key difference is that schedule nodes use optional delay and expiry durations, instead of cron expressions.

This node is configured to run the same flow from the previous example, after a delay of 15 seconds. I’ll add another schedule node, to run the same flow after 30 seconds. The task flow now looks like this:

Using the “run” button on either of the schedule nodes produces output like this:

The node output contains confirmation that the once-off schedule trigger was successfully created, and synchronized with the server’s scheduler.

Next, save the flow, navigate to the schedule trigger list, and switch to once-off triggers (top right blue button).

screenshot: once-off schedule trigger list, with pending triggers

The two new once-off triggers are shown, along with their source and target flows, and scheduling details. Both are in a pending state, waiting to be triggered.

After about 30 seconds, refresh the trigger list (top right refresh button), which now shows both triggers as completed.

screenshot: once-off schedule trigger list, with completed triggers

The target flow was ran 15 and 30 seconds after the scheduling flow scheduled it’s execution. In both cases, the target flow run within about 3 milliseconds of the scheduled time.

As with the cron-based trigger schedule in the previous example, we can inspect scheduler-related events with the event browser.

screenshot: once-off trigger events in event browser

The server scheduler

Sirveo’s scheduler powers schedule triggers, once-off schedule triggers and internal server jobs, like automatic database cleanup. The scheduler is relatively precise, and will typically run schedule triggers within some milliseconds, provided CPU’s are not overwhelmed.

Since schedule triggers can run as often as 5 seconds (@every 5s), the scheduler internals provides a guarantee that the same schedule trigger cannot not execute more than once every 4 seconds.

It also provides a guarantee that the same schedule trigger will not execute while it’s target flow is still running from the previous execution. For example:

Flow A takes around 8 seconds to complete
A schedule trigger is configured to run flow A every 5 seconds
Flow A effectively runs every 10 seconds, since the scheduler will skip every other execution while the flow is busy running

Scheduler event retention

When schedule triggers run, the associated system events are subject to the server’s event retention configuration.

As of version 0.3.0, schedule triggers provide additional settings to:

Override the server’s default event retention period, for a specific cron or once-off trigger
Disable trigger.schedule.ok and trigger.schedule.error events for a specific trigger

In most cases, schedule-related events are useful for short-term monitoring and troubleshooting. It is often unnecessary to retain these events for long periods.

Once-off schedule trigger retention

After a once-off schedule trigger has been executed, it’s trigger configuration data typically does not need to be retained indefinitely.

With default server configuration, completed once-off schedule trigger entries are deleted after 24 hours, as part of the server’s automatic database cleanup.

This behaviour can be adjusted or disabled with the SIRVEO_RETENTION_PERIOD_SCHEDULES server setting. See the configuration reference for details.

Note that the automatic cleanup only removes the trigger configuration data, not the associated system events.

Schedule node details

Using delay

A schedule node’s delay setting is optional. When omitted, the scheduler will execute the target flow as soon as the once-off trigger is created and synchronized, typically within a few milliseconds.

This behaviour can be leveraged to kick off another flow for immediate and asynchronous or background execution, which is useful when a parent flow does not need the output data from the child flow.

The delay setting, when provided, requires a minimum delay of 10 seconds, and supports delays of up to 90 days.

Using expiry

The expiry setting is also optional. It is used to cancel a scheduled flow execution if it hasn’t yet run, after a certain duration.

Consider this scenario:

Flow A schedules flow B to run after a 30 minute delay, without an expiry option
10 minutes later, the server encounters unexpected downtime, and is offline for 2 hours
Once the server comes back online, all pending (once-off) schedule triggers are executed, if they are due.

Here, flow B was intended to run at T+30, but instead runs at around T+130, when the server comes back online.

The expiry setting on the schedule node can be used to prevent this scenario, by specifying a time limit within which the scheduled flow must run.

Flow input data

Schedule node configuration may include optional input data for their target flows. Variable expressions (e.g. ${input:some-key}) can be used to insert dynamic values into flow input data.

The schedule node does not currently support using node input data as input for the target flow. This is by design, because;

Self-scheduling flows

As of release 0.3.4, a flow can use the schedule node to directly schedule it’s own execution.

When a flow schedules itself, a minimum delay of 30 seconds is required. This constraint reduces the impact of accidentally creating an indefinite scheduling loop.

This feature is typically useful alongside some conditional logic, in order to handle automation scenarios like these:

“Retry this flow later if it fails"
"Re-run this flow until some condition is met, or until some time limit is reached”

Cron syntax

Schedule triggers support standard 5-token Linux cron expressions. For example:

Cron	Note
`* * * * *`	Every minute
`/15 * * *`	Every 15 minutes
`10 * * * *`	Hourly, at 10m past the hour
`0 8-17 * * *`	Hourly, between 8am and 5pm
`0 18 * * 1-5`	At 6pm, Monday to Friday

Cron expressions can’t schedule flow executions more frequently than once per minute.

`@every` syntax

As of release 0.3.4, schedule triggers may define execution periods with the @every syntax, as an alternative to standard cron expressions. Below are some comparisons:

Cron	@every
`* * * * *`	`@every 1m` or `@every 60s`
`/25 * * *`	`@every 25m`
n/a	`@every 30s`
`30 3,6,9 * * *`	n/a
n/a	`@every 2h45m`

@every expressions can run a flow as often as every 5 seconds.

Scheduling FAQ

Common questions and useful answers about flow scheduling.

❔ Can a flow be scheduled to run at a specific time?

With cron-based schedule triggers, yes.

With the schedule node, no. The schedule node supports fixed delays, but not fixed times.

❔ How many schedule triggers can I configure?

The practical constraint is available memory and CPU resources.

With many schedule triggers, or triggers that run very frequently, a large number of system events may be generated, which has a storage implication for the server’s database. This can be managed by adjusting the server’s event retention behaviour, and fine-tuning system event settings on individual schedule triggers and schedule nodes.

❔ How does the scheduler handle errors while running a flow?

The scheduler creates these system events:

trigger.schedule.error
trigger.schedule.failed
trigger.schedule.disabled

See the system event reference for a detailed description of error/failure behaviour.

❔ What happens when a schedule trigger tries to run a flow that is still running from a previous scheduled run?

The scheduler will skip the execution, and try again at the next scheduled time. See this.

❔ Within a flow, can I check it is running because of a trigger schedule?

Yes, via the metadata store. Use the following in task flow conditions, or JS code/conditions nodes:

Was the flow triggered by the scheduler?

$meta.run_source === "scheduler"

Was the flow triggered by a cron-based schedule trigger?`

$meta.run_source === "scheduler" && !$meta.scheduling_flow_id

Was the flow triggered by a once-off schedule trigger?

$meta.run_source === "scheduler" && !!$meta.scheduling_flow_id

What is the ID of the scheduling flow that created the once-off trigger?

let schedulingFlowId = $meta.scheduling_flow_id ?? null