Schedule Form
The Schedule form creates a new schedule or edits an existing one. A schedule runs one or more scan templates (or template groups) on a recurring cadence — hourly, daily, weekly, monthly, or via a custom cron expression. Each schedule has a configurable timezone and may include a jitter offset for load distribution across many schedules.
Inputs
| Name | Description | Allowed values | Default |
|---|---|---|---|
Name | Human-readable label for this schedule | Non-empty string, must be unique across schedules (e.g., "nightly-production-scan") | — |
Description | Optional free-text note | Any text, max 10,000 characters | Empty |
Schedule Type | Cadence pattern. Each type exposes different timing inputs below. | hourly | daily | weekly | monthly | cron | daily |
Hour / Minute / Day / Day-of-Month | Type-specific timing fields. Hourly uses minute only; daily uses hour+minute; weekly adds day-of-week; monthly adds day-of-month. | See type-specific input ranges (0–23 hour, 0–59 minute, 0–6 day-of-week, 1–31 day-of-month) | Type-dependent (e.g., daily defaults to 02:00) |
Cron Expression | Custom cron syntax — only shown when Schedule Type is "cron" | Standard 5-field cron (e.g., "0 2 * * *") | 0 2 * * * (daily 02:00) |
Timezone | Timezone the schedule values are interpreted in. Affects when the cron fires. | IANA timezone name (e.g., "UTC", "America/New_York") | UTC |
Scan Templates | Direct template selection | Zero or more from the Scan Templates list | None |
Scan Template Groups | Group selection — every template in each selected group runs on this schedule | Zero or more from the Scan Template Groups list | None |
Gotchas
- The form REQUIRES at least one scan template OR template group selected. The submit button shows an error if both are empty.
- **When creating:** Schedules with the same trigger time get a per-schedule jitter offset (a random 0–N minute delay) computed at creation to spread load across the dispatcher. The jitter is set once and persisted — it does not re-randomize on each run. Edit mode shows the assigned jitter value in an InfoBox above the form.
- **When editing:** Changing the cadence type (e.g. daily → cron) immediately reschedules the next run based on the new pattern. The jitter offset persists across edits — it is not re-rolled.
- **When editing:** Adding or removing a template/group affects the NEXT run. Currently in-flight scans triggered by this schedule are not retroactively cancelled.
- Cron expressions use the standard 5-field syntax (minute, hour, day-of-month, month, day-of-week). The displayed default ("0 2 * * *") fires at 02:00 every day.
- Daylight saving transitions are handled by the timezone field — set to "UTC" to avoid DST shifts entirely if predictable run times matter more than local clock alignment.
API calls (5)
| Method | Path | Description |
|---|---|---|
| GET | /api/scans/schedules/:id | Load an existing schedule with its template/group selection (Edit mode) |
| GET | /api/config/scan-templates | List available scan templates |
| GET | /api/config/scan-template-groups | List available scan template groups |
| POST | /api/scans/schedules | Create a new schedule (Create mode) |
| PUT | /api/scans/schedules/:id | Update an existing schedule (Edit mode) |
Related
- Schedules — Parent list page — describes filtering, deletion, and the next-run column
- Scan Templates — What schedules execute
- Scan Template Groups — Run multiple templates from one schedule entry