xyOps Documentation

Notification Channels in xyOps allow you to bundle multiple notification targets and follow-up actions under a single reusable name. Instead of configuring individual emails, webhooks, or remediation events separately for every workflow, you can reference a single channel. When a channel is triggered, xyOps executes all its configured actions in parallel.

Common capabilities include:

• Email: Notifies channel users and external email addresses.
• Web Hook: Fires an outbound webhook with a templated payload.
• Run Event: Launches a specific event (e.g., for remediation).
• In-App Notify: Sends a UI notification to users, optionally playing an .mp3 sound.

xyOps uses Unbase built on top of pixl-server-storage. Records are stored as JSON in a key/value backend (SQLite by default).

Querying Capabilities:

• Simple field:words syntax.
• Structured PxQL syntax.

Indexing Types:

• word: Default full-text/word index.
• number: Numeric index.
• date: Date index.

Note: Date and number fields may be stored with reduced precision (e.g., divided by 3600 to index hour-level buckets) to optimize performance.

xyOps supports Single Sign-On (SSO) by outsourcing user authentication to third-party identity providers (e.g., Microsoft, Google, GitHub, Okta, Auth0, Cognito).

xyOps utilizes a "trusted headers" implementation. In this flow:

1. An authentication tool (like an OIDC plugin or proxy) authenticates the user.
2. The tool forwards the request to xyOps including specific "trusted headers".
3. xyOps detects these headers to create or update user accounts and manages the session internally.

xyOps can automatically assign user roles and privileges based on groups defined in your identity provider.

xyOps uses a custom expression syntax based on the JEXL (JavaScript Expression Language). It supports JavaScript-style dot paths, array indexing, arithmetic, and boolean operators.

Key features include:

• Object Traversal: Access deep object trees using dot notation.
• Array Filtering: Select items from arrays based on sub-object keys.
• Macro Expansion: Use {{ mustache }} syntax for inline macro expansion in string evaluations.

This format powers several subsystems, including Monitor Expressions, Alert Triggers, Alert Messages, Plugin Parameters, Workflow Controllers, Web Hook Messages, and Email Templates.

xyOps automation is built on two primary concepts:

• Events: Defines a single unit of work. An event specifies:
  • What to run (a plugin and its parameters).
  • Where to run it (specific servers or groups).
  • When to run (triggers).
  • How to control/react (limits and actions).
• Workflows: A visual graph used for orchestration. A workflow run acts as a parent job that launches sub-jobs on its nodes. Use workflows for branching, parallelism (fan-out/join), repeating tasks, or multiplexing across servers.

XYPDF (xyOps Portable Data Format) is a JSON-based method for exporting, storing, transferring, and importing data objects within xyOps. It allows users to serialize data structures into a portable file that can be moved between different xyOps installations.

File Formats

• Plain Text: Uses the .json extension.
• Compressed: Uses the .json.gz extension (Gzip-compressed).

Import/Export Workflow

1. Export: Select objects in the xyOps UI to serialize them into a XYPDF wrapper and download the file.
2. Import: Upload a XYPDF file via the xyOps UI. The system can either create new objects or replace existing objects that share the same IDs.

A user profile in xyOps combines identity, authentication, permissions, and UI preferences.

Key components include:

• Identity: username (unique), full_name (display name), and email.
• Status: The active boolean determines if a user can log in. Suspended users (active: false) are blocked.
• Authentication: Uses bcrypt hashes for passwords.
• Permissions: Managed via a roles array and a privileges object.
• Resource Limits: Access to specific event categories and server groups can be restricted.
• Preferences: Includes UI settings like language, timezone, color_acc, privacy_mode, and contrast.
• Avatar: Users can upload or replace profile images via the UI.

Triggers in xyOps define the conditions under which an event or workflow is allowed to run jobs. You can compose multiple triggers on a single event to manage automatic schedules, one-time launches, manual control, and blackout windows.

Key behaviors include:

• Launching Triggers: manual, schedule, interval, and single actually initiate job runs.
• Modifier/Constraint Triggers: catchup, nth, range, blackout, delay, precision, and plugin augment or restrict scheduling.
• Precision: The scheduler typically runs once per minute, but can support second-level precision.
• Timezones: Supported for schedule and plugin triggers via a timezone field. Note that range, blackout, and interval times are absolute and timezone-agnostic.