Scheduled Trigger

The Scheduled Trigger node starts a workflow based on a cron schedule. Use it for time-based automations like daily summaries, weekly reports, or periodic data sync tasks.

Overview

Configuration

Cron Expression Format

Scheduled Trigger uses 6-field cron expressions:

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

Special characters:

• * - Any value
• , - Value list separator (1,3,5)
• - - Range (1-5)
• / - Step values (*/15 = every 15)

Timezone

Use IANA timezone identifiers:

• America/New_York
• America/Los_Angeles
• Europe/London
• Asia/Tokyo
• UTC

Full list: IANA Time Zone Database

Output Schema

The Scheduled Trigger outputs:

{
  "organizationId": "org_123456",
  "event": "SCHEDULED",
  "firedAt": "2024-01-15T09:00:00.000Z",
  "scheduledFor": "2024-01-15T09:00:00.000Z"
}

Note: Unlike Event Trigger, Scheduled Trigger does NOT include meetingPlanId or dealRoomId. The workflow must fetch any needed data.

Examples

Basic Example: Daily at 9 AM

Run a workflow every day at 9 AM Eastern time:

Configuration:

• Cron Expression: 0 0 9 * * *
• Timezone: America/New_York

Second: 0    (at second 0)
Minute: 0    (at minute 0)
Hour:   9    (at 9 AM)
Day:    *    (every day)
Month:  *    (every month)
DoW:    *    (any day of week)

Common Schedule Examples

Advanced Example: Weekly Summary Report

Generate a weekly summary every Monday at 8 AM Pacific:

Configuration:

• Cron Expression: 0 0 8 * * 1
• Timezone: America/Los_Angeles

Workflow pattern:

[Scheduled Trigger]
        │
        ▼
[Query Meetings from Past Week] ──── Custom logic to fetch data
        │
        ▼
[AI Agent] ────────────────────── Generate summary report
        │
        ▼
[Email Send] ──────────────────── Send to stakeholders

Example: Business Hours Only

Run every hour during business hours (9 AM - 5 PM) on weekdays:

Configuration:

• Cron Expression: 0 0 9-17 * * 1-5
• Timezone: America/New_York

Best Practices

1. Choose Appropriate Frequency

Minimum interval: 4 hours is the recommended minimum to avoid excessive executions.

2. Account for Timezone

Always consider:

• User location: When will recipients see this?
• Business hours: Avoid sending at inappropriate times
• DST transitions: Cron uses local time, so be aware of shifts

3. Handle No-Data Scenarios

Scheduled workflows may run when there's nothing to process:

[Scheduled Trigger]
        │
        ▼
[Query Data]
        │
        ▼
[If: items exist?]
    ├── Yes ──▶ [Process and Send]
    └── No ───▶ [Sink] (do nothing)

4. Provide Context in Output

Since scheduled triggers lack meeting context, include schedule info in output:

📅 Weekly Summary Report
Generated: {{ trigger.firedAt | date: "%B %d, %Y" }}

{{ json.summaryContent }}

Common Issues

Workflow doesn't run at expected time

Symptoms: Missed scheduled execution

Solutions:

1. Verify cron expression is correct (use a cron validator)
2. Check timezone is set correctly
3. Ensure workflow is Active (released)
4. Review execution history around scheduled time

Wrong timezone behavior

Symptoms: Runs at wrong time of day

Solutions:

1. Verify IANA timezone identifier is correct
2. Check for DST if near a time change
3. Test with a known timezone like UTC first

Too many executions

Symptoms: Workflow runs more frequently than expected

Solutions:

1. Review cron expression (common mistake: * * * * * * runs every second!)
2. Check for multiple Active versions
3. Verify step values are correct (*/15 vs 15)

Related Nodes

• Event Trigger - Event-based triggers
• Wait - Delay within workflows

Technical Details

Schedule Materialization

The system looks ahead to find upcoming schedule times:

• Lookahead window: 5 minutes (configurable)
• Lookback window: 2 minutes (catch-up for missed)
• Max occurrences: 500 per window

Schedule State Tracking

A cursor tracks the last processed schedule time:

• Prevents duplicate executions
• Allows catch-up for brief system downtime
• Resets on workflow version change

Fire Time vs Execution Time

scheduledFor: 09:00:00  ──── When it was supposed to run
firedAt:      09:00:03  ──── When it actually executed

Small differences (seconds) are normal due to system processing.

Cron Parser

Uses the cron-parser library with full standard cron support:

• 6-field format (with seconds)
• Timezone-aware
• Standard special characters

Cron Expression Quick Reference

Field        Values         Special Characters
─────────────────────────────────────────────
Second       0-59           * , - /
Minute       0-59           * , - /
Hour         0-23           * , - /
Day (Month)  1-31           * , - /
Month        1-12           * , - /
Day (Week)   0-6 (Sun=0)    * , - /

Helpful Patterns