Actions - xyOps

Overview

Actions in xyOps handle responses to job outcomes and alert state changes. You attach actions to events (jobs) and alerts so when specific conditions occur, xyOps executes one or more actions in parallel. Typical actions include sending email, firing a web hook, running a job, creating a ticket, taking a snapshot, and more.

Actions are small definition objects with three core fields: enabled, condition, and type. Extra fields depend on the type.

Where Actions Are Defined

Event editor: Add job actions to run on job start or completion outcomes
Workflow builder: Attach job actions to workflow nodes
Alert setup: Add alert actions to run when alerts fire and/or clear
Categories: Event categories can set default job actions
Groups: Server groups can set default alert actions
Universal: Server config can add universal job and alert actions

Action Conditions

Each action has a condition selecting when it runs.

Job Conditions

Condition	Fires When
`start`	Job first starts (before remote launch)
`complete`	Job completes (regardless of outcome)
`success`	Job completes successfully (code 0 or false)
`error`	Job completes with any error (non-zero code)
`user`	Job completes with custom error code
`warning`	Job completes with code “warning”
`critical`	Job completes with code “critical”
`abort`	Job is aborted (by user or failure condition)
`tag:TAGID`	On job completion, only if tag is present

Workflow Conditions

Condition	Fires When
`continue`	After Controller completes all connected jobs

Alert Conditions

Condition	Fires When
`alert_new`	Alert fires on a server
`alert_cleared`	Active alert clears

Job completion actions only fire if the job was not retried. This includes tag conditions.

Action Execution

Parallel Execution: All matched actions for a given trigger run in parallel
Deduplication: Actions are deduped by composite of type + target (e.g., same email recipients, same webhook ID)
Recording: Activity and details appear in job’s Activity log and metadata

// Source: lib/action.js:23-101
runJobActions(job, conditions, callback) {
  var final_actions = [];
  
  conditions.forEach( function(condition) {
    var actions = Tools.findObjects( job.actions || [], 
      { condition, enabled: true } );
    if (actions.length) {
      final_actions = final_actions.concat(actions);
    }
  });
  
  // Dedupe actions by type + target
  final_actions = final_actions.filter( function(action) {
    var key = action.type + '-';
    switch (action.type) {
      case 'email': 
        key += action.email; 
        if (action.users) key += action.users.join(',');
        break;
      case 'web_hook': key += action.web_hook; break;
      case 'run_event': key += action.event_id; break;
      // ...
    }
    if (key in temp_state) return false;
    temp_state[key] = 1;
    return true;
  });
  
  async.each( final_actions, 
    function(action, callback) {
      self.runJobAction(job, action, callback);
    }, 
    callback
  );
}

Action Types

Email

Send an email notification to one or more users and/or explicit email addresses. Parameters:

Name	Type	Description
`users`	Array(String)	Array of usernames to email
`email`	String	Comma-separated additional recipients
`body`	String	Optional custom email using Markdown

Example (Job Error):

{
  "enabled": true,
  "condition": "error",
  "type": "email",
  "users": ["oncall"],
  "email": "ops@example.com, dev@example.com"
}

Example (Alert Fired):

{
  "enabled": true,
  "condition": "alert_new",
  "type": "email",
  "users": ["oncall", "sre"],
  "email": "noc@example.com"
}

Custom Email Body

If the body property is provided, it’s used instead of a standard template. Use GitHub-Flavored Markdown and xyOps Expression Format:

<!-- To: {{email_to}} -->
<!-- Subject: ✅ {{config.client.name}} Job Completed: {{event.title}} -->
<!-- Title: Job Successful -->
<!-- Button: View Details | {{links.job_details}} -->

The following job has completed successfully:

- **Job ID:** `{{job.id}}`
- **Event:** {{event.title}}
- **Server:** {{nice_server}}
- **Elapsed Time:** {{display.elapsed}}

### Job Output:
{{log_excerpt}}

Supported comment properties:

To: Email “To” header (use {{email_to}} for combined list)
From: Email “From” header
Subject: Email subject line
Title: Large bold text in HTML header
Button: Large button with label and link (separated by |)
Logo_URL: Custom logo image URL

Web Hook

Fire a configured outbound web hook with rich context payload. Parameters:

Name	Type	Description
`web_hook`	String	WebHook ID
`text`	String	Extra text appended to message

{
  "enabled": true,
  "condition": "critical",
  "type": "web_hook",
  "web_hook": "slack_ops",
  "text": "Paging on-call"
}

Run Event

Launch another event as a follow-up action. The new job inherits context. Parameters:

Name	Type	Description
`event_id`	String	Target Event ID to run
`params`	Object	Override parameters for launched event
`target_server`	Boolean	For alerts: override targets to alert’s server
`clear_alert`	Boolean	For alerts: clear alert when job completes

Example (Job Warning):

{
  "enabled": true,
  "condition": "warning",
  "type": "run_event",
  "event_id": "postprocess_assets",
  "params": { 
    "optimize": true, 
    "quality": 80 
  }
}

Example (Alert Fired):

{
  "enabled": true,
  "condition": "alert_new",
  "type": "run_event",
  "event_id": "scale_out",
  "target_server": true,
  "clear_alert": false
}

Channel

Notify a configured channel. Channels can bundle users (email/notify), a web hook, and/or an event to run.

{
  "enabled": true,
  "condition": "error",
  "type": "channel",
  "channel_id": "ops_oncall"
}

Snapshot

Capture a server snapshot. For jobs, the job must target a specific server. For alerts, snapshot is taken for the alert’s server.

{
  "enabled": true,
  "condition": "error",
  "type": "snapshot"
}

Ticket

Create a ticket with a generated body based on context (job or alert). Parameters:

Name	Type	Description
`ticket_type`	String	Ticket type (issue, task, etc.)
`ticket_assignees`	Array(String)	Array of usernames
`ticket_tags`	Array(String)	Array of Tag IDs

{
  "enabled": true,
  "condition": "error",
  "type": "ticket",
  "ticket_type": "issue",
  "ticket_assignees": ["oncall"],
  "ticket_tags": ["production", "sev2"]
}

Plugin

Invoke a custom Action Plugin. xyOps executes your plugin command/script with a structured JSON payload. Parameters:

Name	Type	Description
`plugin_id`	String	Plugin ID with type “action”
`params`	Object	Plugin-defined parameter values

{
  "enabled": true,
  "condition": "success",
  "type": "plugin",
  "plugin_id": "notify_grafana",
  "params": { 
    "dashboard": "builds", 
    "panel": "summary" 
  }
}

Suspend Job

Suspend the running job until a user resumes it in the UI. Optionally notify users and/or fire a web hook. Parameters:

Name	Type	Description
`users`	Array(String)	Usernames to email
`email`	String	Additional recipients
`web_hook`	String	WebHook ID to fire
`text`	String	Extra text for webhook

{
  "enabled": true,
  "condition": "start",
  "type": "suspend",
  "users": ["deployers"],
  "email": "ops@example.com",
  "web_hook": "slack_ops",
  "text": "Manual review required."
}

Disable Event

Disable the current event when the action runs. Useful after failures to prevent subsequent scheduled executions.

{
  "enabled": true,
  "condition": "error",
  "type": "disable"
}

Delete Event

Delete the current event when the action runs. Designed for ephemeral one-shot events.

{
  "enabled": true,
  "condition": "critical",
  "type": "delete"
}

Use with care - the event is permanently removed from the system.

Store Bucket

Store job data and/or files into a storage bucket. Control whether to sync data, files, or both, and filter files via glob pattern. Parameters:

Name	Type	Description
`bucket_id`	String	Bucket ID target
`bucket_sync`	String	`data`, `files`, or `data_and_files`
`bucket_glob`	String	Glob pattern (default `*`)

{
  "enabled": true,
  "condition": "success",
  "type": "store",
  "bucket_id": "bme4wi6pg35",
  "bucket_sync": "data_and_files",
  "bucket_glob": "*.json"
}

Fetch Bucket

Fetch bucket data and/or files and attach them to the job’s input context. Parameters:

Name	Type	Description
`bucket_id`	String	Bucket ID target
`bucket_sync`	String	`data`, `files`, or `data_and_files`
`bucket_glob`	String	Glob pattern (default `*`)

{
  "enabled": true,
  "condition": "start",
  "type": "fetch",
  "bucket_id": "bme4wi6pg35",
  "bucket_sync": "files",
  "bucket_glob": "*.csv"
}

Apply Tags

Apply a custom set of tags to the job or workflow.

{
  "enabled": true,
  "condition": "complete",
  "type": "tag",
  "tags": ["important"]
}

Tags are deduplicated when the job completes.

Compatibility

Some action types are job-only and cannot be used with alerts: Job-Only Actions:

store (Store Bucket)
fetch (Fetch Bucket)
disable (Disable Event)
delete (Delete Event)
suspend (Suspend Job)

All Others can be used with both jobs and alerts.

Universal Default Actions

Set universal defaults in server config:

"job_universal_actions": {
  "default": [
    {
      "enabled": true,
      "hidden": false,
      "condition": "error",
      "type": "snapshot"
    }
  ],
  "workflow": []
},
"alert_universal_actions": [
  {
    "enabled": true,
    "hidden": true,
    "condition": "alert_new",
    "type": "snapshot"
  }
]

Action Execution Details

When actions run, they track performance and results:

// Source: lib/action.js:103-168
runJobAction(job, action, callback) {
  this.appendMetaLog(job, 
    "Executing job " + action.condition + " action: " + action.type);
  
  action.date = Tools.timeNow();
  action.elapsed_ms = 0;
  var perf_start = performance.now();
  
  var func = 'runJobAction_' + action.type;
  if (!this[func]) {
    action.code = 'type';
    action.description = "Unknown action type: " + action.type;
    return callback();
  }
  
  action.active = true;
  
  this[func](job, action, function() {
    delete action.active;
    action.elapsed_ms = Math.floor( performance.now() - perf_start );
    if (action.code) {
      self.logError( action.type, action.description, { job: job.id } );
    } else {
      self.logAction( 8, action.type + ": " + action.description, 
        { job: job.id } );
    }
    callback();
  });
}

Each action stores:

date: When action executed (Unix timestamp)
elapsed_ms: How long it took in milliseconds
code: 0 for success, error code otherwise
description: Human-readable result
details: Extended markdown details

Notes and Tips

For job actions, email/webhook payloads include job links, log excerpts, performance metrics, and attached files
For alert actions, payloads include server details, links to server and alert, and alert message
Tag-based job conditions are specified as tag:TAGID and fire only at job completion
Bucket actions respect configured limits such as maximum file size and maximum files per bucket

Events

Learn about event configuration

Triggers

Configure when jobs run

Limits

Set resource constraints

Workflows

Build job orchestration graphs

Documentation Index

​Overview

​Where Actions Are Defined

​Action Conditions

​Job Conditions

​Workflow Conditions

​Alert Conditions

​Action Execution

​Action Types

​Email

​Web Hook

​Run Event

​Channel

​Snapshot

​Ticket

​Plugin

​Suspend Job

​Disable Event

​Delete Event

​Store Bucket

​Fetch Bucket

​Apply Tags

​Compatibility

​Universal Default Actions

​Action Execution Details

​Notes and Tips

​Related Documentation

Events

Triggers

Limits

Workflows

Overview

Where Actions Are Defined

Action Conditions

Job Conditions

Workflow Conditions

Alert Conditions

Action Execution

Action Types

Email

Web Hook

Run Event

Channel

Snapshot

Ticket

Plugin

Suspend Job

Disable Event

Delete Event

Store Bucket

Fetch Bucket

Apply Tags

Compatibility

Universal Default Actions

Action Execution Details

Notes and Tips

Related Documentation