Categories

Organize events and workflows with custom categories, default actions, and resource limits

Overview

Categories group related events and workflows in xyOps. Each event or workflow belongs to exactly one category, which aids navigation, controls visibility, provides visual separation, and defines default actions and limits for everything inside.

Categories are completely user-defined. Create as many as you need to organize your automation.

Key Features

Custom Organization

Create unlimited categories to group events and workflows by environment, team, or purpose

Default Actions

Define actions that automatically apply to all jobs in the category

Resource Limits

Set default limits for time, retries, and concurrency

Visual Identity

Customize with colors and icons for quick identification

Creating a Category

1. Navigate to Categories

   Go to Admin → Categories in the UI

2. Define Basic Properties

   Set the category ID, title, color, and icon

   {
     "id": "prod",
     "title": "Production",
     "enabled": true,
     "color": "red",
     "icon": "shield-alert-outline"
   }
   
3. Add Default Actions

   Configure actions that run automatically for all jobs in this category

   "actions": [
     {
       "enabled": true,
       "condition": "error",
       "type": "email",
       "users": ["oncall"]
     },
     {
       "enabled": true,
       "condition": "critical",
       "type": "web_hook",
       "web_hook": "slack_ops"
     }
   ]
   
4. Set Resource Limits

   Define default limits for jobs in this category

   "limits": [
     {
       "enabled": true,
       "type": "retry",
       "amount": 2,
       "duration": 60
     },
     {
       "enabled": true,
       "type": "time",
       "duration": 3600,
       "abort": true
     }
   ]
   

Default Actions and Limits

Categories provide a powerful way to set defaults that apply across multiple events and workflows.

How Actions Merge

Actions from multiple sources are combined and deduplicated:

1. Event-level actions (highest priority)
2. Category actions (from the event’s category)
3. Universal actions (from global configuration)

Actions with identical type and target are deduplicated, so each action runs only once.

Limit Precedence

Limits follow a clear precedence hierarchy:

• Start-time limits: Event/Workflow → Category → Universal
• Runtime limits: Can stack and trigger independently (time, log, memory, CPU)

Use category limits to enforce organization-wide policies, like maximum job runtime or retry attempts.

Visual Customization

Available Colors

Categories support background tint colors that appear in event and job lists:

• plain - Default gray
• red - Production/Critical
• green - Success/Approved
• blue - Standard
• skyblue - Staging/Dev
• yellow - Warning/Attention
• purple - Special
• orange - Alert

Icons

Choose from Material Design Icons (e.g., folder-outline, shield-alert-outline, database-outline). Icons are visual only and appear next to category titles.

Enable/Disable Behavior

Disabling a category prevents all contained events and workflows from running, even if individually enabled.

When a category is disabled:

• The scheduler will not trigger contained events
• Manual job launches are blocked
• Existing running jobs continue to completion

Example Configuration

Here’s a complete example with two categories for different environments:

Production Category

{
  "id": "prod",
  "title": "Production",
  "enabled": true,
  "color": "red",
  "icon": "shield-alert-outline",
  "actions": [
    {
      "enabled": true,
      "condition": "error",
      "type": "email",
      "users": ["oncall"]
    },
    {
      "enabled": true,
      "condition": "critical",
      "type": "web_hook",
      "web_hook": "slack_ops"
    }
  ],
  "limits": [
    {
      "enabled": true,
      "type": "retry",
      "amount": 2,
      "duration": 60
    },
    {
      "enabled": true,
      "type": "time",
      "duration": 3600,
      "abort": true
    }
  ]
}

Staging Category

{
  "id": "staging",
  "title": "Staging",
  "enabled": true,
  "color": "skyblue",
  "actions": [
    {
      "enabled": true,
      "condition": "error",
      "type": "email",
      "users": ["dev"]
    }
  ],
  "limits": [
    {
      "enabled": true,
      "type": "job",
      "amount": 3
    }
  ]
}

Event Using Category Defaults

An event in the production category inherits actions and limits:

{
  "id": "deploy_app",
  "title": "Deploy Application",
  "enabled": true,
  "category": "prod",
  "plugin": "shellplug",
  "limits": [
    {
      "enabled": true,
      "type": "job",
      "amount": 1
    }
  ],
  "actions": []
}

At launch, this event gets:

• Its own concurrency limit (1 job)
• Production category’s retry and time limits
• Production category’s error and critical actions
• Any universal defaults

API Reference

Manage categories programmatically using these endpoints:

List All Categories

GET /api/app/get_categories/v1

Returns all categories with their configurations.

Get Single Category

GET /api/app/get_category/v1?id=prod

Create Category

POST /api/app/create_category/v1

Auto-generates ID if not provided. Validates embedded limits and actions.

Update Category

POST /api/app/update_category/v1

Shallow-merge updates. Increments revision counter.

Delete Category

POST /api/app/delete_category/v1

Deletion is blocked if any events reference the category.

Reorder Categories

POST /api/app/multi_update_category/v1

Update sort order for multiple categories in one call.

Permissions

These privileges control category management:

• create_categories - Create new categories
• edit_categories - Modify existing categories
• delete_categories - Remove categories

Users need appropriate privileges to manage categories. Assign via roles in the Admin panel.

Best Practices

Organize by Environment

Create categories for Production, Staging, Development, and QA to separate workflows by deployment stage.

Use Category Colors Consistently

Assign colors that match your mental model (e.g., red for production, blue for development) to quickly identify job environments.

Set Conservative Limits

Use category limits to prevent runaway jobs. Better to start restrictive and relax later.

Centralize Notifications

Put common notification actions at the category level rather than repeating them on every event.