Scheduling & Timers

Scheduled triggers allow workflows to run at specific times rather than in response to events. This enables daily reports, weekly digests, periodic checks, and other time-based automations.

Overview

The scheduling system:

• Uses standard cron expressions with timezone support
• Materializes schedule occurrences ahead of time for reliability
• Handles timezone differences correctly
• Supports high-frequency to annual schedules

Cron Expression Syntax

Standard 6-Field Format

┌───────────── second (0-59)
│ ┌───────────── minute (0-59)
│ │ ┌───────────── hour (0-23)
│ │ │ ┌───────────── day of month (1-31)
│ │ │ │ ┌───────────── month (1-12)
│ │ │ │ │ ┌───────────── day of week (0-6, Sun-Sat)
│ │ │ │ │ │
│ │ │ │ │ │
* * * * * *

Field Values

Special Characters

Common Schedule Examples

Daily Schedules

Every day at 9:00 AM:

0 0 9 * * *

Every day at midnight:

0 0 0 * * *

Every day at 6:00 PM:

0 0 18 * * *

Weekly Schedules

Every Monday at 9:00 AM:

0 0 9 * * 1

Every Friday at 5:00 PM:

0 0 17 * * 5

Every weekday (Mon-Fri) at 8:00 AM:

0 0 8 * * 1-5

Monthly Schedules

First day of every month at 9:00 AM:

0 0 9 1 * *

Last day of every month at noon:

0 0 12 L * *

15th of every month at 10:00 AM:

0 0 10 15 * *

Frequent Schedules

Every 15 minutes:

0 */15 * * * *

Every hour at minute 0:

0 0 * * * *

Every 5 minutes during business hours:

0 */5 9-17 * * 1-5

Quarterly/Annual

Quarterly (Jan, Apr, Jul, Oct 1st):

0 0 9 1 1,4,7,10 *

Annually on January 1st:

0 0 9 1 1 *

Timezone Configuration

Supported Timezones

The platform uses IANA timezone identifiers:

Daylight Saving Time

The system handles DST transitions correctly:

• Spring Forward: Schedule may skip the non-existent hour
• Fall Back: Schedule runs once (not twice) during repeated hour

Example with Timezone

Daily at 9:00 AM Pacific Time:

{
  "cronExpression": "0 0 9 * * *",
  "timezone": "America/Los_Angeles"
}

This runs at 9 AM Pacific regardless of DST (9 AM PDT in summer, 9 AM PST in winter).

How Scheduling Works

Materialization Process

1. Scheduler Timer: Runs every minute
2. Lookahead Window: Materializes events 5 minutes ahead
3. Occurrence Enumeration: Calculates all trigger times in window
4. Event Queuing: Creates system events for each occurrence
5. Cursor Tracking: Remembers last processed time

Reliability Features

Cursor-Based Processing

• Tracks last processed time per schedule
• Prevents duplicate triggers
• Handles system restarts gracefully

Overlap Protection

• Small overlap window catches edge cases
• Deduplication prevents double-execution

Backlog Handling

• If system is down, catches up on missed windows
• Configurable maximum occurrences per window (default: 500)

Configuration

Schedule Trigger Setup

1. Open workflow in editor
2. Add a Scheduled Trigger node
3. Configure cron expression
4. Set timezone
5. Connect to downstream nodes

Example Configuration

trigger:
  type: SCHEDULED
  cronExpression: "0 0 9 * * 1-5"
  timezone: "America/New_York"

Use Cases

1. Daily Digest

Send a daily summary of all meetings:

[Scheduled: 0 0 9 * * *] → [Load Yesterday's Meetings] → [AI: Summarize] → [Send Email]

2. Weekly Pipeline Report

Generate weekly pipeline status:

[Scheduled: 0 0 9 * * 1] → [Load Open Deals] → [Generate Report] → [Send to Team]

3. End-of-Day Tasks

Create tasks for meetings without follow-up:

[Scheduled: 0 0 17 * * 1-5] → [Load Today's Meetings] → [Filter: No follow-up] → [Create Tasks]

4. Monthly Review

Send monthly deal review reminders:

[Scheduled: 0 0 9 1 * *] → [Load Stale Deals] → [Send Review Reminder]

5. Hourly Sync

Sync data with external systems:

[Scheduled: 0 0 * * * *] → [Load Changes] → [Sync to CRM]

Best Practices

1. Use Descriptive Times

Choose meaningful times for your audience:

✅ Good: 9 AM local time for daily reports ❌ Bad: Arbitrary times like 3:47 AM

2. Consider Timezone

Always specify the timezone explicitly:

{
  "cronExpression": "0 0 9 * * *",
  "timezone": "America/New_York"  // Be explicit
}

3. Avoid High-Frequency Schedules

Be cautious with very frequent schedules:

4. Test Schedule Expressions

Verify your cron expression:

1. Use online cron expression testers
2. Check next few occurrences
3. Verify timezone handling
4. Test DST transitions

5. Handle Empty Results

Your workflow should handle days with no data:

[Scheduled] → [Load Data] → [If: has data?]
                                  │
                                  ├── Yes → [Process]
                                  │
                                  └── No → [Sink]

Common Issues

Issue: Schedule Not Firing

Possible causes:

1. Cron expression syntax error
2. Timezone mismatch
3. Workflow not released
4. Schedule reference count is 0

Solution:

• Verify cron syntax
• Check timezone setting
• Confirm workflow is released and Active

Issue: Running at Wrong Time

Possible cause: Timezone configuration issue.

Solution:

• Verify timezone identifier is correct
• Check if DST is affecting the time
• Use UTC if timezone handling is complex

Issue: Duplicate Executions

Possible cause: Overlapping schedule expressions.

Solution:

• Review all scheduled workflows
• Ensure deduplication logic in workflow
• Check for multiple triggers with same schedule

Issue: Missing Executions

Possible cause: System was down during scheduled time.

Solution:

• System catches up on restart
• Check execution logs for backfill
• Consider longer lookahead for critical schedules

Advanced Patterns

Pattern 1: Conditional Scheduling

Skip execution on holidays:

[Scheduled: Daily] → [Check: Is holiday?]
                            │
                            ├── Yes → [Sink]
                            │
                            └── No → [Execute]

Pattern 2: Cascade Schedules

Run dependent workflows in sequence:

[Scheduled: 8:00 AM] → [Data Prep]
[Scheduled: 9:00 AM] → [If: Prep complete?] → [Generate Report]

Pattern 3: Business Hours Only

Combine schedule with time check:

[Scheduled: Every 15 min] → [If: Business hours?] → [Action]

Related

• Scheduled Trigger Node
• Wait Node
• Event Trigger Node