Migrate jobs from self-managed XXL-JOB to Alibaba Cloud XXL-JOB - Microservices Engine

This topic describes how to migrate jobs from self-managed XXL-JOB to Alibaba Cloud XXL-JOB. You can complete job redeployment without the need to modify code. This implements efficient job scheduling and management.

Solution overview

You can use the export tool provided by Alibaba Cloud to export job configurations from an open source XXL-JOB system, and then import the job configurations to an Alibaba Cloud XXL-JOB instance. This process includes the following steps:

Optional. Create alert contacts in CloudMonitor. Alerts about system health and performance metrics can be sent to the specified alert contacts.
Manually create an application that has the same name as the application on open source XXL-JOB in advance.
Export job information and configurations from a self-managed XXL-JOB system.
Import the job information and configurations to Alibaba Cloud XXL-JOB.
After the job information and configurations are imported, redeploy the applications. This ensures that the applications are imported to Alibaba Cloud XXL-JOB and can run as expected.

Step 1: (Optional) Create alert contacts in the CloudMonitor console

Note

If you have created alert contacts in CloudMonitor, skip this step.

Go to the Alert Contacts page in the CloudMonitor console. Click Create Alert Contact. In the panel that appears, configure the Name and Region for alarm Notification Service parameters and configure notification methods. The following notification methods are supported: mobile phone, email, DingTalk, Lark, WeCom, and webhooks.
After you create an alert contact, ask the contact to click the activation link that is sent by using the specified notification method.

Step 2: Create an application with the same name in advance

Log on to the MSE console, go to the XXL-JOBVersion page, and then select a region in the top navigation bar.
Click the ID of your XXL-JOB instance to go to the instance details page. On the instance details page, click Application Management in the left-side navigation pane. On the page that appears, click CreateApplication.
Manually create an application that has the same name as the application on open source XXL-JOB.

Step 3: Export job information and configurations from self-managed XXL-JOB

Jobs on open source XXL-JOB 2.1.1 or later can be migrated to Alibaba Cloud XXL-JOB. When you export job information and configurations, use the export tool of an appropriate version.

Download the export tool package.

Decompress the package and configure export settings in the application.properties file.

Note

We recommend that you configure the xxl-job.alarm.users and xxl-job.alarm.channel parameters in the application.properties file to specify the alert contacts and notification methods.

In the application.properties file, specify the database information of the XXL-JOB jobs.
Optional. In the application.properties file, specify the name of the application whose job configurations you want to export. If you skip this step, the configurations of the jobs in all applications are exported.

### 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

# The filter rules.
# The name of the application whose job configurations you want to export. Separate multiple names with commas (,). If you do not specify this parameter, the configurations of the jobs in all applications are exported.
#xxl-job.filter.app-name=xxl-job-executor-sample1,xxl-job-executor-sample2

# Optional. The string that must be contained in the job description.
#xxl-job.filter.job-desc=test

# Optional. The string that must be contained in the author information.
#xxl-job.filter.author=test

# Optional. The status of the job. If you do not specify this parameter, jobs in any state are exported.
#xxl-job.filter.trigger-status=0

# Optional. The start position of reading jobs in pages, with jobs sorted based on IDs. Default value: 0.
#xxl-job.filter.page-start=0

# Optional. The page size. If you do not specify this parameter, the page size is unlimited.
#xxl-job.filter.page-size=10

# Optional. The status of exported jobs. A value of 0 indicates that the exported jobs are disabled. A value of 1 indicates that the exported jobs are enabled. If you do not specify this parameter, the original status of the jobs is retained.
#xxl-job.default.job-status=0

# Optional. The alert contacts created in CloudMonitor. Separate multiple contacts with commas (,).
# xxl-job.alarm.users=Zhang San,Li Si

# Optional. The notification methods. Valid values: sms, mail, phone, and webhook. DingTalk, Lark, and WeCom webhooks are supported. Separate multiple methods with commas (,).
#xxl-job.alarm.channel=sms,mail

Run the ./start.sh $version command to export job configurations. If you do not specify a version number, the export tool of version 2.2.0 is used by default.
Important
If the version of open source XXL-JOB is 2.1.1 or 2.1.2, you can also use the export tool of version 2.2.0 to export job configurations.
```
# If you run the sh start.sh command without specifying a version number, the export tool of version 2.2.0 is used by default.
sh start.sh 2.3.0
```

After the configurations are exported, obtain a configuration file named xxljob_version_*******.json in the current directory. The file contains only the configurations of jobs in Bean mode.

The following content describes the structure of a configuration file exported from an XXL-JOB 2.2.0 system:

The outermost layer includes fields such as version, type, kind, and content. The value of the content field is the specific job information.
In the value of the content field, job information is grouped by application. Each element in the value contains the appName and jobConfigInfo fields.

The value of the jobConfigInfo field is an array that contains the job information in an application, such as name, jobType, and timeConfig.

Example of exported job configurations

{
  "content":[
    {
      "appName":"app2",
      "description":"Application group 2",
      "jobConfigInfo":[
        {
          "attemptInterval":30,
          "contactInfoList":[
            {
              "contactType":1,
              "name":"Zhang San"
            },
            {
              "contactType":1,
              "name":"Li Si"
            }
          ],
          "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":"Zhang San"
            },
            {
              "contactType":1,
              "name":"Li Si"
            }
          ],
          "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 to Alibaba Cloud XXL-JOB

Upload the generated JSON configuration file to Alibaba Cloud XXL-JOB. This allows you to import configurations of multiple jobs at a time.

Log on to the MSE console, go to the XXL-JOBVersion page, and then select a region in the top navigation bar. Find the XXL-JOB instance that you want to manage and click its ID. In the left-side navigation pane of the instance details page, click Task Management. On the Task Management page, click Import Task.
In the Import Task dialog box, configure the following parameters:
- Same task: specifies whether to overwrite jobs with the same name. Default value: Cover. If you select Skip, jobs with the same name are skipped and are not imported.
- Automatic CreationApp: specifies whether to automatically create applications that are specified in the configuration file but do not exist in the XXL-JOB instance and import the jobs in these applications. Default value: Yes. If you select No, jobs in applications that do not exist in the XXL-JOB instance are not imported.
In the Import Task dialog box, click Select File and select the job configuration file that is generated in the preceding step to import the job configurations to Alibaba Cloud XXL-JOB.

Step 5: Redeploy the application

Select the appropriate restart procedure based on the version of the xxl-job-core client in use.

2.1.1 and later

Alibaba Cloud XXL-JOB is fully compatible with the protocol used by the xxl-job-core client of version 2.1.1 or later. You only need to restart the application by using the -D parameters. To restart the application, perform the following steps:

In the left-side navigation pane, click Application Management. Click Access Configuration in the Operation column of the application.
Select Access Method 2: Restart the Application By Using the -D Parameter (No Modifications of Code and Configuration Files). After you add -D parameters for the application, restart the application.
After the application is restarted, view the number of executors in the Number of actuators column on the Application Management page.

2.1.0

You do not need to modify any code. You only need to change the version number of the com.xuxueli:xxl-job-core dependency in the pom.xml file to 2.1.2. The business code is fully compatible. After you change the version number, follow the steps in 2.1.1 or later to redeploy the application.

1.x and 2.0.x

You do not need to modify business code. You only need to change the dependency information and modify the initialization logic of XxlJobExecutor. To redeploy the application, perform the following steps:

Change the xxl-job-core version in the dependency to 2.1.2.

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

In XxlJobConfig, replace the initialization content of XxlJobExecutor with that of XxlJobSpringExecutor.

Important

Do not add initMethod and destroyMethod to @Bean.

@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 in 2.1.1 and later to redeploy the application.