Skip to main content

​
Overview

Temporal Schedules enable you to run workflows automatically on a specified schedule. Schedules support:
  • Cron-like specifications with calendar awareness
  • Interval-based scheduling for regular execution
  • Timezone support for consistent execution across regions
  • Backfills for retroactive execution of missed runs
  • Pause/unpause capabilities for operational control
Scheduler is implemented using the CHASM (Coordinated Heterogeneous Application State Machines) framework. Each schedule is backed by a durable execution with specialized components.

​
Architecture

The Scheduler implementation uses a hierarchical component structure:

​
Key Components

Buffers automated actions according to the schedule specification. Driven by GeneratorTask timer tasks that fire on the schedule interval.
  • Processes cron expressions and calendar specifications
  • Maintains high water mark for next scheduled action
  • Enqueues buffered starts to the Invoker
Executes buffered actions and handles retry logic. Only component that makes service calls with side effects.
  • Processes buffered starts from Generator and Backfiller
  • Schedules ProcessBufferTask to resolve buffered starts
  • Executes ExecuteTask to call StartWorkflowExecution
  • Handles overlap policies and retry logic
Handles manual backfill requests and trigger requests. One Backfiller component per pending request.
  • Buffers actions from backfill time ranges
  • Driven by BackfillerTask timer tasks
  • Enqueues buffered starts to Invoker for execution

​
Execution Flow

​
Schedule Specification

Schedules support multiple specification types:
Standard cron expressions with calendar awareness:
spec:
  cron: "0 9 * * MON-FRI"
  timezone: "America/New_York"
  • Supports standard 5-field cron syntax
  • Calendar-aware (skips DST transitions correctly)
  • Timezone support for consistent execution

​
Overlap Policies

Control what happens when a scheduled workflow is still running when the next execution is due:

Skip

Skip the new execution if a previous one is still running

Buffer One

Buffer one execution to run when the current one completes

Buffer All

Buffer all executions (limited by configured max)

Cancel Other

Cancel the running execution and start the new one

Terminate Other

Terminate the running execution and start the new one

Allow All

Start new executions regardless of running ones

​
Backfills

Backfills allow you to retroactively execute a schedule for a time range: 
// Example backfill request
backfill := &schedpb.BackfillRequest{
    StartTime: timestamppb.New(time.Now().Add(-7 * 24 * time.Hour)),
    EndTime:   timestamppb.New(time.Now()),
    OverlapPolicy: enumspb.SCHEDULE_OVERLAP_POLICY_ALLOW_ALL,
}
Backfills can generate a large number of workflow executions. Use overlap policies carefully to avoid overwhelming your workers.

​
Pause and Unpause

Schedules can be paused to temporarily stop execution:
  • Paused schedules do not generate new workflow executions
  • Notes can be added when pausing for audit purposes
  • Unpause resumes normal schedule operation
  • Running workflows are not affected by pause

​
State Management

Scheduler maintains several key state elements:
  • Schedule specification - Cron, interval, or calendar definition
  • High water marks - Track next scheduled execution time
  • Buffered starts - Actions queued for execution
  • Remaining actions - Count of limited schedule runs
  • Pause state - Whether schedule is currently paused

​
Monitoring

Key metrics to monitor for schedules:
  • Scheduled actions - Total actions scheduled
  • Executed actions - Successfully executed workflow starts
  • Failed actions - Failed workflow start attempts
  • Buffered actions - Actions waiting in buffer
  • Skipped actions - Actions skipped due to overlap policy

​
Implementation Details

Scheduler is implemented in the CHASM library:
  • Location: chasm/lib/scheduler/
  • Core components: scheduler.go, generator.go, invoker.go, backfiller.go
  • Task types: GeneratorTask, ProcessBufferTask, ExecuteTask, BackfillerTask
  • CHASM framework: Provides lifecycle management and request-reply handlers
The Scheduler implementation is CHASM-based and is not yet generally available. The architecture and implementation may change before general release.

​
See Also

CHASM Architecture

Learn about the CHASM framework underlying schedules

Workflow Lifecycle

Understand how scheduled workflows execute

Build docs developers (and LLMs) love

Get started for freeTalk to us