Scheduled processes

A scheduled process is a topology that the platform starts on a fixed CRON expression instead of in response to a webhook or an HTTP call. It is the default shape for periodic syncs, nightly aggregations, hourly health checks, and anything else that has to happen on a clock.

For background see Concepts: Processes and Messages. For the canvas mechanics of the Cron event node — per-node config, the Scheduled Tasks page, the per-node Disable toggle — see Building nodes: Event nodes.

When to use it #

Use a scheduled process when:

The upstream system does not support webhooks.
The cost of polling is acceptable for the cadence (every 5 minutes is fine; every 100 ms is not).
The work is bounded in time: a sync, a report, a cleanup.

For real-time event delivery prefer Webhooks.

Configure the schedule #

Schedules are configured on the topology in the Admin UI, not in code. Drop a Cron event node into the canvas and set its Name, Crontab, and optional Parameters JSON. The configuration modal renders a human-readable description of the expression and the next two scheduled runs so you can verify the cadence at a glance.

Screenshot pending

Cron node configuration modal

Cron node settings dialog showing Name field, Crontab field, optional Parameters JSON, the human-readable preview of the expression, and the next two scheduled runs.

target 1100 x 500

Common patterns:

Cadence	CRON
Every 5 minutes	`/5 * * *`
Hourly at minute 10	`10 * * * *`
Nightly at 02:30	`30 2 * * *`
First Monday of each month at 06:00	`0 6 1-7 * 1`

Scheduled Tasks page #

Every Cron node across every topology is also surfaced on the global Scheduled Tasks page (/scheduled-tasks in the Admin UI). Use it to enable / disable individual schedules without opening the topology, see the next run time, and spot any topology with a Cron node whose crontab is empty (Cron is not set warning, marked in red, will not fire until corrected).

Anatomy of the starting node #

The starting node of a scheduled topology receives an empty payload. Its job is to figure out what work needs doing this run. Two patterns are common:

Watermark pattern #

Track the timestamp of the last successful sync in the application install settings. On each run, ask the upstream API for changes since that watermark, then update it on success.

Node.js

public async processAction(dto: ProcessDto): Promise<ProcessDto> {
    const install = await this.getApplicationInstallFromProcess(dto);
    const since = install.getNonEncryptedSettings()['lastSyncAt'] ?? '1970-01-01T00:00:00Z';

    const changes = await this.fetchChangesSince(since);

    install.addNonEncryptedSettings({ lastSyncAt: new Date().toISOString() });
    await this.applicationInstallRepository.update(install);

    dto.setJsonData({ items: changes });
    return dto;
}

Full snapshot pattern #

Re-fetch the current state of the upstream resource and let downstream nodes diff it against your local copy (see Patterns: Data comparator). Simpler to implement, more expensive to run.

Operational notes #

Overlap. If a run is still going when the next CRON fire time arrives, the platform queues it; runs do not overlap on the same topology+install.
Time zones. Configure the schedule in the time zone that matters for your business rules. The default is UTC.
Catch-up. If a worker is offline when a CRON fire time passes, the platform does not retroactively catch up; the missed run is skipped. If catch-up matters, store the watermark and recover the gap on the next run.
Failure handling. A failed run lands in the Trash inbox like any other failed message. The next CRON tick still fires.