Schedules

Schedules let you run operations on a recurring basis using cron expressions. Use them for automated data syncs, report generation, content cleanup, and any task that needs to happen on a regular cadence.

Overview

A schedule connects a cron expression to an operation. At the configured times, Foir triggers the operation automatically. Schedules support timezones, pause/resume, and manual triggering for testing.

Key Concepts

• Cron expression: defines when the schedule runs (e.g., 0 9 * * * for daily at 9am)
• Operation: the HTTP endpoint that is called when the schedule fires
• Timezone: all cron expressions are evaluated in the configured timezone
• Status: schedules can be active (running on schedule) or paused

In the Admin

Creating a Schedule

1. Go to Automation > Schedules
2. Click Create Schedule
3. Configure:
   • Key: unique identifier (e.g., daily-sync)
   • Name: display name (e.g., “Daily Data Sync”)
   • Cron Expression: when to run (e.g., 0 9 * * *)
   • Timezone: timezone for cron evaluation (e.g., America/New_York)
   • Operation: the operation to execute
   • Input (optional): static input data passed to the operation
4. Save

The schedule starts in an active state and will run at the next matching time.

Pause and Resume

• Click Pause to temporarily stop a schedule. It will not fire until resumed.
• Click Resume to reactivate a paused schedule.

Manual Trigger

Click Trigger Now to execute the schedule’s operation immediately, regardless of the cron expression. Useful for testing or running an ad-hoc execution.

Monitoring

The schedule list shows:

• Cron expression: the configured schedule
• Last run status: whether the most recent execution succeeded or failed
• Next run: when the schedule will fire next

Click a schedule to view its execution history.

Via the CLI

# List all schedules
foir schedules list
 
# Get a schedule by key
foir schedules get <key>
 
# Create a schedule
foir schedules create --data '{
  "key": "daily-sync",
  "name": "Daily Data Sync",
  "cron": "0 9 * * *",
  "timezone": "America/New_York",
  "operationKey": "sync-external-data"
}'
 
# Update a schedule
foir schedules update <key> --data '{"cron": "0 */6 * * *"}'
 
# Trigger a schedule immediately
foir schedules trigger <key>
 
# Pause a schedule
foir schedules pause <key>
 
# Resume a paused schedule
foir schedules resume <key>
 
# Delete a schedule
foir schedules delete <key>

Via the API

Schedules are managed through the admin API. The operation that a schedule triggers receives a standard OperationPayload with no record context (since schedules are not tied to specific records).

Config System

Schedules can also be defined in foir.config.ts using defineSchedule. See the Configuration reference for details.

Cron Expression Reference

Cron expressions use the standard five-field format:

*    *    *    *    *
|    |    |    |    |
|    |    |    |    +--- Day of week (0-7, where 0 and 7 are Sunday)
|    |    |    +-------- Month (1-12)
|    |    +------------- Day of month (1-31)
|    +------------------ Hour (0-23)
+----------------------- Minute (0-59)

Common Examples

Use Cases

Data Sync

Sync content or customer data from an external system on a regular cadence:

{
  "key": "shopify-sync",
  "cron": "0 */2 * * *",
  "operationKey": "sync-shopify-products"
}

Report Generation

Generate daily analytics reports and send them to your team:

{
  "key": "daily-report",
  "cron": "0 8 * * 1-5",
  "operationKey": "generate-analytics-report"
}

Content Cleanup

Remove expired or draft content on a weekly basis:

{
  "key": "weekly-cleanup",
  "cron": "0 2 * * 0",
  "operationKey": "cleanup-expired-content"
}

Best Practices

• Use descriptive keys — daily-product-sync is clearer than schedule-1.
• Set the correct timezone — cron expressions are evaluated against the configured timezone, so choose the one that matches your business operations.
• Test with manual trigger — use foir schedules trigger <key> to verify the operation works before relying on the cron schedule.
• Monitor execution history — check the schedule detail page or foir operations stats for failures.
• Keep operations idempotent — schedules may occasionally double-fire due to infrastructure events; your operations should handle this gracefully.
• Start with longer intervals — begin with daily or hourly schedules and increase frequency only when needed.