Triggers - xyOps

Overview

Triggers in xyOps define when and how an event (or workflow) is allowed to run jobs. You compose one or more triggers on an event to describe automatic schedules, one-time launches, manual control, blackout windows, and optional behaviors like catch-up, delays, and sub-minute precision. The scheduler evaluates triggers once per minute (with optional second-level precision), launches matching jobs, and enforces any options.

Each trigger is a small definition object with two core fields: enabled and type. Extra fields depend on the type.

Trigger Types

xyOps supports several trigger types that can be combined:

Launching Triggers: manual, schedule, interval, single, magic, keyboard, startup
Modifier Triggers: catchup, range, blackout, delay, precision, quiet, plugin

Manual Run

Allow the event to be launched on demand by users (UI) and API keys (API). Does not produce automatic runs.

{
  "type": "manual",
  "enabled": true
}

If an event does not have an enabled manual trigger, attempts to run it via the API/UI are rejected (unless using test paths).

Schedule

Define a repeating schedule similar to Unix Cron using arrays of years, months, days, weekdays, hours, and minutes. Omitted fields mean “all” in that category.

Parameters

Name	Type	Description
`years`	Array(Number)	Years in YYYY format
`months`	Array(Number)	Months 1-12 (Jan=1, Dec=12)
`days`	Array(Number)	Month days 1-31, or reverse days −1 to −7
`weekdays`	Array(Number)	Weekdays 0-6 (Sun=0, Sat=6)
`hours`	Array(Number)	Hours 0-23 (24-hour clock)
`minutes`	Array(Number)	Minutes 0-59
`timezone`	String	IANA timezone (defaults to server timezone)
`params`	Object	Parameter overrides for event/plugin
`tags`	Array	Tag IDs to add to job on start

Examples

Twice Daily

Run at 4:30 AM and 4:30 PM in New York:

{
  "type": "schedule",
  "enabled": true,
  "hours": [4, 16],
  "minutes": [30],
  "timezone": "America/New_York"
}

Last Day of Month

Run on last day of every month at 23:55:

{
  "type": "schedule",
  "enabled": true,
  "days": [-1],
  "hours": [23],
  "minutes": [55]
}

Weekday Mornings

Run Monday-Friday at 9:00 AM:

{
  "type": "schedule",
  "enabled": true,
  "weekdays": [1, 2, 3, 4, 5],
  "hours": [9],
  "minutes": [0]
}

Reverse month days allow “last day of month” style expressions: −1 = last day, −2 = second-to-last, etc.

Interval

Run the event on a fixed interval starting from a specific epoch. Timezone-agnostic and can launch multiple jobs within the current minute at second offsets.

Parameters

Name	Type	Description
`start`	Number	Start time as Unix timestamp (seconds)
`duration`	Number	Interval length in seconds (must be > 0)
`params`	Object	Parameter overrides
`tags`	Array	Tag IDs to add to job

Example

Every 90 seconds starting at a specific time:

{
  "type": "interval",
  "enabled": true,
  "start": 1754580000,
  "duration": 90
}

Interval is mutually exclusive with precision and delay triggers.

Single Shot

Launch exactly once at the specified absolute timestamp.

{
  "type": "single",
  "enabled": true,
  "epoch": 1754631600
}

Magic Link

Generates a unique URL to start a job from a web request (incoming webhook). Authentication is built into the URL via a unique cryptographic token.

Parameters

Name	Type	Description
`key`	String	Plain text key (client supplies, server hashes)
`token`	String	Hashed token stored on server (generated from key)
`body`	String	Custom Markdown for landing page

{
  "type": "magic",
  "enabled": true,
  "token": "592b38cb583c1d028dde1dc7ec69a4865c321dd2e4ce09f4700f286ec7f18021",
  "body": "Hello! This is custom **markdown** content!"
}

Two different links are provided:

Direct link: Simple URL request (response is JSON)
Landing page: Standalone HTML page for providing parameters and uploading files

Query string and POST parameters are passed directly into Job.params for the running job.

Keyboard

Bind the event to keyboard shortcuts so users can run jobs by hitting a key combo while logged into the UI.

Parameters

Name	Type	Description
`keys`	Array	Keyboard shortcuts (e.g., `["ControlLeft+KeyA"]`)
`watch`	Boolean	Redirect to Job Details page on start
`params`	Object	Parameter overrides
`tags`	Array	Tag IDs to add

{
  "type": "keyboard",
  "enabled": true,
  "keys": ["ControlLeft+AltLeft+KeyD"],
  "watch": true
}

Startup

Automatically run a job when xyOps starts up (process uptime < 5 minutes, avoiding failover runs).

{
  "type": "startup",
  "enabled": true,
  "params": {},
  "tags": []
}

It’s highly recommended to add a Max Queue Limit when using startup triggers to ensure jobs queue if no target servers are available.

Catch-Up

Ensure events always run on schedule, even after downtime. When enabled, xyOps executes all scheduled jobs including missed ones.

{
  "type": "catchup",
  "enabled": true
}

How It Works

Catch-up mode maintains a “cursor” in the database for every event:

Cursor Advances

When a job runs on schedule, the cursor advances to the next minute, stopping at current time

Time Gap Handling

In the event of a time gap, cursor advances minute-by-minute up to current time

No Missed Jobs

Ensures all scheduled jobs are executed during “downtime” periods

Use Cases for Catch-Up

Shutting down the xyOps service
Pausing the scheduler
Disabling the scheduler or triggers
Disabling the entire event

Catch-up mode will NOT re-run jobs that failed or were aborted. Use Max Retry Limit for automatic retries of failed jobs.

Range

Restrict scheduling to a date/time window. Prevents launches before start and after end. Endpoints are inclusive.

Parameters

Name	Type	Description
`start`	Number	Earliest allowed time (Unix seconds)
`end`	Number	Latest allowed time (Unix seconds)

{
  "type": "range",
  "enabled": true,
  "start": 1740787200,
  "end": 1748649600
}

Ranges may be open or closed. You can specify only start, only end, or both. If both are set, start must be ≤ end.

Blackout

Prevent any automatic launches during a specific date/time window. Useful for maintenance windows or holidays.

{
  "type": "blackout",
  "enabled": true,
  "start": 1754694000,
  "end": 1754780400
}

Blackout triggers only affect automatic launches from scheduler triggers. Manual runs are not blocked.

Delay

Add a starting delay to all scheduler-launched jobs. Mutually exclusive with interval and precision.

{
  "type": "delay",
  "enabled": true,
  "duration": 120
}

This delays all launches by 2 minutes (120 seconds).

Precision

Launch within the scheduled minute at specific second offsets. Achieves sub-minute starts. Mutually exclusive with interval and delay.

{
  "type": "precision",
  "enabled": true,
  "seconds": [5, 20, 35, 50]
}

This launches at :05, :20, :35, and :50 within each matched minute.

Multiple jobs may be launched in a single minute at the listed seconds.

Quiet

Configure jobs to run silently (invisible to UI) and/or ephemeral (self-delete upon completion).

Parameters

Name	Type	Description
`invisible`	Boolean	Hide from UI (upcoming, queued, and running)
`ephemeral`	Boolean	Auto-delete jobs upon completion

{
  "type": "quiet",
  "enabled": true,
  "invisible": true,
  "ephemeral": false
}

Quiet Mode Behaviors

Invisible mode: Affects running, queued, and upcoming jobs in UI (still accessible via API)
Ephemeral mode: Automatically disables if job produces output files
Both modes pass down to child sub-jobs in workflows

Plugin

Use a custom Trigger Plugin to decide whether to launch a job or not. The plugin runs with configured parameters and returns a launch/no-launch decision.

Parameters

Name	Type	Description
`plugin_id`	String	ID of configured Plugin of type `scheduler`
`params`	Object	Plugin-defined configuration
`timezone`	String	Timezone context for plugin

{
  "type": "plugin",
  "enabled": true,
  "plugin_id": "queue_gate",
  "params": { 
    "queue": "nightly", 
    "threshold": 100 
  },
  "timezone": "UTC"
}

At a high level, xyOps invokes the plugin once per scheduled run with context, and launches jobs if the plugin indicates so. Plugins can also request per-launch delay and provide input data/files.

Composition Rules

Some combinations are restricted to keep scheduling unambiguous:

Uniqueness (Enabled)

Only one of each per event:

manual
catchup
range
precision
delay

Mutual Exclusions (Enabled)

interval and precision are mutually exclusive
interval and delay are mutually exclusive
precision and delay are mutually exclusive

Launching Triggers

Only these produce launches:

manual
schedule
interval
single

Modifiers

Range triggers only allow launches between start and end date/time
Blackout triggers disallow launches between start and end date/time
You may add multiple ranges and blackouts

Scheduler Implementation

The scheduler evaluates triggers every minute:

// Source: lib/schedule.js:117-349
schedulerMinuteTick(dargs) {
  var now = Tools.normalizeTime( dargs.epoch, { sec: 0 } );
  var default_tz = this.config.get('tz') || 
    Intl.DateTimeFormat().resolvedOptions().timeZone;
  
  this.events.forEach( function(event) {
    if (!event.enabled) return;
    if (!event.triggers || !event.triggers.length) return;
    
    var triggers = event.triggers.filter( function(trigger) { 
      return trigger.enabled && trigger.type; 
    });
    var schedules = triggers.filter( function(trigger) { 
      return trigger.type.match(/^(schedule|single|interval)$/); 
    });
    if (!schedules.length) return;
    
    var ranges = triggers.filter( function(trigger) { 
      return (trigger.type == 'range'); 
    });
    var blackouts = triggers.filter( function(trigger) { 
      return (trigger.type == 'blackout'); 
    });
    var catch_up = Tools.findObject( triggers, { type: 'catchup' } );
    var cursor = catch_up ? 
      (self.getState('events/' + event.id + '/cursor') || (now - 60)) : 
      (now - 60);
    
    while (cursor < now) {
      cursor += 60;
      // Evaluate schedule/interval/single triggers
      // Check ranges and blackouts
      // Launch job if conditions met
    }
    
    if (catch_up) self.putState( 'events/' + event.id + '/cursor', cursor );
  });
}

Workflows and Triggers

Workflows use the same event trigger system. When a scheduled workflow launches, the scheduler records which trigger initiated the start so the workflow can reference it internally.

Validation

When you save or run an event, xyOps validates triggers:

Types and required parameters must be present and well-formed
Ranges: start ≤ end where applicable
Blackout requires both start and end
Schedule lists must contain numbers in valid ranges
Enabled uniqueness and mutual exclusion rules are enforced

Events

Learn about event configuration

Actions

Configure job completion actions

Limits

Set resource constraints

Workflows

Build visual job orchestration

Get Started

Core Concepts

Monitoring & Alerts

Organization

Operations

Plugins & Extensions

Advanced

Documentation Index

​Overview

​Trigger Types

​Manual Run

​Schedule

​Parameters

​Examples

​Interval

​Parameters

​Example

​Single Shot

​Magic Link

​Parameters

​Keyboard

​Parameters

​Startup

​Catch-Up

​How It Works

​Range

​Parameters

​Blackout

​Delay

​Precision

​Quiet

​Parameters

​Plugin

​Parameters

​Composition Rules

​Uniqueness (Enabled)

​Mutual Exclusions (Enabled)

​Launching Triggers

​Modifiers

​Scheduler Implementation

​Workflows and Triggers

​Validation

​Related Documentation

Events

Actions

Limits

Workflows

Build docs developers (and LLMs) love

Overview

Trigger Types

Manual Run

Schedule

Parameters

Examples

Interval

Parameters

Example

Single Shot

Magic Link

Parameters

Keyboard

Parameters

Startup

Catch-Up

How It Works

Range

Parameters

Blackout

Delay

Precision

Quiet

Parameters

Plugin

Parameters

Composition Rules

Uniqueness (Enabled)

Mutual Exclusions (Enabled)

Launching Triggers

Modifiers

Scheduler Implementation

Workflows and Triggers

Validation

Related Documentation