Migrate self-managed XXL-JOB to Alibaba Cloud XXL-JOB

Solution overview

You can use a tool provided by Alibaba Cloud to export job configurations from your open source XXL-JOB system and then import them into your Alibaba Cloud XXL-JOB instance. The process involves the following steps:

(Optional) Create alert contacts in CloudMonitor to receive alerts about system health and performance.
Create matching applications: Manually create an application with a name identical to the AppName in your open source system.
Export job information: Export the job information and configurations from your self-managed XXL-JOB system.
Import jobs: Import the job information and configurations into Alibaba Cloud XXL-JOB.
Redeploy the application: After the jobs are imported, redeploy your XXL-JOB application to connect it to the Alibaba Cloud XXL-JOB platform.

Step 1: (Optional) Create CloudMonitor alert contacts

Note

If you have already configured alert contacts in CloudMonitor, you can skip this step.

Log on to the CloudMonitor alert contacts page. Create a contact and fill in the Name and Region for alarm Notification Service, and configure alert notification methods. Supported methods include SMS, email, DingTalk, Lark, WeCom, and Webhook.
In the alert contacts list, the Mobile Number column shows the status Pending Activation (Resend activation code). To complete the verification, click the activation link or resend the activation code.

Step 2: Create matching applications

Log on to the MSE XXL-JOB console and select a region from the top menu bar.
Navigate to your XXL-JOB instance. In the left-side navigation pane, select Application Management, and then click Create Application.
Manually create an application, ensuring its name is identical to the AppName in your open source XXL-JOB.

On the application management page, click the Create application button. After creating the application, you can confirm its name in the AppName column of the list.

Step 3: Export jobs

This tool supports all XXL-JOB versions from 2.1.1 onwards. When exporting, select the tool version that corresponds to your system.

Download the export tool.

Unzip the tool package and configure the export settings in the application.properties file.

Note

We recommend configuring the xxl-job.alarm.users (alert contacts from CloudMonitor) and xxl-job.alarm.channel (notification methods) parameters in the application.properties file.

In the application.properties configuration file, configure the database information for your XXL-JOB jobs.
(Optional) In the application.properties configuration file, specify the app-name to export. If this is not set, jobs from all application groups will be exported.

After unzipping, navigate to the distribution directory. You will find application.properties, readme.txt, start.cmd, start.sh, and xxljob-export-v2.x.0.jar files for different versions.

### xxl-job, datasource
datasource.url=jdbc:mysql://127.0.0.1:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&serverTimezone=Asia/Shanghai
datasource.username=root
datasource.password=123456
datasource.driver-class-name=com.mysql.cj.jdbc.Driver
# Export job filter conditions
# Filter by application group app-name. Separate multiple names with a comma (,). (Optional) If not set, jobs from all application groups are exported.
#xxl-job.filter.app-name=xxl-job-executor-sample1,xxl-job-executor-sample2
# Filter by job description, must contain the specified string. (Optional)
#xxl-job.filter.job-desc=test
# Filter by author information, must contain the specified string. (Optional)
#xxl-job.filter.author=test
# Filter jobs by trigger status. If not set, jobs in all states are exported. (Optional)
#xxl-job.filter.trigger-status=0
# Pagination read: Starting position for reading jobs, sorted by job ID. Default is 0. (Optional)
#xxl-job.filter.page-start=0
# Pagination read: Number of rows to read after the starting position. Default is unlimited. (Optional)
#xxl-job.filter.page-size=10
# Default status for exported jobs. 0: Disabled, 1: Enabled. Defaults to the job's original status. (Optional)
#xxl-job.default.job-status=0
# CloudMonitor alert contacts. Separate multiple names with a comma (,). (Optional)
#xxl-job.alarm.users=John Doe,Jane Smith
# Alert notification channels. sms: SMS, mail: Email, phone: Phone, webhook: DingTalk/Lark/WeCom. Separate multiple channels with a comma (,). (Optional)
#xxl-job.alarm.channel=sms,mail

Run the ./start.sh $version command to start the export. If you do not specify a version, the tool uses version 2.2.0 by default.

Important

If you are using version 2.1.1 or 2.1.2, you can also use the 2.2.0 export tool.

# sh start.sh defaults to version 2.2.0
sh start.sh 2.3.0

slamdu... xxx % sh start.sh 2.3.0
15:57:30.610 logback [main] INFO  com.zaxxer.hikari.HikariDataSource - HikariPool-1 - Starting...
15:57:30.846 logback [main] INFO  com.zaxxer.hikari.HikariDataSource - HikariPool-1 - Start completed.
<app2> start export job...
<app2> finish convert job size&lt;1&gt;
<app7> start export job...
<app7> finish convert job size&lt;2&gt;
finish export job size&lt;3&gt;
export finished.

After the export is complete, a job configuration file named xxljob_version_*******.json is generated in the current directory. This file contains configuration information for jobs in Bean mode only.

The following is an example of the export format for version 2.2.0:

The top-level structure includes fields such as version, type, kind, and content. The content field contains the specific job data.
Within content, data is grouped by application. Each element includes the appName and jobConfigInfo fields.

jobConfigInfo is an array that contains a list of job details for the corresponding application. Job information fields include name, jobType, timeConfig, executeMode, and routeStrategy.

Export example

{
  "content":[
    {
      "appName":"app2",
      "description":"Application Group 2",
      "jobConfigInfo":[
        {
          "attemptInterval":30,
          "contactInfoList":[
            {
              "contactType":1,
              "name":"John Doe"
            },
            {
              "contactType":1,
              "name":"Jane Smith"
            }
          ],
          "content":"{\"jobHandler\":\"failJobHandler\"}",
          "description":"test-job04, Owner: cxy",
          "executeMode":"standalone",
          "jobType":"xxljob",
          "maxAttempt":0,
          "monitorConfigInfo":{
            "alarmType":"CustomContacts",
            "sendChannel":"sms,mail",
            "timeout":10
          },
          "name":"test-job04",
          "parameters":"",
          "routeStrategy":2,
          "status":0,
          "timeConfig":{
            "dataOffset":0,
            "timeExpression":"* * * 1 * ?",
            "timeType":1
          }
        },
        {
          "attemptInterval":30,
          "contactInfoList":[
            {
              "contactType":1,
              "name":"John Doe"
            },
            {
              "contactType":1,
              "name":"Jane Smith"
            }
          ],
          "content":"{\"jobHandler\":\"shardingJobHandler\"}",
          "description":"test-job03, Owner: cxy",
          "executeMode":"broadcast",
          "jobType":"xxljob",
          "maxAttempt":0,
          "monitorConfigInfo":{
            "alarmType":"CustomContacts",
            "sendChannel":"sms,mail",
            "timeout":0
          },
          "name":"test-job03",
          "parameters":"",
          "routeStrategy":8,
          "status":1,
          "timeConfig":{
            "dataOffset":0,
            "timeExpression":"* * 18 * * ?",
            "timeType":1
          }
        }
      ]
    }
  ],
  "kind":"SchedulerXJobs",
  "overwrite":true,
  "type":"JSON",
  "version":"2.0"
}

Step 4: Import jobs

Upload the exported JSON file directly to Alibaba Cloud XXL-JOB to import jobs in bulk.

Log on to the MSE XXL-JOB console and select a region. Navigate to your XXL-JOB instance. In the left-side navigation pane, select Task Management, and then click Import Job.

The Import Job dialog box has the following options:
- Duplicate job: Select Overwrite to replace an existing job's configuration, or Skip to leave it unchanged.
- Automatically create application: If set to Yes, applications that do not exist are created automatically during import. If set to No, jobs for non-existent applications are skipped.
Select the exported job configuration file to begin the import. This synchronizes your XXL-JOB configurations to Alibaba Cloud XXL-JOB.

Step 5: Redeploy the application

Based on the version of the xxl-job-core client you are using, select the appropriate redeployment steps.

Version 2.1.1 or later

Alibaba Cloud XXL-JOB is fully compatible with the client protocol for xxl-job-core version 2.1.1 and later. You only need to restart your application with specific -D parameters.

In the left-side navigation pane, go to the Application Management page. In the Actions column for the target application, click access configuration.
Select Access method 2: Restart the application by using the -D parameter (no modifications of code and configuration files). Add the provided -D parameters to your application's startup command, and then restart the application.

The required -D parameters include -Dxxl.job.admin.addresses, -Dxxl.job.accessToken, and -Dxxl.job.executor.appname. Copy the values for these parameters from the access configuration dialog in the console.
After a successful connection, the Number of executors column on the Application Management page displays the number of connected clients.

Version 2.1.0

No code changes are required. You only need to replace a dependency. In your pom.xml file, change the version of the com.xuxueli:xxl-job-core dependency to 2.1.2. Your business code is fully compatible. After updating the dependency, follow the steps for Version 2.1.1 or later to redeploy the application.

Versions 1.x and 2.0.x

You do not need to change your business logic. Simply update the dependency and adjust the XxlJobExecutor initialization.

Update the dependency by changing the xxl-job-core version to 2.1.2 in your pom.xml file.

<dependency>
  <groupId>com.xuxueli</groupId>
  <artifactId>xxl-job-core</artifactId>
  <version>2.1.2</version>
</dependency>

In your XxlJobConfig file, change the initialization of XxlJobExecutor to use XxlJobSpringExecutor.

Important

Do not add initMethod or destroyMethod to the @Bean annotation.

@Bean
public XxlJobSpringExecutor xxlJobExecutor() {
    logger.info(">>>>>>>>>>> xxl-job config init.");
    XxlJobSpringExecutor xxlJobSpringExecutor = new XxlJobSpringExecutor();
    xxlJobSpringExecutor.setAdminAddresses(adminAddresses);
    xxlJobSpringExecutor.setAppName(appName);
    xxlJobSpringExecutor.setIp(ip);
    xxlJobSpringExecutor.setPort(port);
    xxlJobSpringExecutor.setAccessToken(accessToken);
    xxlJobSpringExecutor.setLogPath(logPath);
    xxlJobSpringExecutor.setLogRetentionDays(logRetentionDays);
    return xxlJobSpringExecutor;
}

Follow the steps for Version 2.1.1 or later to redeploy the application.