V2.1 Create OTA Job¶

Create an OTA job for batch verification or upgrading.

This API is available in EnOS 2.2.0 and above.

Operation Permissions¶

Before invoking this API, ensure that the service account has been authorized the policy that includes the following service(s) and action permission(s). For how to authorize the service account, see Managing Service Accounts.

Required Service	Required Operation Permission
Firmware	Create OTA

Prerequisite¶

The required device and firmware have been created.
You have learnt the Limitations about firmware upgrades.

Request Format¶

POST https://{apigw-address}/connect-service/v2.1/ota-jobs?action=create

Request Parameters (URI)¶

Name	Location (Path/Query)	Mandatory/Optional	Data Type	Description
orgId	Query	Mandatory	String	The organization ID which the asset belongs to. How to get orgId>>
firmwareId	Query	Mandatory	String	The firmware ID.

Request Parameters (Body)¶

The structure of the request parameter will vary according to whether you are creating a firmware verification task or a firmware upgrade task.

Upgrade Task¶

Name	Mandatory/Optional	Data Type	Description
name	Optional	StringI18n	The job name. For more details on the structure and locales supported, see Internationalized name struct.
type	Mandatory	String	The job type. Use `upgrade` for upgrade task.
upgradeScope	Mandatory	UpgradeScope Struct	The scope of the upgrade. For more details, see UpgradeScope Struct.
upgradePolicy	Mandatory	String	The upgrade policy. Available options are as per the below. `snapshot` `incremental`
enableUpgradeRequest	Mandatory	Boolean	`true`: Device can request for upgrade. `false`: Device cannot request for upgrade.
upgradeTimeout	Optional	Long	The timeout for the upgrade, which starts when the OTA task enters the “upgrading” state. The available range is between 300 to 172,800 seconds, with the default as 7,200. You can use the Search OTA Task API to search for the status of the OTA task.
retryPolicy	Optional	RetryPolicy Struct	The policy for retrying failed OTA tasks. Default is no retry. For more details, see RetryPolicy Struct.
schedulePolicy	Optional	SchedulePolicy Struct	The schedule policy for the OTA task. By default, the task starts immediately and repeats daily from 00:00:00 to 23:59:59. For more details, see SchedulePolicy Struct.
maximumConcurrency	Optional	Integer	The maximum number of concurrent upgrade tasks. The default value is 300.

Firmware Verification Task¶

Name	Mandatory/Optional	Data Type	Description
type	Mandatory	String	The job type. Use `verify` for verification task.
upgradeScope	Mandatory	UpgradeScope Struct	The scope of the upgrade. For more details, see UpgradeScope Struct. For firmware verification tasks, the value of the `type` parameter in this struct must be `partial`.
upgradeTimeout	Optional	Long	The timeout for the verification, which starts when the OTA task enters the “upgrading” state. The available range is between 300 to 172,800 seconds, with the default as 7,200. You can use the Search OTA Task API to search for the status of the OTA task.

UpgradeScope Struct ¶

Name	Mandatory/Optional	Data Type	Description
type	Mandatory	String	The scope of the devices to be upgraded. Available options are as per the below. `total`: Upgrade all devices whose firmware version number matches what is specified in `versionNumbers`. `partial`: Out of all the devices whose firmware version number matches what is specified in `versionNumbers`, only upgrade/verify some of them. Specify which devices for firmware upgrade by using the `deviceKeys`, `attributes`, `tags`, or `assetTrees` parameters in this struct. For firmware verification, only `deviceKeys` can be used.
versionNumbers	Mandatory	String Array	The list of firmware version numbers.
deviceKeys	Optional	String Array	Specify the devices for firmware upgrade or verification via device keys. Only one of the parameters `deviceKeys`, `attributes`, `tags`, or `assetTrees` can be used to specify the device for firmware upgrade. For firmware verification, only `deviceKeys` can be used.
attributes	Optional	Map (Key is of String type, and Value is of Object Array)	Specify the devices for firmware upgrade or verification via the attributes and their corresponding values. Only one of the parameters `deviceKeys`, `attributes`, `tags`, or `assetTrees` can be used to specify the device for firmware upgrade. For firmware verification, only `deviceKeys` can be used.
tags	Optional	Map (Key is of String type, and Value is of String Array)	Specify the devices for firmware upgrade or verification via the device tags and their corresponding values. Only one of the parameters `deviceKeys`, `attributes`, `tags`, or `assetTrees` can be used to specify the device for firmware upgrade. For firmware verification, only `deviceKeys` can be used.
assetTrees	Optional	AssetTreeScope Struct	Specify the devices for firmware upgrade or verification via asset trees (max 5 asset trees). Only one of the parameters `deviceKeys`, `attributes`, `tags`, or `assetTrees` can be used to specify the device for firmware upgrade. For firmware verification, only `deviceKeys` can be used. For more details, see AssetTreeScope Struct.

AssetTreeScope Struct ¶

Name	Mandatory/Optional	Data Type	Description
treeId	Mandatory	String	The asset tree ID.
includedNodes	Optional	String Array	The nodes in the asset tree, identified by the asset’s asset ID. Specifying one node means all sub-nodes are included as well. Leave this blank to select the entire tree.

RetryPolicy Struct ¶

Name	Mandatory/Optional	Data Type	Description
enableRetry	Optional	Boolean	`true`: Able to retry task if task fails. `false`: Not able to retry task if task fails. Default is false.
retryInterval	Mandatory if `enableRetry` is `true`	Integer	The retry interval in seconds after failure. Range: 0 to 86400.
retryCount	Mandatory if `enableRetry` is `true`	Integer	The maximum number of retries. Range: 1 - 5.

SchedulePolicy Struct ¶

Name	Mandatory/Optional	Data Type	Description
isRepeatDaily	Optional	Boolean	`true`: The task will repeat daily. `false`: The task will not repeat daily. Default is false.
startTimestamp	Mandatory	Long	The timestamp of the schedule start time.
endTimestamp	Mandatory	Long	The timestamp of the schedule end time. If `isRepeatDaily` is `true`，the end time needs to be on the same day as `startTimeStamp`.

Response Parameters¶

Name	Data Type	Description
data	JobCreateResult Struct	The details of the created OTA job. For more details, see JobCreateResult Struct.

JobCreateResult Struct ¶

Name	Data Type	Description
jobId	String	The job ID.

Error Codes¶

Code	Message	Description
24404	Firmware not found	The firmware cannot be found.
24610	Not allowed to create job as firmware is not verified while enable verification is switched on	OTA job cannot be created as firmware has switched on enable verification but the firmware has not been verified.
24611	upgradeScope type total is not allowed for verification task	The option `total` for parameter `type` in `UpgradeScope Struct` is not allowed for verification jobs.
24612	Exceeded max verification deviceKeys, max[%d]	Exceeded the maximum number (%d) of devices for verification.

Samples¶

Request Sample¶

url: https://{apigw-address}/connect-service/v2.1/ota-jobs?action=create&orgId=yourOrgId&firmwareId=yourFirmwareId
method: POST
requestBody:
{
    "name":{
        "defaultValue":"ota-job-test",
        "i18nValue":{

        }
    },
    "type":"upgrade",
    "upgradePolicy":"snapshot",
    "upgradeScope":{
        "type":"partial",
        "versionNumbers":[
            "1.0"
        ],
        "deviceKeys":[
            "deviceKey1",
            "deviceKey2"
        ]
    },
    "startSchedule":0,
    "endSchedule":86399,
    "enableUpgradeRequest":true
}

Return Sample¶

{
    "code":0,
    "msg":"OK",
    "requestId":"0bdefc0f-369f-4664-a570-695f4e31877c",
    "data":{
        "jobId":"5ee1a91029b990001b9c188e"
    }
}

SDK Samples¶

You can access the SDK samples for Connection Service on GitHub:

Java
Python