Scheduling tasks

Portail ZAPP runs scheduled tasks in the background (called "jobs" on screen): sending the notification queue, directory synchronizations, connector collections, deadline monitoring, and so on. Each task is provided by a module; the Scheduler screen is where you choose when they run, start them by hand and check their result.

The Scheduler screen (menu Administration › Instance and operations › Scheduler) is restricted to Administrators.

The task list

Each row shows the task's Name, its Category, its Description, its Triggers (the active schedules), its Status (Enabled, Disabled or Running), the Last run date and its Result.

Tasks are neither created nor deleted from this screen: they appear with the modules that provide them. Some are shipped disabled because they need some configuration first (a directory synchronization, for example): enable them once that configuration is done.

When the Data grids module is installed, the list is a grid: select a row, then use the Run now, Enable, Disable or Details buttons of the toolbar. Without the grid, Details opens the task's page.

A task's page

The State card shows the category, status, last run and its result, with two actions:

• Enable / Disable: a disabled task no longer starts by itself, whatever its triggers;
• Trigger now: starts the task right away, even if it is disabled. The button is greyed out (Running) until the current run has finished: the same task never runs twice in parallel. The run happens in the background; reload the page to see its result.

Some generic tasks also show a Parameters card: a JSON text passed to the task on every run. Save stores it as is, without any format check: review it before saving.

The task that calls a URL (url parameter) reaches a public address or a machine on your private network. It refuses reserved addresses (link-local, a cloud host's metadata address such as 169.254.169.254, multicast) as well as localhost, except when the URL targets the application itself: same base address (protocol, name and port), or localhost on a port the application listens on. Other services of the machine (localhost on another port) stay refused. Towards another address, a redirect is followed and checked the same way; towards the application itself, only redirects that stay on the application are followed. A refused call shows in the history with the message Call refused.

Triggers

A trigger is a CRON expression that says when the task starts. A task can have several; it starts as soon as any of them is due.

• To add one, enter a Name and a CRON expression, then + Add trigger. The CRON assistant button (icon to the right of the field) builds the expression for you; Apply copies it into the field.
• Edit changes a trigger's name, expression and Enabled box; Delete removes it after confirmation.

Good to know:

• the expression has six fields, the first one being seconds: 0 0/10 * * * * means "every 10 minutes", 0 30 2 * * * "every day at 2:30 AM". An invalid expression is rejected and an error message is shown;
• triggers created from this screen follow UTC time, not local time: keep this in mind for a task at a fixed time;
• the scheduler checks what is due once a minute: a task therefore never starts more than once a minute, and a run missed while the application was stopped is not caught up (except for the few tasks designed to catch up at startup).

Execution history

Execution history lists the latest runs, with the start time, Duration, Status, Stats supplied by the task (number of items processed, for example) and any Error. Only the last 20 runs of each task are kept.

The status is shown in its technical form: Success, PartialSuccess, Error, Running or Skipped (not started: during a blackout window, or because the task's module is not available). A run that was not started is not caught up later.

A blackout window is a period, one-off or recurring (days of the week and time range), during which no scheduled job fires. It is managed through the scheduler API (GET and POST /api/v1/scheduler/blackout-windows, DELETE /api/v1/scheduler/blackout-windows/{id}); the instance health screen only reports the one in progress.

If the application stops during a run, the task is reset at restart and starts again at its next due time.

When a task fails, the Error column explains the cause in your language; the API and exports receive a stable code followed by an English sentence. The technical message (which may name a server, a file or a query) stays in the server log. Causes common to all tasks:

A task that runs a stored query names, when it fails, the query at fault: the exact reason is in its execution log (Queries module).

Any other unforeseen error is shown as "Unexpected error" with its type. The causes specific to a task (connectors, scripts, synchronizations) are described on the page of its module.

Export and import the schedule

• Export schedule downloads a JSON file with, for each task, its name, its state (enabled or not) and its triggers. JSON parameters are not exported.
• Import schedule loads such a file. Tasks are matched by name; a task that does not exist on this instance is ignored, none is created. Tick Overwrite existing schedule (triggers replaced) to apply the file: the state of each matched task is taken from the file and its triggers are replaced by the file's. Without this box, the import changes nothing.

This is how you carry a schedule tuned on a test instance over to another instance.

See also

• "Setting permissions": who can open the Scheduler.
• The pages of the modules that provide tasks (directory synchronizations, connectors) describe what each one does.