Tickets

Overview

Tickets in xyOps provide a lightweight, integrated way to track issues, releases, changes, incidents, and any operational work that benefits from an audit trail, comments, files, and automation. Tickets live alongside jobs, alerts, servers, and workflows, and can both react to the system (auto-created from jobs or alerts) and drive the system (run events/jobs directly from a ticket).

Key Properties

Tickets are simple JSON records with core and optional fields:

Core Fields

subject: Short summary/title (HTML is stripped)
body: Markdown content for runbooks, context, and checklists
type: One of issue, feature, release, change, maintenance, question, other
status: One of draft, open, closed

Assignment & Notifications

assignees: Array of usernames responsible for the ticket (receive update emails and overdue notices)
cc: Array of usernames to receive update emails (no overdue notices)
notify: Array of custom email addresses for updates (no overdue notices)

Organization

category: Optional Category ID (auto-set from jobs)
tags: Array of Tag IDs (auto-set from source job’s tags)
server: Optional Server ID (auto-set when created from jobs/alerts)

Additional Features

due: Optional due date (Unix seconds) - triggers daily overdue notices to assignees
files: Uploaded files attached to the ticket (passed as inputs to jobs)
events: Event stubs that can run jobs from the ticket
changes: Change and comment history

Creating Tickets

Manual Creation

Click “New Ticket” in the sidebar and fill in the details:

Subject, body (Markdown), type, status, category, server
Assignees, cc, notify, tags, and due date
Attach files (appear under Ticket Files and flow to jobs)
Save as Draft to suppress notifications until ready

API Creation

Use the create_ticket API endpoint to create tickets programmatically:

# JSON POST
curl -X POST https://your.xyops.example.com/api/app/create_ticket/v1 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "subject": "Database backup failed",
    "body": "## Issue\n\nBackup job failed at 2:00 AM",
    "type": "issue",
    "status": "open",
    "assignees": ["admin"],
    "tags": ["critical"]
  }'

For file uploads, use multipart/form-data with a json field containing the ticket JSON string, plus file fields.

Job Actions

Jobs can create tickets automatically on start or completion. Add a “Create Ticket” action to an event, workflow node, or category:

Ticket body is auto-generated with job details, performance, log excerpt, and links
Category, tags, and server fields are auto-populated from the job
New ticket is added to the originating job for traceability

Alert Actions

Alerts can create tickets when fired. Add a “Create Ticket” alert action:

Ticket body includes server and alert context with links
Server is populated from the firing server
Tags can be set from the action configuration

Ticket Status Workflow

Draft tickets suppress all email notifications and do not record changes. Use draft status when preparing tickets without notifying anyone.

Ticket Events & Automation

Ticket events attach runnable jobs to a ticket with optional parameter overrides.

Add Events

Click “Add Event” and select an event. Configure parameter overrides, targets, selection algorithm, and tags as needed.

Run Jobs from Tickets

When launched from a ticket:

The ticket is associated with the job
Ticket files are passed as job input files
Files from previous ticket-launched jobs can chain into subsequent runs

This makes tickets a powerful control plane for CI/CD: create a release ticket, attach deploy/test/rollback events, upload artifacts, then run jobs with the entire history centralized.

Ticket Files

Attach files via UI or API when creating/updating tickets
Files are stored server-side and listed on the ticket page
Automatically provided to jobs launched from ticket events
File expiration governed by file_expiration configuration
Upload settings configured via client.ticket_upload_settings:

"ticket_upload_settings": {
  "max_files_per_ticket": 100,
  "max_file_size": 1073741824,
  "accepted_file_types": ""
}

Comments & Change History

Any user with edit_tickets privilege can add comments supporting Markdown formatting.

Change Tracking

Edits to key fields are recorded as structured change entries:

subject, status, type, category, server
assignees, due, cc, notify, tags

Draft tickets do not record changes or send notifications.

Email Updates

Assignees, cc users, and notify emails receive batched updates (debounced):

Summary of changes and new comments
Full body text if changed
Configuration via tickets.email_debounce_sec

"tickets": {
  "email_enabled": true,
  "email_debounce_sec": 30,
  "due_date_format": "[dddd], [mmmm] [mday], [yyyy]",
  "date_time_format": "[dddd], [mmmm] [mday], [yyyy] [hour12]:[mi] [ampm]"
}

Overdue Notices

After due date passes, daily overdue emails are sent to assignees only:

Scheduled via tickets.overdue_schedule (default: "04:30")
Query filter: tickets.overdue_query (default: "status:open due:<today")

Searching Tickets

Perform searches using the ticket search interface or API:

Basic Search

# Match all words (anywhere in ticket)
zip targeting

# Exact phrase match
"zip targeting"

# Negative matches
"zip targeting" -birds -cats

# OR matches
campaign | memory | performance

Field-Specific Search

Use GitHub-style syntax with field IDs:

subject:yum status:open created:>=2020-01-01

Available Search Fields

Field ID	Description
`subject`	Search ticket subject line
`body`	Search ticket body text (default)
`changes`	Search ticket changes/comments
`status`	Filter by status (open, closed, draft)
`username`	Filter by ticket author
`assignees`	Filter by assignees
`cc`	Filter by cc list
`type`	Filter by type (issue, feature, etc.)
`category`	Filter by category
`tags`	Filter by tags
`created`	Filter by creation date (supports ranges)
`due`	Filter by due date (e.g., `due:<today`)
`num`	Filter by ticket number (supports ranges)

Search Examples

Name	Query
All tickets	`*`
All issues	`type:issue`
All overdue tickets	`status:open due:<today`
Created in date range	`created:2021/02/01..2021/03/01`
Open for N days	`status:open created:<2021/02/01`
Open and important	`status:open tags:important`
Ticket number range	`num:>=5000 num:<6000`

Search API

curl -X GET "https://your.xyops.example.com/api/app/search_tickets/v1?query=status:open&offset=0&limit=50&compact=1" \
  -H "X-API-Key: YOUR_API_KEY"

Use compact=1 to scrub verbose parameters (body, changes) for grid displays.

Configuration

Ticket settings in config.json:

"tickets": {
  "email_enabled": true,
  "email_debounce_sec": 30,
  "overdue_schedule": "04:30",
  "overdue_query": "status:open due:<today",
  "due_date_format": "[dddd], [mmmm] [mday], [yyyy]",
  "date_time_format": "[dddd], [mmmm] [mday], [yyyy] [hour12]:[mi] [ampm]"
}

Default user privileges:

"default_user_privileges": {
  "create_tickets": true,
  "edit_tickets": true
}

Common Patterns

Release Management

Create a Release ticket and attach deploy, test, and rollback events:

Upload build artifacts to the ticket
Run deploy from the ticket
Artifacts automatically flow into the job
Track entire release history in one place

Incident Response

Auto-create an Issue on alert fire with server context:

Assign on-call engineer
Set due date for follow-up
Track remediation steps with comments
Close when resolved

Change Control

Use Change tickets for planned work:

Attach validation jobs (pre-checks, post-checks)
Require second assignee to review
Document changes in ticket body
Link to related jobs and alerts

Runbooks

Use ticket body (Markdown) for runbooks and checklists:

Link to jobs via ticket events for repeatable actions
Attach common scripts as files
Track execution history in comments

API Reference

Key ticket API endpoints:

get_ticket - Load single ticket by ID or number
get_tickets - Load multiple tickets (supports verbose mode)
search_tickets - Search with pagination and sorting
create_ticket - Create new ticket (JSON or multipart)
update_ticket - Shallow-merge updates (server detects changes)
add_ticket_change - Add/edit/delete comments or change entries
update_ticket_change - Update existing change entry
upload_user_ticket_files - Upload and attach files
delete_ticket_file - Remove attached file
delete_ticket - Permanently delete ticket

Required Privileges

create_tickets: Create new tickets
edit_tickets: Edit tickets, add comments, attach/remove files, run ticket events
delete_tickets: Permanently delete tickets

Standard authentication applies for UI and API usage (sessions or API Keys).

Get Started

Core Concepts

Monitoring & Alerts

Organization

Operations

Plugins & Extensions

Advanced

Overview

Key Properties

Creating Tickets

Ticket Status Workflow

Ticket Events & Automation

Ticket Files

Comments & Change History

Searching Tickets

Basic Search

Field-Specific Search

Search API

Configuration

Common Patterns

API Reference

Required Privileges

Build docs developers (and LLMs) love

Get Started

Core Concepts

Monitoring & Alerts

Organization

Operations

Plugins & Extensions

Advanced

Documentation Index

​Overview

​Key Properties

​Creating Tickets

​Ticket Status Workflow

​Ticket Events & Automation

​Ticket Files

​Comments & Change History

​Searching Tickets

​Basic Search

​Field-Specific Search

​Search API

​Configuration

​Common Patterns

​API Reference

​Required Privileges

Build docs developers (and LLMs) love

Overview

Key Properties

Creating Tickets

Ticket Status Workflow

Ticket Events & Automation

Ticket Files

Comments & Change History

Searching Tickets

Basic Search

Field-Specific Search

Search API

Configuration

Common Patterns

API Reference

Required Privileges