Scheduling

Frequency and Windows

A task’s schedule is a frequency in minutes, optionally narrowed by a window and a cap.

Where to find it

Architect Panel → Automation:

• Tasks — the scheduled tasks themselves
• Task Log — every execution and its result

Frequency is minutes

Not a cron expression. A task with a frequency of five runs every five minutes; sixty is hourly; 1440 is daily. A frequency of zero means it runs on every engine pass.

Simple, and it means "run at 2am precisely" is expressed as a daily frequency with an active window rather than as a schedule syntax.

Choose the longest frequency that works

Every run costs something, and most tasks do not need to be as frequent as they are set. A reminder task running every minute is doing nothing 1,439 times a day.

Ask what the acceptable delay actually is, and set the frequency to that.

Active windows

A start and end time confining a task to part of the day. That is how heavy work is kept overnight, and how anything that contacts people is kept to reasonable hours.

Anything sending a message to a person should have a window. A notification at three in the morning is worse than no notification.

Start and end dates

A task can be bounded by dates as well. Useful for a migration, a campaign or anything temporary — and it means the task stops on its own rather than being remembered.

Maximum runs

A cap on how many times it will ever run. That is how a one-off job is expressed: a frequency, and a maximum of one.

It is also a safety net on anything new — cap it at a handful of runs while you watch what it does.

Preview mode

The task runs and reports what it would have done without doing it. Use it whenever a task acts on records or sends anything, and use it every time you change one.

Stagger the schedule

Tasks all set to run at midnight run at midnight together. Spreading them across the hour is the difference between a busy few minutes and a spike that makes everything slow.

The engine shares itself between tenants

Worth knowing on a multi-tenant installation. Work is interleaved between tenants in turn rather than processed in whatever order the query returned, with an optional per-tenant cap per cycle.

So one customer with an enormous backlog cannot starve everybody else — which is exactly what happens without it.

Worked example

An organisation sets its reminder task hourly with a window of eight to six, its reporting task daily overnight, and staggers three heavy tasks across the small hours rather than all at midnight. A new task was capped at five runs while being watched.

Recommendations

• The longest frequency that meets the need.
• A window on anything that contacts a person.
• Cap new tasks while you watch them.
• Stagger heavy tasks rather than stacking them at midnight.

One-off and Recurring

Most tasks recur. A few should run once, and expressing that properly matters.

Where to find it

Architect Panel → Automation:

• Tasks — the scheduled tasks themselves
• Task Log — every execution and its result

A one-off is a capped task

Set a frequency and a maximum of one run. The task executes, the cap is reached, and it stops — without anybody needing to remember to disable it.

That is much safer than an uncapped task somebody intends to switch off afterwards.

Bound temporary work with dates

A task needed for a month should have an end date. It then stops on its own, and the failure mode is a task that stopped too early rather than one still running a year later.

The recurring task that should have been one-off

The characteristic mess. A migration task, a backfill, a correction — set up as recurring, run successfully, and left enabled. It then runs every night doing nothing, or worse, doing something again.

Every task should have an answer to "when does this stop", even if the answer is never.

Make one-off work idempotent

Safe to run twice. A backfill that only processes records not already processed can be re-run without harm; one that adds a value each time it runs cannot.

You will run it twice — by accident, or because the first run failed part way.

Preview first, always

One-off tasks tend to be the consequential ones: a data change, a batch of messages, a correction across thousands of records. Preview mode is exactly what it is for, and skipping it on a one-off is the worst place to skip it.

Watch it while it runs

A recurring task can be reviewed next week. A one-off that goes wrong is going wrong now, across your whole dataset. Be present for it.

Have a way back

Before running anything that changes data at scale: a backup you have confirmed, or a way to identify and reverse what it did. Recording which records were touched is often the difference between a reversible mistake and a permanent one.

Tidy up afterwards

A completed one-off task should be removed rather than left disabled. A list of thirty disabled tasks is a list nobody reads, and one of them will be re-enabled by somebody who assumes it is current.

Worked example

A backfill was written to skip records it had already processed, previewed against production data, capped at one run, and watched while it executed. It failed part way on a bad record; re-running it after the fix processed only the remainder. The task was then deleted.

Recommendations

• Cap one-off tasks at one run.
• Make them safe to run twice.
• Always preview a one-off, and watch it run.
• Delete it afterwards, do not disable it.