Scheduling Reference
This page documents how to configure workflow schedules in Zenmako, including schedule types, cron expressions, timezone handling, and execution timing.
Schedule Types
Zenmako supports two schedule types for workflows:
One-off Schedule
Executes the workflow once at a specific date and time.
type | one-off |
datetime | ISO 8601 datetime (e.g., 2026-03-15T09:00:00) |
timezone | IANA timezone identifier (optional) |
Example:
{
"type": "one-off",
"datetime": "2026-03-15T09:00:00",
"timezone": "America/New_York"
}
Repeating Schedule
Executes the workflow on a recurring basis using cron expressions.
type | repeating |
cron | Cron expression defining the schedule |
timezone | IANA timezone identifier (optional) |
Example:
{
"type": "repeating",
"cron": "0 9 MON-FRI",
"timezone": "Europe/London"
}
Preset Schedules
For common use cases, use these preset cron expressions:
| Preset | Cron Expression | Description |
| Every 15 minutes | /15 | Runs at minutes 0, 15, 30, 45 of every hour |
| Hourly | 0 | Runs at the start of every hour |
| Daily at 9am | 0 9 | Runs at 9:00 AM every day |
| Weekly on Monday at 9am | 0 9 MON | Runs at 9:00 AM every Monday |
| Monthly on the 1st at 9am | 0 9 1 | Runs at 9:00 AM on the 1st of each month |
Custom Cron Expressions
Cron Syntax
Zenmako uses standard 5-field cron syntax:
┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12 or JAN-DEC)
│ │ │ │ ┌───────────── day of week (0-6 or SUN-SAT, where 0 = Sunday)
│ │ │ │ │
Special Characters
| Any value | (every minute) |
, | Value list | 0,30 (at 0 and 30 minutes) |
- | Range | 0 9-17 (9am to 5pm, hourly) |
/ | Step | /15 (every 15 minutes) |
Examples
| Cron Expression | Description |
0 9 MON-FRI | Weekdays at 9:00 AM |
0 /4 | Every 4 hours (at 0:00, 4:00, 8:00, etc.) |
30 8 1 | 8:30 AM on the 1st of every month |
0 6 1 | 6:00 AM every Monday |
0 0 | Midnight every day |
0 12 15 | Noon on the 15th of every month |
0 9 1,3,5 | 9:00 AM on Monday, Wednesday, and Friday |
0 8-18 MON-FRI | Every hour from 8 AM to 6 PM on weekdays |
Timezone Handling
Setting a Timezone
Specify the timezone using an IANA timezone identifier:
{
"type": "repeating",
"cron": "0 9 ",
"timezone": "America/Los_Angeles"
}
Common Timezone Identifiers
| US Eastern | America/New_York |
| US Central | America/Chicago |
| US Mountain | America/Denver |
| US Pacific | America/Los_Angeles |
| UK | Europe/London |
| Central Europe | Europe/Berlin |
| India | Asia/Kolkata |
| Japan | Asia/Tokyo |
| Australia Eastern | Australia/Sydney |
Default Timezone
If no timezone is specified, schedules use UTC.
Daylight Saving Time
Timezones that observe daylight saving time (DST) are handled automatically. A workflow scheduled for 9:00 AM in America/New_York will run at 9:00 AM local time year-round, regardless of DST changes.
Execution Timing
Polling-Based System
Zenmako uses a polling-based scheduler that checks for due workflows every 15 minutes.
Polling windows:
:00 (on the hour)
:15
:30
:45
Execution Window
Due to the polling mechanism, workflows execute within 0 to 15 minutes of their scheduled time.
| Scheduled Time | Earliest Execution | Latest Execution |
| 9:00 AM | 9:00 AM | 9:14 AM |
| 9:05 AM | 9:15 AM | 9:29 AM |
| 9:20 AM | 9:30 AM | 9:44 AM |
Why This Matters
Consider execution timing when:
Time-sensitive operations: If a task must complete by a deadline, schedule it with sufficient buffer time.
Coordinating with external systems: Account for the potential 15-minute delay when integrating with time-sensitive APIs.
Sequential workflows: When one workflow depends on another completing first, add appropriate margins.
Example: To ensure a report is ready by 10:00 AM, schedule it for 9:30 AM or earlier to account for both the execution window and processing time.
Limitations
Minimum Frequency
The minimum scheduling frequency is 15 minutes. Cron expressions that would trigger more frequently are not supported.
/15 | Yes | Every 15 minutes |
/10 | No | Every 10 minutes (too frequent) |
/5 | No | Every 5 minutes (too frequent) |
| No | Every minute (too frequent) |
No Second-Level Precision
Cron expressions in Zenmako do not support seconds. The smallest unit of time is minutes.
Execution Precision
Due to the polling-based architecture, exact-to-the-minute execution is not guaranteed. Plan for a 0-15 minute variance from the scheduled time.
Quick Reference
Schedule Configuration Template
{
"schedule": {
"type": "repeating",
"cron": "0 9 MON-FRI",
"timezone": "America/New_York"
}
}
Common Patterns
| Business hours check (every 15 min, 9-5 weekdays) | /15 9-17 MON-FRI |
| Daily morning report | 0 8 |
| Weekly summary (Friday afternoon) | 0 17 FRI |
| Monthly billing (1st at midnight) | 0 0 1 |
| Quarterly review (1st of Jan, Apr, Jul, Oct) | 0 9 1 1,4,7,10 |
Zenmako