Schedule server tasks

A schedule runs a list of tasks on a timetable: a console command, a power action or a snapshot. A nightly restart, for example, is a schedule that warns players with a command, waits a minute and then restarts the server. You set schedules up on the server's Schedules tab.

• Free servers cannot use schedules. Free servers lists what they leave out.
• A server holds up to 25 schedules, and a schedule holds up to 25 tasks.
• On a server someone shared with you, the owner must have given you the Schedules permission. To add a task, you also need the permission for what the task does: Command for a console command, Power for a power action, and Snapshots for a snapshot.

1. In the dashboard, go to Container Apps and open the server, then the Schedules tab.
2. Select New schedule….
3. Enter a Name, such as Nightly restart. It can be up to 120 characters.
4. Under Cron expression, fill in Minute, Hour, Day, Month and Weekday. The form starts at 0 4 * * *, which runs at 04:00 every day. See Write the timetable.
5. Choose the Time zone to read the timetable in. It starts as your browser's time zone.
6. Choose the options:
   • Active runs the schedule on its timetable. Clear it to create the schedule paused.
   • Only while the server is online skips a run when the server is not running.
   • Catch up a missed run runs a missed run once, as soon as possible, when our systems were down at the time it was due. Clear it to skip the missed run and wait for the next one.
7. Select Create schedule.

The new schedule has no tasks yet, so it does nothing when it runs. Add its tasks next.

The five fields are standard cron fields, read in the schedule's time zone:

Use * for any value, a comma for a list (0,30), a hyphen for a range (1-5) and a slash for a step (*/15). Some common timetables:

Daylight saving follows the time zone. A time that the clocks skip in spring runs once, an hour late, and a time that the clocks repeat in autumn runs once.

1. Select the schedule's name to open it. It opens on Tasks.
2. Select Add task.
3. Choose the Action and fill in what it needs:
   • Run a console command: the Command to send, without a leading /, such as say Restarting in 60 seconds. It can be up to 1,000 characters.
   • Send a power signal: the Signal, which is Start, Stop, Restart or Kill.
   • Take a snapshot: nothing else. The snapshot is named scheduled- followed by a code for the run and the task.
4. Set the Delay: how many seconds to wait after the previous task finishes before this one runs. Leave it at 0 to run at once. A delay can be up to 24 hours (86,400 seconds).
5. Select Continue if this task fails if the tasks after it should still run when it fails. Without it, a failed task ends the run.
6. Select Add task.

Tasks run from the top down. Use Move up and Move down beside a task to change the order, and Remove task to remove it.

A console command reaches the server only while it is running, so select Only while the server is online for a schedule that starts with a command.

A snapshot task uses your account's snapshot storage. When the storage is full, the schedule deletes the oldest unlocked snapshots it took of this server until the new one fits. It never deletes a snapshot that you took by hand, that another schedule took or that we took. If deleting its own snapshots does not make enough room, the task fails.

Select Run now beside the schedule. It runs once straight away, and the timetable carries on as before. Run now is greyed out while the schedule is running.

• To stop a schedule for a while, open the menu beside Run now and select Pause. Select Resume to start it again. A resumed schedule waits for its next time on the timetable, so resuming a nightly restart does not restart the server there and then.
• To change the name, timetable, time zone or options, open the schedule, select Settings, then Edit schedule. Make your changes and select Save changes.
• To delete a schedule, open the menu beside Run now and select Delete schedule…, then Delete schedule. Its tasks and run history are deleted with it, and a run in progress stops.

Open the schedule and select Run history. It lists the last 20 runs, newest first, with each run's status, when it started and whether the timetable (Cron) or someone (Manual) started it. Select Show steps to see what each task did and any error.

The schedule's Settings view also shows the Timetable, the Next run, the Last run and its Options.

A message confirms each change, such as Schedule created., Task added. or Run queued. The schedule's badge shows Active, Paused or Running, and the next run time appears beside its timetable.

Schedules are not included on the free plan. …

The server is a free server. To use schedules, order a paid server and restore a snapshot of this one onto it.

Last run failed

A task failed. Open the schedule and select Run history, then Show steps to read the error. The same error shows under The last run failed in Settings.

Skipped: server was not running …

Only while the server is online is selected and the server was stopped when the run was due. Skipped: could not confirm the server was online means we could not check, so we skipped the run to be safe.

Skipped: server cannot run schedules right now

The server was installing, being moved or suspended when the run was due, so the run did not start. A run shows Skipped: server is suspended, or another status, for the same reason. The schedule runs again at its next time.

Skipped: due time passed while the panel was down

The run was due while our systems were down, and Catch up a missed run is not selected.

A snapshot or restore was already in progress; this run did not take one.

Another snapshot or restore was running on the server, so the snapshot task was skipped.

This schedule was changed in another tab. Reload and try again.

Someone saved the schedule after you opened it. Reload the page and make your change again.

This schedule is already running.

Wait until the current run finishes, then select Run now again.

Backups have been replaced by snapshots. …

The Take a backup action can no longer be added. Use Take a snapshot instead. Backup tasks added before snapshots replaced backups keep running.

This server already has the maximum of 25 schedules. Delete one before creating another.

Delete a schedule you no longer need, or add its tasks to another schedule.

• Take a server snapshot
• Use the server console
• Share a server with other users explains the Schedules permission.

GET /api/v1/client/servers/{uuid}/schedules lists the server's schedules, each with its tasks. POST to the same path creates one. The body takes name, the five cron fields cron_minute, cron_hour, cron_day_of_month, cron_month and cron_day_of_week, timezone (an IANA name, default UTC), is_active (default true), only_when_online (default false), catch_up (default true) and an optional tasks list, so you can create a schedule and its tasks in one request:

curl -X POST https://api.coritan.com/api/v1/client/servers/$SERVER/schedules \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly restart",
    "cron_minute": "0", "cron_hour": "4", "cron_day_of_month": "*",
    "cron_month": "*", "cron_day_of_week": "*",
    "timezone": "Europe/London",
    "only_when_online": true,
    "tasks": [
      {"action": "command", "payload": {"command": "say Restarting in 60 seconds"}},
      {"action": "power", "payload": {"signal": "restart"}, "time_offset": 60}
    ]
  }'

Each task has an action and a payload:

time_offset is the delay in seconds after the previous task, from 0 to 86400, and continue_on_failure defaults to false. The response echoes a power task's signal as {"action": "restart"}.

The paths are relative to /api/v1/client/servers/{uuid}. A schedule's response also carries next_run_at, last_run_at, last_run_status, last_failure_message, is_processing and revision.

GET /api/v1/client/timezones lists the time zones a schedule accepts, as zones with each zone's name and current offset, and aliases that map old zone names to current ones. An unknown zone answers 400 with Unknown timezone, and a cron that is not five valid fields answers 400 too.

On a server shared with you, listing needs schedule.read, creating needs schedule.create, deleting needs schedule.delete, and every other change needs schedule.update. A task also needs the permission its action uses: control.console for a command, control.start, control.stop, control.restart or control.kill for a power signal, and snapshot.create for a snapshot.