SchedulerX:Migrate ElasticJob to SchedulerX 2.0

Before you begin

Make sure you have:

• An Alibaba Cloud account with SchedulerX 2.0 activated

• A Spring Boot application that uses ElasticJob 3.0.2

• A SchedulerX namespace. For instructions, see Create a namespace

• A SchedulerX application registered in that namespace. For instructions, see Create an application

After creating the namespace and application, note down the namespace ID, groupId, and appKey from the console. You need these values in the configuration step.

For a complete working example, see the schedulerx-example-elasticjob demo project.

Step 1: Add the SchedulerX plugin dependency

Add the schedulerx2-plugin-elasticjob dependency before the ElasticJob dependency in your pom.xml file.

<dependency>
    <groupId>com.aliyun.schedulerx</groupId>
    <artifactId>schedulerx2-plugin-elasticjob</artifactId>
    <version>3.0.2.2</version>
</dependency>
<dependency>
    <groupId>org.apache.shardingsphere.elasticjob</groupId>
    <artifactId>elasticjob-lite-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>

Step 2: Configure SchedulerX as the scheduler

In your application.yml file, set elasticjob.scheduler to schedulerx and add the SchedulerX connection properties under spring.schedulerx2.

elasticjob:
  regCenter:
    serverLists: 127.0.0.1:2181
    namespace: elasticjob-test
  scheduler: schedulerx   # Route scheduling to SchedulerX 2.0 instead of ZooKeeper
  jobs:
    simpleJob:
      elasticJobClass: com.alibaba.elasticjob.test.processor.SpringBootSimpleJob
      cron: 0/10 * * * * ?
      shardingTotalCount: 1
      overwrite: true
    shardingJob:
      elasticJobClass: com.alibaba.elasticjob.test.processor.SpringBootShardingJob
      cron: 0 * * * * ?
      shardingTotalCount: 3
      shardingItemParameters: 0=Beijing,1=Shanghai,2=Guangzhou
      overwrite: true

# SchedulerX 2.0 connection settings
spring:
  schedulerx2:
    endpoint: acm.aliyun.com
    namespace: <your-namespace-id>        # Example: 433d8b23-xxxx-xxxx-xxxx-90d4d1b9a4af
    groupId: <your-group-id>              # Example: xueren_primary
    appKey: <your-app-key>
    regionId: public
    aliyunAccessKey: <your-access-key>
    aliyunSecretKey: <your-secret-key>

Replace the following placeholders with your actual values:

For a full reference of SchedulerX connection parameters, see Connect a Spring Boot application to SchedulerX.

Step 3: Add component scanning for the SchedulerX plugin

Add com.alibaba.schedulerx.plugin.* to your application's @ComponentScan so that Spring Boot loads the plugin classes at startup.

@SpringBootApplication
@ComponentScan(basePackages = {"com.alibaba.schedulerx.plugin.*", "your.application.package"})
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

Replace your.application.package with your actual application base package.

Step 4 (optional): Set up log collection

SchedulerX 2.0 can collect job execution logs from your application. The following example configures log collection with log4j2.

Create or update your log4j2.xml configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="off">
    <Appenders>
        <Console name="Console" target="SYSTEM_OUT">
            <PatternLayout
                pattern="%d{yyyy-MM-dd HH:mm:ss.SSS} [%t] %-5level %logger{36} - %m%n" />
        </Console>
        <SchedulerxLog4j2Appender name="schedulerxLog"
                timeFormat="yyyy-MM-dd'T'HH:mmZ"
                timeZone="UTC"
                ignoreExceptions="true">
            <PatternLayout pattern="%d %-5level [%thread] %logger{0}: %msg"/>
        </SchedulerxLog4j2Appender>
    </Appenders>
    <Loggers>
        <Root level="info">
            <AppenderRef ref="Console" />
        </Root>
        <Logger name="schedulerx" level="info" additivity="false">
            <AppenderRef ref="schedulerxLog" />
        </Logger>
    </Loggers>
</Configuration>

To write logs to the SchedulerX logging service from your job code, get the logger named schedulerx:

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class MyJob implements SimpleJob {
    private static final Logger schedulerxLogger = LoggerFactory.getLogger("schedulerx");

    @Override
    public void execute(ShardingContext shardingContext) {
        schedulerxLogger.info("Processing shard: {}", shardingContext.getShardingItem());
        // Your job logic here
    }
}

For other logging frameworks, see Logging services supported by SchedulerX.

Step 5: Verify the migration

Start your application. SchedulerX 2.0 automatically syncs your ElasticJob definitions to the console. During sync, SchedulerX applies the following rules:

• Second-level cron expressions are converted to the second_delay trigger type.

• Jobs with shardingTotalCount greater than 1 run in sharding mode. All other jobs run in standalone mode.

Open the SchedulerX console and confirm that your jobs appear under the correct namespace and application. Check the execution logs to verify that jobs run as expected.

Roll back to ElasticJob

If you need to switch back to the ElasticJob scheduler, pass the following JVM parameters when starting your application:

-Dspring.schedulerx2.enabled=false -Delasticjob.scheduler=elasticjob

This disables the SchedulerX plugin and restores ElasticJob's native ZooKeeper-based scheduling. No code changes are required.

Migration benefits

After migration, SchedulerX 2.0 provides the following capabilities that are not available in open-source ElasticJob:

SchedulerX 2.0 advantages:

• No ZooKeeper maintenance. SchedulerX 2.0 is a fully managed service. You do not need to provision, scale, or troubleshoot registry infrastructure.

• Built-in high availability. SchedulerX 2.0 creates multiple replicas for each job and continues scheduling even if two cluster nodes fail or a data center loses power. This architecture is battle-tested in Alibaba Group production scenarios such as Double 11 events.

• Visual operations and monitoring. Access dashboards, execution history, running stacks, and operation logs directly in the SchedulerX console.

• Flexible alerting. Receive notifications for job failures, timeouts, and no available machines through email, DingTalk groups, text messages, or phone calls.

• DAG-based job orchestration. Define job dependencies using Directed Acyclic Graphs (DAGs) through a drag-and-drop interface in the console.

• Concurrency throttling with priority queues. Control the maximum number of concurrent jobs per application. Jobs that exceed the threshold wait in a queue, and higher-priority jobs can preempt lower-priority ones.

• Resource isolation. Isolate resources by namespace or application, with built-in multi-tenant permission management.

What's next

• Connect a Spring Boot application to SchedulerX -- Full reference for SchedulerX connection parameters

• Create a namespace -- Set up resource isolation boundaries

• Create an application -- Register your application in SchedulerX