Events

Learn about events, the core building blocks of xyOps that define what to run, where, when, and how to react to job execution.

Overview

Events are the core building block of xyOps. An event describes what to run (a Plugin with parameters), where to run it (one or more target servers or groups), when to run it (Triggers), and how to constrain and react to runs (Limits and Actions). Each time an event runs, it launches a job with full lifecycle state, logs, metrics, limits, and actions.

An event is essentially a saved configuration template for launching jobs. When a trigger fires, the scheduler creates a job from the event and launches it on a chosen target server.

Key Concepts

• Event Configuration: An event has an id, title, category, plugin, params, optional fields, tags, targets, algo, triggers, limits, and actions
• Job Execution: When a trigger fires (schedule, interval, manual, or plugin), the scheduler creates a job from the event
• Category Defaults: Category-defined actions and limits are automatically merged into jobs in addition to event-specific configurations
• Plugin Execution: Jobs run code provided by an Event Plugin on the selected server, streaming logs back to the UI
• Workflows: Special events that launch a graph of nodes using a workflow pseudo-plugin

Creating Events

You can create and edit events in the Events page of the UI or via the API. The minimum configuration typically includes:

1. Basic Information

   • Title: Human-friendly name displayed in the UI
   • Category: Controls access and provides default actions/limits
   • Plugin: The Event Plugin that runs the job code (not required for workflows)
2. Target Configuration

   • Targets: One or more servers and/or groups where jobs may run
   • Algorithm: Server selection algorithm when multiple targets are available (default is random)
3. Parameters & Fields

   • Params: Plugin parameters passed to your job (locked parameters may be enforced)
   • Fields: Optional user-defined parameters prompted when launching manually
   • Tags: Labels that help searching and filtering job history
4. Timing & Constraints

   • Triggers: One or more entries that determine run timing and rules
   • Limits: Self-imposed resource constraints for the job to follow
   • Actions: Optional per-event notifications and chaining behavior

Event Lifecycle

Running an event produces a job. Here is the lifecycle from trigger to execution:

Detailed Execution Steps

1. Trigger Fires

The scheduler evaluates all event triggers once per minute (with optional second precision) and emits launches when conditions match. Manual runs from the UI/API also count as launches.

2. Job Object Created

• The job starts as a copy of the event plus trigger context and any user/API overrides
• Assigned a unique job.id, and job.event is set to the event’s ID
• Category-defined actions/limits and system defaults are merged in

3. Parameters Resolved

event.params and any prompted fields are merged and can use {{ macros }} that resolve against the job context (including input.data and input.files if present).

4. Target Selection

• System collects candidate servers from targets (servers and/or groups)
• Filters to enabled, online servers
• Optionally removes servers under active job-limiting alerts
• If no servers available, queue limit (if configured) may place job in queue; otherwise job aborts and may be eligible for retry

5. Plugin Execution

• Job is dispatched to chosen server’s xySat agent
• Event Plugin runs with final parameters and environment
• Output streams into job log
• CPU/memory/IO metrics are sampled for limits and history

6. Limits and Actions

• Active limits (time, log size, CPU, memory, etc.) are continuously evaluated
• When exceeded, configured actions fire (email, web hooks, tags, snapshots, abort, etc.)

7. Completion

Final actions run (success/fail/progress/abort, plus any tag-based actions), and the job record is stored in history for searching and analytics.

Server Selection

The targets list may contain server IDs and/or group IDs. At launch time xyOps:

• Expands groups into member servers and de-duplicates the list
• Filters to currently enabled, online servers
• Optionally removes servers under active blocking alerts (e.g. maintenance or capacity limits)
• Optionally applies a Target Expression to further reduce the list
• If the resulting set is empty and a queue limit is present, the job may enter a per-event queue; otherwise it aborts

Selection Algorithms

Selection among remaining candidates is controlled by algo:

Algorithm	Description
random	Choose randomly among candidates
round_robin	Cycle through candidates in order, persisting position between runs
least_cpu	Choose the server reporting the lowest CPU load
least_mem	Choose the server reporting the lowest active memory
prefer_first	Prefer first by hostname sort for stability
prefer_last	Prefer last by hostname sort for stability
monitor:ID	Choose the server with the smallest current value of a specific monitor

Target Expressions

Events can include an optional “target expression” to further reduce the set of candidate servers. The expression is applied to each server in the matched set, and if it evaluates to false, the server is eliminated.

info.arch == "arm64" && info.cpu.cores >= 4

This reduces candidates to only ARM64 servers with 4+ CPU cores.

One common use case is applying the target expression to properties in Server User Data:

userData.foo == "bar"

Event Parameters

Parameters are passed to the plugin. Locked/required attributes can be set by admins or categories. Optional fields collected at manual run time are merged into params.

Environment: Jobs inherit configured job_env plus any event-specific env overrides. Additionally, all Plugin params are passed as environment variables.

Input: Jobs may include structured input.data and uploaded input.files when launched from the UI/API. Actions like “Bucket Fetch” can also populate inputs before your code runs.

Manual Runs and Prompts

To allow on-demand runs from the UI or API, include an enabled manual trigger on the event. When launching manually:

• Any fields defined on the event are presented as a UI form, and their values are merged into params
• The UI/API may attach uploaded files; these become input.files
• Arbitrary JSON may be provided as input.data when testing
• Non-admin users must satisfy any locked/required parameters

Example Event Configuration

Here is an example event in JSON format:

{
  "id": "event100",
  "title": "Daily Database Backup",
  "enabled": true,
  "category": "cat9",
  "plugin": "shellplug",
  "params": { 
    "script": "#!/bin/bash\nsleep 30; echo HELLO;\n" 
  },
  "targets": ["main"],
  "algo": "random",
  "triggers": [
    { 
      "type": "schedule", 
      "enabled": true, 
      "hours": [19], 
      "minutes": [6] 
    }
  ],
  "limits": [
    { 
      "type": "time", 
      "enabled": true, 
      "duration": 3600 
    }
  ],
  "actions": [
    { 
      "enabled": true, 
      "condition": "error", 
      "type": "email", 
      "email": "admin@localhost" 
    }
  ]
}

Do not commit files that likely contain secrets (.env, credentials.json, etc.) when creating events. The system will warn you if you attempt to commit sensitive files.

Permissions and Inheritance

• You must have privileges to create/edit events and to run jobs
• The system enforces category and target privileges for all operations including history access
• Category actions and limits are appended to the event at runtime
• Universal actions/limits may also apply based on system configuration

Related Documentation

Triggers

Learn about scheduling and trigger types

Actions

Configure notifications and chaining

Limits

Set resource constraints and thresholds

Workflows

Build visual job orchestration graphs