Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pixlcore/xyops/llms.txt

Use this file to discover all available pages before exploring further.

This guide is for users of Cronicle, the spiritual predecessor of xyOps. You can migrate all your data to xyOps, enable compatibility mode for Cronicle Plugin interop, and optionally white-label the UI to bring back the Cronicle name and logo.

​
Prerequisites

Before importing your Cronicle data, you must add all your worker servers to your xyOps installation.
Cronicle events can target servers directly by hostname, but xyOps handles this differently. It’s important to have all servers in your xyOps cluster before importing so the system can properly match your Cronicle server targets to xyOps servers. Steps:
1

Add All Worker Servers

Follow the Adding Servers guide to add all your worker servers to xyOps.
2

Verify Server Connectivity

Ensure all satellites are connected and showing as online in the Servers tab.
3

Export Cronicle Data

Prepare your Cronicle data for export (see next section).

​
Data Export from Cronicle

Follow the Cronicle Data Export guide to export all your data from Cronicle. Command: 
cd /opt/cronicle
bin/control.sh export /path/to/export.json
This creates a JSON file containing all your:
  • Events and schedules
  • Categories
  • Server groups
  • Plugins
  • Users and API keys
  • Configuration settings

​
Data Import into xyOps

The bulk import operation is destructive and will:
  • Delete all existing data in the way
  • Abort all running jobs
  • Flush all queued jobs
  • Automatically pause the scheduler
Make sure you have a backup before proceeding.

​
Import Steps

1

Login as Administrator

Login to xyOps with an administrator account.
2

Navigate to System Tab

Click on the “System” tab in the sidebar.
3

Start Import

Click the “Import Data…” button.
4

Select File Format

In the “File Format” menu, select “Cronicle Data Format”.
5

Choose File

Click “Choose File…” and select your Cronicle data export file.
6

Review Results

Once complete, a notification appears in the bottom-left corner. Click on the “Activity” tab, locate the completed import job, and click “Details…” to see the full report, including any warnings or errors.

​
Post-Import Verification

Before re-enabling the scheduler, verify all data imported correctly:
  • Check all events are present
  • Verify schedule triggers
  • Review multiplex settings (now converted to workflows)
  • Check notifications and actions
  • Verify all categories imported
  • Check category limits and actions
  • Confirm all server groups exist
  • Verify server membership
  • Check all plugins are available
  • Review plugin parameters
  • Test a sample job with each plugin
  • Verify all users imported
  • Check user privileges (see notes below)
  • Test API key authentication

​
Plugin Compatibility Mode

While both xyOps and Cronicle communicate with plugins via JSON over STDIO, the APIs differ slightly.

​
API Differences

xyOps Format: 
{ "xy": 1, "progress": 0.5 }
xyOps requires each JSON message to have a top-level xy property set to 1. This differentiates xyOps API messages from other random JSON output. Cronicle Format: 
{ "progress": 0.5 }
Cronicle accepts any JSON message with recognized properties.

​
Enabling Compatibility Mode

To use existing Cronicle plugins without code changes, enable compatibility mode: Option 1: Configuration File Add to config.json: 
{
  "satellite": {
    "config": {
      "cronicle": true
    }
  }
}
Option 2: Environment Variable 
export XYOPS_satellite__config__cronicle="true"
Changing the Satellite Configuration requires a restart for the changes to take effect across all your servers.

​
Compatibility Features

Compatibility mode:
  • Drops the xy property requirement
  • Recognizes and converts Cronicle-specific Plugin APIs:
    • chain
    • chain_error
    • chain_data
    • notify_success
    • notify_fail

​
White-Label UI

To make xyOps resemble Cronicle’s branding:

​
Configuration

Option 1: Configuration File Add to the client object in config.json: 
{
  "client": {
    "name": "Cronicle",
    "logo_url": "/images/cronicle-logo.png"
  }
}
Option 2: Environment Variables 
export XYOPS_client__name="Cronicle"
export XYOPS_client__logo_url="/images/cronicle-logo.png"
Make sure the logo URL is an absolute path or a fully-qualified URL.

​
Multiplex Events

xyOps handles multiplex events (jobs that run on multiple servers in parallel) differently than Cronicle.

​
How Multiplex is Converted

Multiplex events are now implemented as Workflows using a Multiplex Controller Node. When you import Cronicle data with multiplexed events, they are automatically converted to workflows with the event added inside as a Job Node.

​
Enhanced Capabilities

Your multiplex events should “just work” like they did in Cronicle, but you now have more options:
Attach Limiter Nodes to control execution:
  • Max Jobs Limiter: Control how many jobs run in parallel
  • Max Queue Limiter: Manage queue depth
By default, there is no parallel limit.
Once converted to workflows, you can:
  • Add conditional branching
  • Chain multiple processing steps
  • Implement error handling workflows
  • Use split/merge patterns for complex pipelines

​
Detached Jobs

xyOps does not have the concept of detached jobs like Cronicle does.

​
Why Detached Jobs Aren’t Needed

Satellite Architecture:
  • xyOps installs a small satellite binary on worker servers
  • Satellites run 24x7 and never need restarting
  • Jobs continue running even during satellite upgrades
Upgrade Process:
  • Satellite upgrades roll out gradually
  • Each server waits for all jobs to complete before self-upgrading
  • No interruption to running jobs
Conductor Shutdown:
  • Stopping the primary xyOps service does not abort running jobs
  • Jobs continue headless if conductor is down
  • Jobs report completion when a conductor comes back up

​
User Privileges

User and API Key privileges are automatically migrated with a couple of exceptions:

​
Privilege Changes

Cronicle: User-level privilegexyOps: Administrators onlyThe feature exists, but it is limited to administrators for security reasons.
Cronicle: Undocumented job_read_only privilegexyOps: Parameter-level lockingIndividual Plugin and Event parameters can be marked as “administrator locked” (only admins can write to them). The Shell Plugin script parameter is preconfigured this way.

​
Migration Checklist

1

Pre-Migration

  • Add all worker servers to xyOps
  • Verify server connectivity
  • Export Cronicle data
  • Backup xyOps data (if any exists)
2

Import

  • Import Cronicle data
  • Review import report for errors
  • Verify all entities imported
3

Configuration

  • Enable plugin compatibility mode if needed
  • Configure white-label UI if desired
  • Review and test converted workflows
4

Testing

  • Test sample jobs from each event
  • Verify plugin execution
  • Test notifications and actions
  • Confirm user authentication and privileges
5

Go Live

  • Re-enable scheduler
  • Monitor initial job runs
  • Update documentation and runbooks
  • Train team on xyOps differences

​
Rollback Plan

If you need to rollback to Cronicle:
  1. Keep Cronicle Running: Don’t decommission Cronicle until xyOps is fully validated
  2. Maintain Parallel Systems: Run both systems in parallel during a transition period
  3. Document Changes: Keep a log of any configuration changes made during migration
  4. Backup Strategy: Maintain regular backups of both systems during transition

​
Getting Help

If you encounter issues during migration:

Build docs developers (and LLMs) love

Get started for freeTalk to us