Schedule trigger node

Schedule Trigger Node

Overview

The Schedule Trigger Node automatically initiates MaestroHub pipelines on a recurring cadence. It supports both advanced cron expressions and high-frequency intervals (milliseconds, seconds, or minutes), giving you the flexibility to automate routine jobs, align pipelines with regional business hours, or capture near real-time telemetry—all without manual intervention.

---

Core Functionality

What It Does

1. Recurring Pipeline Automation Start pipelines on predictable schedules—from hourly refreshes to monthly closing tasks—without relying on user actions.

2. Cron-Based Precision Use six-field cron expressions (including seconds) or cron macros (@daily, @hourly, etc.) to model complex timing scenarios. Powered by robfig/cron/v3 with seconds support.

3. Multi-Unit Intervals Trigger pipelines at millisecond precision (100–900 ms), every 1–30 seconds, or every 1–10 minutes. Millisecond intervals use a dedicated high-precision ticker scheduler with drift compensation; second and minute intervals are converted to cron expressions internally.

4. Timezone Awareness Execute cron schedules in any IANA-recognized timezone so that business processes align with local hours and daylight-saving changes.

5. Custom Output Payloads Attach JSON data to each trigger event. The output data merges with the schedule metadata, making it available to all downstream nodes.

---

Configuration Options

Basic Information

Field	Type	Description
Node Label	String (Required)	Display name for the node on the pipeline canvas. Must be non-empty (trimmed).
Description	String (Optional)	Explains the intent of the automated workflow.

---

Parameters

The schedule configuration is organized across two tabs in the UI: Parameters and Settings.

Parameter	Type	Default	Required	Constraints	Description
Schedule Type	select	"interval"	Yes	cron / interval	Schedule mode selection.
Cron Expression	string	"0 0 0 * * *"	If cron	6-field format (see Cron Reference) or macros (@daily, @hourly)	Cron expression including the seconds field.
Timezone	string	"UTC"	If cron	IANA timezone names (searchable selector with 50+ timezones)	Timezone for cron expression evaluation.
Interval	number	5	If interval	See Interval Constraints	Time between trigger firings.
Interval Unit	select	"seconds"	If interval	milliseconds / seconds / minutes	Unit for the interval value.
Enabled	boolean	true	No	--	Enable/disable the schedule.
Output Data	JSON / null	null	No	Valid JSON or plain string	Custom data payload included on each trigger event.

Interval Constraints

Allowed ranges depend on the selected Interval Unit:

Unit	Allowed Values	Input Control	Scheduler
milliseconds	100, 200, 300, 400, 500, 600, 700, 800, 900	Dropdown selector	TickerScheduler (high-precision, drift-compensated)
seconds	1--30	Numeric input	CronScheduler (converted to cron internally)
minutes	1--10	Numeric input	CronScheduler (converted to cron internally)

note

When switching from cron to interval mode, the UI defaults to 100 milliseconds. When switching from interval to cron, it defaults to 0 0 0 * * * (daily at midnight).

---

Settings

Description

A free-text area for documenting the node's purpose and behavior. Notes entered here are saved with the pipeline and visible to all team members.

Execution Settings

Setting	Options	Default	Description
Timeout (seconds)	number	Pipeline default	Maximum execution time for this node (1--600). Leave empty for pipeline default.
Retry on Timeout	Pipeline Default / Enabled / Disabled	Pipeline Default	Whether to retry the node if it times out.
Retry on Fail	Pipeline Default / Enabled / Disabled	Pipeline Default	Whether to retry on failure. When Enabled, shows Advanced Retry Configuration.
On Error	Pipeline Default / Stop Pipeline / Continue Execution	Pipeline Default	Behavior when node fails after all retries.

Advanced Retry Configuration (visible when Retry on Fail = Enabled)

Field	Type	Default	Range	Description
Max Attempts	number	3	1--10	Maximum retry attempts.
Initial Delay (ms)	number	1000	100--30,000	Wait before first retry.
Max Delay (ms)	number	120000	1,000--300,000	Upper bound for backoff delay.
Multiplier	number	2.0	1.0--5.0	Exponential backoff multiplier.
Jitter Factor	number	0.1	0--0.5	Random jitter (+-percentage).

---

Output Data Structure

When the schedule fires, the trigger node produces a structured output with two top-level keys: _metadata and payload. The output varies slightly depending on the schedule type.

Cron Trigger Output

{
  "_metadata": {
    "type": "cron_trigger",
    "scheduled_time": "2026-02-11T09:00:00Z",
    "cron_expr": "0 0 9 * * *",
    "timezone": "UTC"
  },
  "payload": {}
}

Field	Type	Description
_metadata.type	string	Always "cron_trigger" for cron schedules.
_metadata.scheduled_time	string	ISO 8601 timestamp of the scheduled firing time.
_metadata.cron_expr	string	The cron expression that triggered the execution.
_metadata.timezone	string	IANA timezone used for evaluation.
payload	object	Empty by default; populated by Output Data if configured.

Interval Trigger Output

{
  "_metadata": {
    "type": "interval_trigger",
    "scheduled_time": "2026-02-11T14:30:00.500Z",
    "interval": 500,
    "interval_unit": "milliseconds"
  },
  "payload": {}
}

Field	Type	Description
_metadata.type	string	Always "interval_trigger" for interval schedules.
_metadata.scheduled_time	string	ISO 8601 timestamp of the trigger firing time.
_metadata.interval	number	The interval value.
_metadata.interval_unit	string	The interval unit ("milliseconds", "seconds", or "minutes").
payload	object	Empty by default; populated by Output Data if configured.

Output Data Merge Behavior

When you configure Output Data (a JSON object), its fields are merged at the top level of the trigger data alongside _metadata and payload. For example, if Output Data is {"triggeredBy": "schedule", "region": "us-east"}, the downstream output becomes:

{
  "_metadata": {
    "type": "cron_trigger",
    "scheduled_time": "2026-02-11T09:00:00Z",
    "cron_expr": "0 0 9 * * *",
    "timezone": "UTC"
  },
  "payload": {},
  "triggeredBy": "schedule",
  "region": "us-east"
}

Referencing in Downstream Nodes

Use expressions to access schedule data in subsequent nodes:

• $trigger._metadata.type -- "cron_trigger" or "interval_trigger"
• $trigger._metadata.scheduled_time -- when the schedule fired
• $trigger._metadata.cron_expr -- cron expression (cron mode only)
• $trigger._metadata.timezone -- timezone (cron mode only)
• $trigger._metadata.interval -- interval value (interval mode only)
• $trigger._metadata.interval_unit -- interval unit (interval mode only)
• $trigger.triggeredBy -- custom field from Output Data (if configured)

---

Validation Rules

The Schedule Trigger Node enforces validation at both the frontend (UI) and backend levels.

Node Configuration Validation

Label Requirements

• Must not be empty
• Must not contain only whitespace
• Error: "Node name is required"

Schedule Type Validation

• Must be either cron or interval
• Error: "Schedule type must be either 'cron' or 'interval'"

Cron Mode Validation (scheduleType = "cron")

• Cron expression is required and must not be empty
• Must contain six space-separated fields (or be a valid macro like @daily)
• Supports cron macros: @daily, @hourly, @weekly, etc.
• Syntax validation deferred to the cron library at runtime
• Errors:
  • "Cron expression is required for cron schedule type"
  • "Cron expression must have exactly 6 fields (second minute hour day month day-of-week)"

Interval Mode Validation (scheduleType = "interval")

Validation depends on the selected Interval Unit:

Unit	Constraint	Error
milliseconds	Must be one of: 100, 200, 300, 400, 500, 600, 700, 800, 900	"Interval must be one of: 100, 200, 300, 400, 500, 600, 700, 800, 900 for milliseconds"
seconds	Must be between 1 and 30	"Interval must be between 1 and 30 for seconds"
minutes	Must be between 1 and 10	"Interval must be between 1 and 10 for minutes"

Additional rules:

• Interval value is required and must be a number greater than 0
• Interval unit is required and must be one of milliseconds, seconds, or minutes
• Cron expression is ignored in interval mode
• Errors:
  • "Interval value is required for interval schedule type"
  • "Interval unit is required for interval schedule type"
  • "Interval unit must be milliseconds, seconds, or minutes"

Timezone Validation

• Must be a string if provided
• Error: "Timezone must be a valid string"

---

Usage Examples

Daily Report Generation (Cron)

Key configuration

• Label: Daily Report Generator
• Description: Runs every day at 09:00 local time
• Parameters: cron schedule (0 0 9 * * *), timezone America/New_York, schedule enabled
• Output data: {"type": "daily", "recipients": ["admin@company.com", "manager@company.com"], "format": "pdf"}
• Settings: retry disabled, on error stop

Downstream usage: $trigger._metadata.cron_expr for audit logging, $trigger.type to identify the report type, $trigger.recipients for the mailing list.

15-Minute Health Monitoring (Cron)

Key configuration

• Label: System Health Monitor
• Description: Checks critical services every 15 minutes
• Parameters: cron schedule (0 */15 * * * *), timezone UTC, schedule enabled
• Output data: {"checkType": "health", "targets": ["api", "database", "cache"], "alertThreshold": 90}
• Settings: retry enabled, on error continue

Downstream usage: $trigger.targets to iterate over services, $trigger.alertThreshold to set the failure threshold.

High-Frequency Sensor Collection (Interval - Milliseconds)

Key configuration

• Label: IoT Sensor Data Collector
• Description: Captures readings every 500 milliseconds
• Parameters: interval 500 ms, schedule enabled
• Output data: {"sensorGroup": "temperature-monitors", "metrics": ["temperature", "humidity", "pressure"]}
• Settings: retry disabled, on error stop

Downstream usage: $trigger._metadata.interval to verify tick rate, $trigger.sensorGroup to identify the sensor cluster.

Every-5-Seconds Queue Processor (Interval - Seconds)

Key configuration

• Label: Queue Processor
• Description: Drains the outbound message queue every 5 seconds
• Parameters: interval 5 seconds, schedule enabled
• Output data: {"queue": "outbound-messages", "batchSize": 50}
• Settings: retry enabled, on error continue

Downstream usage: $trigger.queue to select the target queue, $trigger.batchSize to limit processing.

Weekly Data Cleanup (Cron)

Key configuration

• Label: Weekly Data Cleanup
• Description: Purges stale data every Sunday at midnight
• Parameters: cron schedule (0 0 0 * * SUN), timezone America/New_York, schedule enabled
• Output data: {"cleanupType": "weekly", "retentionDays": 90, "targets": ["logs", "temp_files", "cache"]}
• Settings: retry enabled, on error stop

Downstream usage: $trigger.retentionDays to calculate the cutoff date, $trigger.targets to iterate over cleanup targets.

Temporarily Disabled Schedule (Cron)

Key configuration

• Label: Disabled Weekend Notification
• Description: Weekend notifications (currently paused for summer)
• Parameters: cron schedule (0 0 10 * * SAT,SUN), timezone Asia/Tokyo, schedule disabled
• Output data: {"notificationType": "weekend-summary", "recipients": ["team@company.jp"]}
• Settings: retry disabled, on error stop

Downstream usage: Pipeline will not execute until Enabled is toggled back on.

---

Best Practices

Choosing the Right Schedule Type

Use Cron When

• Jobs rely on specific days, hours, or weekdays
• Timezone alignment and daylight-saving adjustments matter
• You need readable patterns like "every weekday at 09:00"

Use Interval When

• You require high-frequency execution (sub-second to every few minutes)
• Workloads are timezone-agnostic
• Near real-time monitoring or ingestion is required

Avoid

• Long-duration intervals (use cron instead for anything over 10 minutes)
• Cron schedules for sub-second timings (cron minimum resolution is 1 second)

Cron Expression Reference

Always provide six fields: second minute hour day month day-of-week

Field	Range	Special Characters
Second	0-59	*, ,, -, /
Minute	0-59	*, ,, -, /
Hour	0-23	*, ,, -, /
Day of Month	1-31	*, ,, -, /, ?
Month	1-12	*, ,, -, /
Day of Week	0-7 (0 and 7 = Sunday)	*, ,, -, /, ?

Common Examples (also available as click-to-apply presets in the UI)

Expression	Description
0 0 0 * * *	Daily at midnight
0 */15 * * * *	Every 15 minutes
0 0 9 * * MON	Mondays at 9 AM
0 30 14 * * FRI	Fridays at 2:30 PM
0 0 */2 * * *	Every 2 hours
0 0 0 1 * *	First day of every month
30 0 0 * * *	Daily at 12:00:30 AM
@daily	Daily at midnight (macro)
@hourly	Every hour (macro)

• Prefer macros for readable daily or hourly schedules
• Document business meaning for complex expressions
• Remember to add the leading seconds field when converting from traditional five-field cron tools

Managing Timezones

• Explicitly set the timezone instead of relying on UTC
• Use full IANA identifiers (e.g., America/New_York, not EST)
• Consider daylight-saving transitions when scheduling jobs around local midnight
• For multi-region operations, deploy dedicated nodes per region
• The timezone selector in the UI supports 50+ timezones grouped by region (UTC, North America, Europe, Asia-Pacific, South America, Africa) with search and UTC offset display

Working with Intervals

• Start with higher intervals in testing, then tighten as needed
• Monitor infrastructure load; sub-second triggers can create backpressure
• Avoid 100ms intervals in production without robust throughput handling
• Millisecond intervals use a dedicated TickerScheduler with drift compensation for precision
• Second and minute intervals are converted to cron expressions internally, so they have 1-second resolution

Interval Guidance

Interval	Example Use Case	Risk Guidance
100--200 ms	Real-time monitoring	High load: reserve for short-lived bursts only.
300--500 ms	Frequent data collection	Elevated load: monitor worker utilization closely.
600--900 ms	Regular heartbeat checks	Moderate load: safe default for most workloads.
1--5 seconds	Queue draining, polling	Low load: suitable for most production workloads.
5--30 seconds	Periodic syncs, light ETL	Minimal load: broadly safe.
1--10 minutes	Batch processing, reports	Negligible load: use for non-urgent periodic tasks.

Designing Output Payloads

• Keep payloads concise and structured
• Include metadata such as scheduleType, expression, or timezone for downstream routing
• Document downstream expectations to avoid schema drift
• Avoid bloated payloads that slow downstream processing
• Remember: Output Data fields merge at the top level alongside _metadata and payload

Enable vs. Disable

• Use enabled: false for temporary pauses (maintenance, seasonal shutdowns)
• Document the reason in the Settings description note
• Delete the node only when the schedule is no longer needed

Error Handling

• Enable retries for critical cron jobs where transient failures occur
• Combine retries with monitoring to avoid silent failures
• Keep retries disabled for high-frequency interval schedules to prevent overload