> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/temporalio/temporal/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow Schedules

> Run workflows on automated schedules with cron-like specifications and calendar support

## 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

<Note>
  Scheduler is implemented using the CHASM (Coordinated Heterogeneous Application State Machines) framework. Each schedule is backed by a durable execution with specialized components.
</Note>

## Architecture

The Scheduler implementation uses a hierarchical component structure:

```mermaid theme={null}
classDiagram
    direction TB
    
    class Scheduler {
        Schedule Input
        Payloads
        Shared State
        IdleTask()
    }
    class Generator {
        High Water Mark
        GeneratorTask()
    }
    class Invoker {
        High Water Mark
        Buffered Starts
        ProcessBufferTask()
        ExecuteTask()
    }
    class Backfiller {
        High Water Mark
        Backfill Input
        BackfillerTask()
    }
    
    Scheduler --> Generator
    Scheduler --> Invoker
    Scheduler ..> "0..*" Backfiller
```

### Key Components

<AccordionGroup>
  <Accordion title="Generator" icon="repeat">
    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
  </Accordion>

  <Accordion title="Invoker" icon="play">
    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
  </Accordion>

  <Accordion title="Backfiller" icon="clock-rotate-left">
    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
  </Accordion>
</AccordionGroup>

## Execution Flow

```mermaid theme={null}
sequenceDiagram
    participant Generator
    participant Invoker
    participant FrontendService

    loop specification interval
        Generator->>Generator: execute GeneratorTask

        Generator->>Invoker: enqueue buffered starts
        Invoker->>Invoker: schedule ProcessBufferTask
        Invoker-->>Generator: 
        Generator->>Generator: schedule GeneratorTask
    end

    Invoker->>Invoker: execute ProcessBufferTask
    Invoker->>Invoker: resolve buffered starts
    Invoker->>Invoker: schedule ExecuteTask
    Invoker->>Invoker: execute ExecuteTask
    Invoker->>FrontendService: call StartWorkflowExecution
    FrontendService-->>Invoker: 
```

## Schedule Specification

Schedules support multiple specification types:

<Tabs>
  <Tab title="Cron">
    Standard cron expressions with calendar awareness:

    ```yaml theme={null}
    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
  </Tab>

  <Tab title="Interval">
    Fixed interval between executions:

    ```yaml theme={null}
    spec:
      interval: "1h30m"
      phase: "30m"
    ```

    * Duration-based scheduling
    * Optional phase offset for alignment
  </Tab>

  <Tab title="Calendar">
    Complex calendar-based scheduling:

    ```yaml theme={null}
    spec:
      calendar:
        - dayOfMonth: 1
          hour: 9
          minute: 0
        - dayOfWeek: "MON"
          hour: 14
          minute: 30
    ```

    * Multiple time specifications
    * Day, month, year constraints
    * Holiday awareness
  </Tab>
</Tabs>

## Overlap Policies

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

<CardGroup cols={2}>
  <Card title="Skip" icon="forward">
    Skip the new execution if a previous one is still running
  </Card>

  <Card title="Buffer One" icon="layer-group">
    Buffer one execution to run when the current one completes
  </Card>

  <Card title="Buffer All" icon="layers">
    Buffer all executions (limited by configured max)
  </Card>

  <Card title="Cancel Other" icon="ban">
    Cancel the running execution and start the new one
  </Card>

  <Card title="Terminate Other" icon="circle-xmark">
    Terminate the running execution and start the new one
  </Card>

  <Card title="Allow All" icon="check-double">
    Start new executions regardless of running ones
  </Card>
</CardGroup>

## Backfills

Backfills allow you to retroactively execute a schedule for a time range:

```go theme={null}
// 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,
}
```

<Warning>
  Backfills can generate a large number of workflow executions. Use overlap policies carefully to avoid overwhelming your workers.
</Warning>

## 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

<Info>
  The Scheduler implementation is CHASM-based and is not yet generally available. The architecture and implementation may change before general release.
</Info>

## See Also

<CardGroup cols={2}>
  <Card title="CHASM Architecture" href="/architecture/chasm">
    Learn about the CHASM framework underlying schedules
  </Card>

  <Card title="Workflow Lifecycle" href="/architecture/workflow-lifecycle">
    Understand how scheduled workflows execute
  </Card>
</CardGroup>