Migration from Cronicle

Complete guide for migrating from Cronicle to xyOps

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:

Events

• Check all events are present
• Verify schedule triggers
• Review multiplex settings (now converted to workflows)
• Check notifications and actions

Categories

• Verify all categories imported
• Check category limits and actions

Server Groups

• Confirm all server groups exist
• Verify server membership

Plugins

• Check all plugins are available
• Review plugin parameters
• Test a sample job with each plugin

Users & API Keys

• 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:

Parallel Job Control

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.

Advanced Workflow Features

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

Toggle Scheduler Privilege

Cronicle: User-level privilege

xyOps: Administrators only

The feature exists, but it is limited to administrators for security reasons.

Job Read-Only Privilege

Cronicle: Undocumented job_read_only privilege

xyOps: Parameter-level locking

Individual 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:

• Check the GitHub Discussions for community support
• Review the full documentation
• Open a GitHub Issue for bugs or problems