Schedules

Overview

Schedules allow you to automate workflow execution by triggering flows at specific times or on recurring intervals. This guide will help you create and manage schedules effectively.

Quick Start

Creating Your First Schedule

1. Navigate to the Triggers page from the sidebar (Schedules tab)

2. Click New Schedule

3. Fill in the schedule details:

   • Schedule name: Optional descriptive name (auto-generated if empty)
   • Flow: Select the workflow to execute
   • Version: Choose a committed version or use the latest draft
   • Schedule type: One-time or Recurring
   • Timing: Configure when the schedule should run

4. Click Create schedule

Schedule Types

One-Time Schedules

Execute a flow once at a specific date and time.

Use cases:

• Maintenance windows
• Planned upgrades during off-hours
• One-time configuration changes
• Scheduled audits

Configuration:

• Run at: Select date and time for execution
• Timezone: Specify timezone for the run time (default: UTC)

Example:

Name: "Router Upgrade - Maintenance Window"
Type: One-time
Run at: 2026-02-15 02:00:00
Timezone: America/New_York

After execution, one-time schedules automatically transition to COMPLETED status and cannot be re-enabled.

Recurring Schedules

Execute a flow repeatedly based on a cadence.

Use cases:

• Daily health checks
• Weekly configuration backups
• Hourly compliance scans
• Periodic evidence collection

Cadence Options:

Interval-based

Run every N seconds.

Configuration:

• Interval seconds: Minimum 60 seconds
• Common intervals:
  • Hourly: 3600
  • Every 6 hours: 21600
  • Daily: 86400

Example:

Name: "Daily Pre-Change Checks"
Type: Recurring
Cadence: Interval
Interval: 86400 (24 hours)

Cron-based

Use cron expressions for complex scheduling patterns.

Configuration:

• Cron expression: Standard 5-field cron syntax (minute hour day month weekday)
• Timezone: Applied to cron evaluation

Common cron patterns:

0 * * * *        → Every hour at :00
0 2 * * *        → Daily at 2:00 AM
0 0 * * 0        → Weekly on Sunday at midnight
0 9 * * 1-5      → Weekdays at 9:00 AM
*/15 * * * *     → Every 15 minutes
0 */6 * * *      → Every 6 hours

Example:

Name: "Weekday Morning Health Checks"
Type: Recurring
Cadence: Cron
Cron expression: 0 9 * * 1-5
Timezone: America/New_York

Flow Parameters

When creating a schedule, you can configure flow-specific parameters:

Device Targets

For flows that require target devices, assign devices to target roles:

Single device roles:

• Select one device from the dropdown

Multiple device roles:

• Select multiple devices using the multi-select component

Example:

Flow: "IOS-XE Upgrade Workflow"
Target role: upgraded_device (required)
Selected: router-01, router-02, switch-01

Flow Inputs

Provide values for flow input parameters:

Supported types:

• String: Text values
• Int: Whole numbers
• Float: Decimal numbers
• Bool: Checkbox (true/false)

Example:

Flow: "Version Upgrade"
Inputs:
  - target_version: "17.9.4" (string)
  - reboot_required: true (bool)
  - timeout_minutes: 30 (int)

Template Variables

The UI automatically detects template variables used in flow nodes (e.g., {{inputs.target_version}}). These are shown as required inputs even if not explicitly defined in the flow's inputs section.

When a trigger does not start a run

A schedule fires, but the API can still refuse the run it asks for — most often because the schedule's saved inputs no longer satisfy the flow's own field rules (a change reference that fails the flow's pattern, a required device target that was removed), or because the flow was deleted.

When that happens:

• The reason is stored on the schedule and shown as Trigger failed in the Schedules list, and in full on the schedule's detail page with the time it was recorded.
• The occurrence is skipped instead of being re-attempted every poll: a recurring schedule moves on to its next slot, and a one-time schedule stops, since a retry would be refused for the same reason. Run Now re-arms it once the cause is fixed.
• A server-side failure — the workflow engine could not start the run — is recorded the same way but is not skipped: the occurrence is retried about five minutes later, since the cause is usually transient.
• The stored reason is cleared as soon as the schedule next starts a run, so a populated one always describes the current state.
• The same reason is logged by the API (action: schedule_trigger_refused) and by the scheduler (action: schedule_trigger_error, with the API's message).

Fix the cause — usually by editing the schedule's parameters — then use Run Now to confirm before the next occurrence is due.

A run the flow's own limits postpone (concurrency, rate window, cooldown) is not a failure: it is reported as a skip and leaves no error on the schedule. A recurring schedule takes its next slot; a one-time schedule, which has none, retries the same occurrence about five minutes later, so a busy flow cannot silently drop it. See Run limits.

A flow that refuses runs started by hand does not affect its schedules at all. Both the cadence and Run Now keep working: the schedule is an approved trigger, and pressing Run Now early is still the schedule starting the run, not a person starting it directly. See Manual run control.

Managing Schedules

Viewing Schedules

Schedules are listed on the Triggers page (Schedules tab), reachable from the sidebar. The old /schedules URL redirects there; individual schedule detail and edit pages keep their own routes.

Trigger nodes in the flow editor

Every schedule targeting a flow also appears as a projected trigger node in that flow's graph editor (and the flow detail Graph tab), attached to the Start node with a dashed edge. These nodes are a live, non-versioned overlay: they are not part of the flow definition, never appear in drafts, commits, or version diffs, and pausing or resuming a schedule from the node's side panel takes effect immediately without a flow commit. The side panel offers Pause/Resume, Run now, the version the schedule runs, and links to the schedule's detail and edit pages; the Manual trigger node offers an Add schedule shortcut that pre-selects the flow. The overlay can be hidden with the Triggers toggle in the editor toolbar.

Visibility is version-scoped: a trigger appears only on the flow version it would start. A schedule pinned to an older version is hidden from the editor (which represents the current committed version) — the Manual node's panel counts such hidden triggers — and shows instead on that version's preview in the version history dialog, with a vN chip marking the pin.

Flows that start this one as a child flow appear alongside the schedules and webhooks: a parent flow card for each flow.run step targeting it, version- scoped by that step's optional child-version pin. Its panel names the calling step and confirms whether the call exists in the parent's committed version — the flow list carries each parent's draft, so a step added but not yet committed is reported as such rather than presented as live.

The run detail Graph tab shows the triggers applicable to the run's executed version, dimmed, with the trigger that actually started the run highlighted ("This run"). Runs whose trigger was deleted keep a provenance node marked Deleted; runs started by a parent flow's flow.run step show a "Called by" node linking to the parent run.

Those trigger cards come from a snapshot taken when the run was created, stored on the run alongside the flow definition it executed. A run therefore keeps showing the schedules and webhooks as they were configured at that moment — including their names, pins, and active state — even after they are renamed, repointed, paused, or deleted, and it never shows a trigger created afterwards. Runs created before this snapshot existed fall back to the flow's current trigger configuration.

Upcoming Tab

• Shows only ACTIVE schedules
• Sorted by next run time
• Displays cadence and next run information

All Schedules Tab

• Shows all schedules regardless of status
• Includes completed and disabled schedules

Schedule Actions

Run Now

Triggers the schedule immediately, creating a new run without waiting for the next scheduled time.

• Available only for ACTIVE schedules
• Does not affect the schedule's next run time
• Useful for testing or urgent executions
• Recorded in the audit log as a run.started entry on the new run, carrying trigger_source: run_now in its details — the same start action every run gets, whoever started it

Pause

Disables an active schedule, preventing automatic execution.

• Changes status to DISABLED
• Next run time is preserved
• Can be resumed later

Resume

Re-enables a disabled schedule.

• Changes status back to ACTIVE
• Recalculates next run time from current time
• Not available for COMPLETED schedules

Delete

Removes the schedule from the list.

• The row is kept and can be brought back with POST /schedules/{id}/restore
• Does not affect runs that have already been created
• Both the delete and the restore are recorded in the audit log: the delete carries the schedule as it stood, the restore carries it as it stands afterwards

Schedule Status

Status	Description	Actions Available
ACTIVE	Schedule is enabled and will execute when due	Run now, Pause, Delete
DISABLED	Schedule is paused and will not execute	Resume, Delete
COMPLETED	One-time schedule has finished execution	Delete only

Monitoring and Troubleshooting

Checking Schedule Execution

1. Next Run Time: Displayed in the schedule table

   • For recurring schedules, automatically updates after each run
   • For one-time schedules, shows the scheduled run time

2. Last Run Time: Shows when the schedule last executed

3. Created Runs: Navigate to the Runs page to see executions triggered by schedules

   • Filter by schedule name or flow name

Common Issues

Schedule not executing

• Check schedule status is ACTIVE
• Verify next run time is in the past
• Check the scheduler service is running and review its logs (for example docker compose logs scheduler)

Wrong timezone

• Cron expressions are evaluated in the specified timezone
• UTC is the default if not specified
• Use standard timezone names (e.g., America/New_York, Europe/London)

Completed schedule can't be resumed

• One-time schedules automatically complete after execution
• Create a new schedule if you need to run it again

Best Practices

Naming Conventions

Use descriptive names that indicate:

• Purpose: "Daily Health Check" or "Weekly Backup"
• Target: "Core Router Maintenance" or "Access Switch Audit"
• Timing: "Weekday Morning Check" or "Sunday Night Backup"

Timezone Selection

• Use local timezone for business-hours schedules
• Use UTC for globally distributed infrastructure
• Document timezone in schedule name if critical

Version Pinning

• Pin to specific flow versions for production schedules
• Use latest draft only for development/testing
• Review and update versions after flow changes

Testing

1. Create a test schedule with near-future run time
2. Use "Run now" to test before scheduling
3. Monitor first few automatic executions
4. Verify flow inputs and targets are correct

Maintenance

• Review and clean up completed schedules regularly
• Update schedules after flow definition changes
• Disable unused schedules instead of deleting (preserves history)

Examples

Example 1: Daily Backup at 2 AM

Name: Daily Configuration Backup
Flow: backup-running-config
Type: Recurring
Cadence: Cron
Cron: 0 2 * * *
Timezone: America/New_York
Targets:
  - all_routers: [router-01, router-02, router-03]

Example 2: Maintenance Window

Name: Q1 Maintenance - Core Upgrade
Flow: ios-xe-upgrade
Type: One-time
Run at: 2026-03-15 02:00:00
Timezone: America/Chicago
Inputs:
  - target_version: "17.9.4"
  - reboot_required: true
Targets:
  - upgraded_device: [core-router-01]

Example 3: Hourly Health Checks

Name: Hourly Connectivity Check
Flow: pre-change-checks
Type: Recurring
Cadence: Interval
Interval: 3600 seconds
Timezone: UTC
Targets:
  - monitored_devices: [all production devices]

API Reference

For programmatic schedule management, see the API endpoints:

• POST /schedules - Create schedule
• GET /schedules - List schedules
• GET /schedules/{id} - Get schedule details
• PATCH /schedules/{id} - Update schedule
• DELETE /schedules/{id} - Delete schedule
• POST /schedules/{id}/restore - Restore a deleted schedule
• POST /schedules/{id}/run - Trigger schedule immediately

See architecture/overview.md for detailed technical information.