Create a custom task - IoT Platform - Alibaba Cloud Documentation Center

If batch property configuration tasks or batch service call tasks no longer meet your business requirements, you can create custom tasks and configure custom rules to meet the requirements of various scenarios. This topic describes how to create a custom task and view information about the task. This topic also describes the topics that are used during the execution of the task and the corresponding message formats.

Prerequisites

A task is deployed on a device and the corresponding management functionality is developed. For more information, see Overview.

Task management process

Create a custom task.

In the IoT Platform console, find the instance that you want to manage and click the instance name. In the left-side navigation pane of the Instance Details page, choose Maintenance > Tasks. On the Tasks page, click Create Task.

On the Create Task page, configure the parameters in the Create Task and Task Schedule steps. Then, click Complete. Move the pointer over the icon next to a parameter to view information about the parameter.

Create Task

Parameter	Description
Task Name	Specify a valid task name. You can specify a custom name.
Task Type	Set the parameter to Custom Task.
Task Description	Specify information such as the purpose of the task, which can be used to identify tasks.
Destination Device, Product, or Group	Select the devices for which you want to execute the task. You can select separate devices, devices by product, or devices by group. Important If you select devices by group, you cannot select a dynamic group.
Task Execution Rules Issued to Devices	Upload a rule file. The file must be in the `JSON` format and cannot exceed 64 KB in size. You can click Download Template to obtain a rule template. The following code shows the content of the file: `{ "key":"value" }` key: The ID of a custom field. Data type: String. value: The value that corresponds to the key. The value must be in the JSON format.
File Signature Algorithm	The signature algorithm. Valid values: MD5 and SHA256. This parameter is optional. You can use the File Signature Algorithm parameter together with the Task File Issued to Devices parameter.
Task File Issued to Devices	Upload a file for the custom task. This parameter is optional. You can use the Task File Issued to Devices parameter together with the File Signature Algorithm parameter. The following file formats are supported: `.bin`, `.apk`, `.tar`, `.gz`, `.zip`, `.gzip`, and `.tar.gz`. The file cannot exceed 1,000 MB in size.

Important

You can create a custom rule file and specify custom content for a device file based on your business requirements. You must develop the implementation logic of task rules and the content of a device on the specified devices.

Task Configuration

Parameter

Description

Job Execution Push Configuration

Adjust the number of jobs pushed per minute to suit your business requirements.

Set the Number Of Jobs Executed Per Minute according to your operational needs.
Choose the Push Message Type for custom tasks and Pub batch message push tasks.
Options include:
- QoS0: Delivers the message at most once.
- QoS1: Ensures delivery at least once. If a PUBACK response is not received after sending a QoS 1 message, the message will be resent to the device upon reconnection to the IoT Platform.

Job Execution Timeout Configuration

This optional parameter allows you to set a timeout for device tasks. If not set, tasks will not time out. This is applicable only to custom tasks.

The timer starts when the device task enters the IN_PROGRESS state. If the task exceeds the set timeout without completion, the job status changes to TIMED_OUT, and the job execution ceases.

After you create the task, IoT Platform pushes the task information to the specified devices by using the /sys/{productKey}/{deviceName}/thing/job/notify topic.

Sample message:

{
    "id": "7542940",
    "version": "1.0",
    "params": {
        "task": {
            "taskId": "i5Ks6***pF010101",
            "status": "SENT",
            "jobDocument": {},
            "jobFile":{
                "signMethod":"Md5",
                "sign":"wssxff56dhdsd***",
                "fileUrl": "https://iotx-***.oss-cn-shanghai.aliyuncs.com/***.zip"
            }
        }
    }
}

jobDocument specifies the content of a rule file.

Table 1. Request Parameter Description

Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the current device.
version	String	The version of the protocol. Set this parameter to 1.0.
params	Object	The list of request parameters.
task	Object	Parameters of the subtask.
taskId	String	The ID of the subtask, which is a globally unique identifier.
status	String	The status of the subtask. SENT: Scheduled. REMOVED: Deleted. CANCELLED: Canceled.
jobDocument	Object	The job document that describes the task execution rules. Note If status is REMOVED or CANCELLED, this field is empty.
jobFile	Object	The file information uploaded when creating a custom task. signMethod: The signature method. Currently supports `Md5` and `Sha256`. sign: The signature parameter generated according to the corresponding signature method. fileUrl: The download URL of the task file, valid for 1 hour. Note ```html If status is REMOVED or CANCELLED, this field is empty.

The devices implement the rule file content based on the logic of the custom task.

If a specified device is offline and cannot receive the task information, the device can request executable tasks from the /sys/{productKey}/{deviceName}/thing/job/get topic after the device goes online. Then, the device can request the information about the custom task to complete the custom task.

Sample request that is used to obtain executable tasks:

{
    "id": "123",
    "version": "1.0",
    "params": {
        "taskId": "$list"
    }
}

Sample request that is used to obtain information about a task:

{
    "id": "123",
    "version": "1.0",
    "params": {
        "taskId": "i5Ks***F010101"
    }
}

Table 3. Request Parameter Description

Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the current device.
version	String	The version of the protocol. Set this parameter to 1.0.
params	Object	The list of request parameters.
taskId	String	Three value methods can return task information with different statuses. The ID of the subtask: Returns detailed information about the task corresponding to the job ID. `$next`: Returns information about an executable task. `$list`: Returns a list of executable tasks, with a maximum of 10 by default.

After IoT Platform receives a request, IoT Platform sends a response to the corresponding device by using the /sys/{productKey}/{deviceName}/thing/job/get_reply topic.

Sample response that includes returned tasks:

{
    "id": "1234",
    "code": 200,
    "data": {
        "statusDetails":{"devs":"test","status":"init"},
        "taskId": "$list",
        "task":[
            {
                "taskId": "i5Ks***",
                "status": "IN_PROGRESS"
            },
            {
                "taskId": "i61s***",
                "status": "IN_PROGRESS"
            }
        ]
    }
}

Sample response that includes returned information about a task:

{
    "id": "1234",
    "code": 200,
    "data": {
        "statusDetails":{"devs":"test","status":"init"},
        "taskId": "i5Ks***F010101",
        "task":{
            "taskId": "i5Ks***F010101",
            "status": "IN_PROGRESS",
            "jobDocument": {},
            "jobFile":{
                "signMethod":"Md5",
                "sign":"wssxff56dhdsd***",
                "fileUrl": "https://iotx-***.oss-cn-shanghai.aliyuncs.com/***.zip"
            }
        }
    }
}

When the task is executed, a specified device submits the task progress to IoT Platform by using the /sys/{productKey}/{deviceName}/thing/job/update topic.

Sample message:

{
    "id": "123",
    "version": "1.0",
    "params": {
        "taskId": "i5Ks***F010101",
        "status": "IN_PROGRESS",
        "statusDetails": {
            "key": "value"
        },
        "progress": 50
    }
}

Table 5. Request Parameter Description

Parameter	Type	Description
id	String	The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the current device.
version	String	The version of the protocol. Set this parameter to 1.0.
params	Object	The list of request parameters.
taskId	String	The ID of the subtask, which is a globally unique identifier.
status	String	The status of the subtask. Valid values: SUCCEEDED: Successfully completed. FAILED: Execution failed. IN_PROGRESS: Currently being executed. REJECTED: Rejected execution.
statusDetails	Object	Customizable user-defined status details. These can be viewed on the Device Management > Tasks > Task Details page in the IoT Platform console.
progress	Integer	The execution progress percentage of the subtask.

In the IoT Platform console, find the instance to which the task belongs and click the instance name. On the Instance Details page, choose Maintenance > Tasks. On the Tasks page, you can view the relevant details, including the status of the task that you created.

Important If a task is in the Timed Out state, the task can no longer be executed based on the specified schedule.

If the sub-tasks of a task fail to be executed within seven days after the time when the task was created, the task enters the Timed Out state.

You can perform one of the following operations based on your business requirements:

On the Tasks page, cancel a task that is in the Processing state.

Find the task that you want to manage and click View in the Actions column. On the task details page, view the task information and task statistics.

Tab	Description
Task Information	You can view the task information, modify the task description and task configuration, and download the rule file.
Task Summary	You can view statistics on sub-tasks by status. Find the device that you want to manage and click View to go to the device details page. On the Task tab, you can view all tasks of the device. On the Device Log tab, click View. On the Device Log page, click Cloud run log. On the Cloud run log tab, select Cloud-to-device Message from the workload type drop-down list in the search bar to view task-related logs. If a sub-task fails to be executed, click Execution details in the Actions column to view the cause of the failure. If a sub-task times out or fails to be executed, click Timed Out or Failed in the Status column to view the sub-tasks in the corresponding state. In the upper part of the Tasks page, click Rerun to re-execute the sub-tasks that are in the Timed Out and Failed states of the current task.

Click Delete in the Actions column of a task. In the message that appears, click OK.
Warning After you delete a task, all data that is related to the task is deleted. If business applications run based on the task, the applications may become unavailable and your business may be affected. Proceed with caution.