Scheduled actions – running an action on a schedule¶

A scheduled action runs an action again and again at fixed times – every night, every Monday morning, every 15 minutes. This chapter describes how to set one up, which server runs it, what happens when something goes wrong and where you see what it did.

It is intended for administrators who automate recurring work in nexxcite.

1. Scheduled actions at a glance¶


Purpose	Runs an action on a recurring schedule, without a user and without a record
Typical use	Nightly clean-up, reminders, escalations, imports from another system, daily reports
Where	Admin Studio → Automation → Scheduled Actions
Related	Actions, Background processing, Monitoring

Summary¶

A scheduled action consists of a schedule (a cron expression), an action and the user the action runs as.
The schedule is evaluated in UTC, not in local time.
The action runs without a current record. It has to find the records it works on itself, for example with a query.
Exactly the servers with ApplicationServer:ProcessScheduledActions = true run scheduled actions.
Every run is recorded under Admin Studio → Monitoring → Background Processes.

2. Settings¶

Open Admin Studio → Automation → Scheduled Actions and create a new scheduled action. Besides the name, description and tags in the header, the editor offers these settings:

Setting	Meaning	Default / Required
"Disabled"	Switches the scheduled action off. It is then not run by its schedule.	off
"Identity"	The user the action – and the failure action – runs as. The roles of this user decide which records the action may read and change.	Required. Without it, every run fails.
"Schedule"	When the action runs, as a cron expression (section 3).	Required. Without it, nothing is scheduled.
"Planned Begin"	Runs before this point in time are skipped.	empty = no start limit
"Planned End"	Runs after this point in time are skipped.	empty = no end limit
"Action"	The action that runs at every scheduled time.	Required
"Failure Action"	An action that runs, as the same user, when the action fails (section 4). For notifications or clean-up.	empty
"Stop After Failure"	Meant to switch the scheduled action off after its first failed run. Not evaluated in the current version – the schedule keeps running.	off
"Store Execution Log"	Whether the log written during a run is kept with the run: "Inherit (use the next level)", "Never", "On failure or warnings", "Always". See Background processing.	"Inherit (use the next level)"

For administrators

Use a dedicated technical user as "Identity", with a role that allows exactly what the action needs. A personal account stops working when the person leaves, and its permissions change with the person's role.
"Planned Begin" and "Planned End" are entered in the date and time field of the editor. In our reading of the current version they are interpreted in the time zone of the server, unlike the schedule itself (UTC). On servers that run in UTC – the usual case for containers – both are the same.

3. The schedule¶

Choosing a schedule¶

The section "Schedule" offers templates for common schedules. Choose one in the list (the empty list reads "Not scheduled") and fill in the details:

Template	Details
"Every minute"	every 1–59 minutes
"Every hour"	every 1–23 hours, at a minute
"Every day"	at a time
"Every week"	at a time, on one or more weekdays
"Every month"	at a time, on one or more days of the month
"Every year"	at a time, on days of the month, in one or more months
"Advanced"	every field of the cron expression on its own, including lists, ranges and steps; optionally "Expression with seconds (6 fields)"

The resulting cron expression is always shown in the field "Expression", with a plain-language description next to it. You can also type the expression there directly. An expression that cannot be read is reported below the field.

Cron expressions¶

A cron expression has five fields, separated by spaces:

minute  hour  day-of-month  month  day-of-week

A sixth field for seconds in front is also accepted. Common shortcuts such as @daily, @hourly, @weekly, @monthly and @yearly can be used as well.

Expression	Runs
`0 6 * * *`	every day at 06:00 UTC
`0 6 * * MON-FRI`	Monday to Friday at 06:00 UTC
`/15 * * *`	every 15 minutes
`30 22 1 * *`	on the first day of every month at 22:30 UTC

The schedule runs in UTC¶

The schedule is evaluated in UTC, not in the local time of your users or of the server. 0 6 * * * runs at 06:00 UTC – that is 08:00 in Central Europe in summer and 07:00 in winter.

nexxcite does not adjust the schedule for daylight saving time. If an action must run at the same local time all year round, plan for the shift or check the result in the action itself.

4. Behaviour¶

A run step by step¶

At every scheduled time, the server that runs scheduled actions does the following:

It reads the current scheduled action. If it is switched off with "Disabled", or the time lies before "Planned Begin" or after "Planned End", nothing happens and nothing is recorded.
It checks that an action and an identity are set and that the action exists. If not, the run is recorded as failed with the reason.
It runs the action as the identity, without a current record and without a user interface.
If the action ends with an error – an unexpected error, or an error the action reports in its protocol – the "Failure Action" runs, as the same identity. Its protocol is stored with the failed run.
The run is recorded with its result, the protocol of the action and, depending on "Store Execution Log", the log.

What the action can and cannot do¶

The action runs on the server, without a browser. Commands that need a user interface – opening a dialog or a form, navigating, showing a message, asking for input – cannot work there. Build actions for scheduled actions without such commands. An action that should run both from a button and on a schedule must not contain them either.

Which server runs it¶

Only servers with ApplicationServer:ProcessScheduledActions = true run scheduled actions. With a single server, this is the default and nothing needs to be done. With several servers, exactly one server – the worker – may have this setting; every server that has it runs every scheduled action. See Running several servers.

When changes take effect¶

The schedule of a scheduled action is registered on the server when it starts and when the scheduled action is saved in its editor – on the server that serves the editor, if that server runs scheduled actions.

Change	Takes effect
The content changes (action, identity, failure action, planned period)	With the next run. The run always reads the current definition.
A new scheduled action, or a changed schedule, saved in the editor	Immediately – if the server that serves your browser tab runs scheduled actions. Otherwise only when the server that runs them restarts.
A new scheduled action or a changed schedule that arrives in another way – through the AI assistant or by importing a sketch	Only when the server that runs scheduled actions restarts.
Switched off with "Disabled"	With the next scheduled time.
Deleted	As soon as the deletion is published: the schedule is removed and nothing more is recorded. With several servers, the server that runs scheduled actions learns about a deletion published on another server through the message bus (see Running several servers). Without a message bus, it records a failed run at every scheduled time until it restarts ("The scheduled action definition does not exist (any more), …").

Note on sketches: saving a scheduled action registers its schedule immediately, even while a sketch is open. A run, however, always reads the published definition. A new scheduled action saved into a sketch is therefore recorded as failed at every scheduled time until the sketch is published; a changed schedule applies before the sketch is published. See Sketches and publishing.

Monitoring → Background Processes → Calendar warns when an enabled scheduled action is registered on no server ("Enabled, but no instance has registered its recurring job. Save the schedule again or restart the instance that processes scheduled actions.").

When the server is down¶

Situation	Effect
The server that runs scheduled actions is stopped or has failed	Scheduled actions do not run. There is no automatic takeover by another server.
The server starts again	The schedules are registered again. Runs that were missed while the server was down are not made up; the next run is the next scheduled time.
The server stops while an action is running	The run is lost and shown as "Abandoned". It is not repeated automatically.
The database cannot be reached	The run fails.

Use "Run now" in Monitoring → Background Processes to start a missed or abandoned run by hand.

Overlapping runs¶

nexxcite does not hold back a run because the previous run of the same scheduled action is still working. Choose an interval that is clearly longer than the action needs, or make the action safe to run twice at the same time.

5. Execution history¶

Every run of a scheduled action is recorded under Admin Studio → Monitoring → Background Processes with the kind "Scheduled action":

"Executions" lists every run with server, start, duration and result. The details show the protocol of the action step by step, the protocol of the failure action, the log and the cron expression.
"Calendar" shows the runs per day and, in the table "Scheduled actions", every scheduled action with its schedule, the next and the last run and warnings.
"Run now" in the details of a run or in the calendar runs the scheduled action again at once, on the server that runs scheduled actions. A manual run ignores "Planned Begin" and "Planned End", but not "Disabled". It requires "Background Job Administration".

Not recorded: scheduled times at which the scheduled action is switched off or outside its planned period. Details of the pages: Monitoring.

6. Examples¶

Daily reminder at 07:00 Central European time (summer)

"Schedule": "Every day" at 05:00 – expression 0 5 * * * (05:00 UTC = 07:00 CEST)
"Identity": the technical user "svc-automation"
"Action": "Remind owners of overdue tasks" – queries all open tasks with a due date before today and sends one mail per owner
"Failure Action": "Notify administrators" – sends a mail to the administrators' mailbox

In winter, the action runs at 06:00 local time.

Synchronisation every 15 minutes during a project

"Schedule": "Every minute" with 15 – expression */15 * * * *
"Planned Begin": 01.11.2026 00:00, "Planned End": 31.12.2026 23:59
"Action": "Import orders from ERP"

Outside November and December nothing runs and nothing is recorded.

7. Permissions¶

Permission	Allows	Granted by
"Open Scheduled Action Manager"	Seeing the collection in the Admin Studio	System Developer
"Add Scheduled Action"	Creating scheduled actions	System Developer
"Edit Scheduled Action"	Changing scheduled actions	System Developer
"Delete Scheduled Action"	Deleting scheduled actions	System Developer
"View Background Processes"	Seeing the runs	System Administrator
"Background Job Administration"	"Run now"	System Administrator

See Roles and permissions.

8. Limitations¶

"Stop After Failure" has no effect in the current version.
The schedule is always evaluated in UTC; there is no setting for a time zone.
Missed runs are not made up after the server was down.
A new or rescheduled scheduled action that was not saved in the editor – created by the AI assistant or imported with a sketch – runs only after the server that runs scheduled actions has restarted.
With several servers and no message bus, a scheduled action that was deleted on another server than the one that runs scheduled actions produces a failed run at every scheduled time until that server restarts.
A run that was interrupted by a stopped server is not repeated automatically.

9. Frequently asked questions¶

My action runs two hours too early. Why? The schedule is evaluated in UTC. Subtract the offset of your time zone from the local time you want.

Can a scheduled action work on one specific record? Not directly – it runs without a record. Let the action find its records, for example with a query, and work through them.

I created a scheduled action, but it never runs. What should I check? That "Disabled" is off, that "Identity", "Action" and a schedule are set, and the calendar in Monitoring → Background Processes: it warns when the schedule is registered on no server. Then check that the server that runs scheduled actions is up.

Can I run a scheduled action right now to test it? Yes, with "Run now" in Monitoring → Background Processes (calendar or the details of a run). This requires "Background Job Administration".

Does a scheduled action take a license? No. Scheduled actions keep running even when the license has expired. See Licensing.