OTA Jobs

Jobs

Jobs in IoT is the definition of new OtaUpdate for the given target with the given firmware. The targetType can be a Device or Group. If the target is a device, the OTA update job is created for the given device whereas if it is a group, it will be applied to all the devices under that group.

Job execution states:

QUEUED
IN_PROGRESS
SUCCEEDED
FAILED
TIMED_OUT
REJECTED
CANCELED

Terminal States : SUCCEEDED, FAILED, TIMED_OUT, CANCELED, and REJECTED.

The following shows the MQTT API operations and their request and response syntax. All MQTT API operations have the following parameters:

clientToken: An optional client token that can be used to correlate requests and responses. Enter an arbitrary value here and it will be reflected in the response.
timestamp: The time in seconds since the epoch, when the message was sent.

####GetPendingJobExecutions

Gets the list of all jobs that are not in a terminal state, for a specified device.

Request Topic	$aws/things/{clientId}/jobs/get
Request Payload	```json { "clientToken": "string" } or Empty Payload ```

Response Topic	$aws/things/{clientId}/jobs/get/accepted
Response Payload	```json { "inProgressJobs" : [ JobExecutionSummary ... ], "queuedJobs" : [ JobExecutionSummary ... ], "timestamp" : long, "clientToken" :”string" } ```

Response Topic	$aws/things/{clientId}/jobs/get/rejected
Response Payload	Error

####StartNextPendingJobExecution

Gets and starts the next pending job execution for a device. Updates the next pending job execution in QUEUED to IN_PROGRESS.

Request Topic	$aws/things/{clientId}/jobs/start-next
Request Payload	```json { "statusDetails": { "string": "string" ... }, "stepTimeoutInMinutes": long, "clientToken": "string" } ```

statusDetails: (Optional) A collection of name-value pairs that describe the status of the job execution.
stepTimeOutInMinutes: (Optional) Specifies the amount of time the device has to finish execution of the job. The job execution will be set to TIMED_OUT, if the job execution status is not set to a terminal state before this timer expires. The timer can be reset by calling UpdateJobExecution, setting the status to IN_PROGRESS and specifying a new timeout value.

Response Topic	$aws/things/{clientId}/jobs/start-next/accepted
Response Payload	```json { "execution" : JobExecution, "timestamp" : long, "clientToken" : "string" } ```

Response Topic	$aws/things/{clientId}/jobs/start-next/rejected
Response Payload	Error

####DescribeJobExecution

Gets detailed information about a job execution.

Request Topic	$aws/things/{clientId}/jobs/{jobId}/get
Request Payload	```json { "executionNumber": long, "includeJobDocument": boolean, "clientToken": "string" } ```

jobId: The unique identifier assigned to this job when it was created. Set the jobId to $next to return the next pending job execution for a device.
executionNumber: (Optional) A number that identifies a job execution on a device. If not specified, the latest job execution is returned.
includeJobDocument: (Optional) Unless set to false, the response contains the job document. The default is true.

Response Topic	$aws/things/{clientId}/jobs/{jobId}/get/accepted
Response Payload	```json { "execution" : Job, "timestamp": long, "clientToken": "string" } ```

Response Topic	$aws/things/{clientId}/jobs/{jobId}/get/rejected
Response Payload	Error

####UpdateJobExecution

Updates the status of a job execution. Step timer can be created optionally by setting a value for the stepTimeoutInMinutes property.

Request Topic	$aws/things/{clientId}/jobs/{jobId}/update
Request Payload	```json { "status": "string", "statusDetails": { "string": "string" ... }, "expectedVersion": "number", "executionNumber": long, "includeJobExecutionState": boolean, "includeJobDocument": boolean, "stepTimeoutInMinutes": long, "clientToken": "string" } ```

status: (Optional) The new status for the job execution (IN_PROGRESS, FAILED, SUCCEEDED, or REJECTED).
statusDetails: (Optional) A collection of name-value pairs that describe the status of the job execution.
expectedVersion: (Optional) The expected current version of the job execution. Each time you update the job execution, its version is incremented. The version should match the value in IoT Jobs Service.
executionNumber: (Optional) A number that identifies a job execution on a device. If not specified, the latest job execution is used.
includeJobExecutionState: (Optional) When included and set to true, the response contains the JobExecutionState field. The default is false.
includeJobDocument: (Optional) When included and set to true, the response contains the JobDocument. The default is false.
stepTimeoutInMinutes: (Optional) Specifies the amount of time this device has to finish execution of this job. The job execution will be set to TIMED_OUT, if the job execution status is not set to a terminal state before this timer expires.

Response Topic	$aws/things/{clientId}/jobs/{jobId}/update/accepted
Response Payload	```json { "executionState": JobExecutionState, "jobDocument": "string", "timestamp": long, "clientToken": "string" } ```

Response Topic	$aws/things/{clientId}/jobs/{jobId}/update/rejected
Response Payload	Error

####JobExecutionsChanged

Sent whenever a job execution is added to or removed from the list of pending job executions for a device.

Response Topic	$aws/things/{clientId}/jobs/notify
Response Payload	```json { "jobs" : { "JobExecutionState": [ JobExecutionSummary ... ] }, "timestamp": long } ```

####NextJobExecutionChanged

Device receives a notification whenever there is a change to the job execution that is next on the list of pending job executions, as defined for DescribeJobExecution with jobId $next. (This message is not sent when the next job’s execution details change, only when the next job that would be returned by DescribeJobExecution with jobId $next has changed). Consider job executions J1 and J2 with a status of QUEUED. J1 is next on the list of pending job executions. If the status of J2 is changed to IN_PROGRESS while the state of J1 remains unchanged, then this notification is sent and contains details of J2.

Response Topic	$aws/things/{clientId}/jobs/notify-next
Response Payload	```json { "execution" : JobExecution, "timestamp": long, } ```

####Message Structure

JobExecutionSummary	```json { "jobId": "string", "queuedAt": long, "startedAt": long, "lastUpdatedAt": long, "versionNumber": "number", "executionNumber": long } ```
JobExecution	```json { "jobId": "string", "status": "string", "queuedAt": long, "startedAt": long, "lastUpdatedAt": long, "versionNumber": number, "executionNumber": number, "jobDocument": JobDocument, } ```
Job	```json { "jobId" : "string", "jobDocument" : JobDocument, "status": "string", "statusDetails": { "string": "string" }, "queuedAt" : long, "startedAt" : long, "lastUpdatedAt" : long, "versionNumber" : number, "executionNumber": long } ```
JobExecutionState	```json { "status": "string", "statusDetails": { "string": "string" ... } "versionNumber": number } ```
JobDocument HTTP	```json { "afr_ota": { "protocols": [ "HTTP" ], "files": { "filepath": "string", "fileid": number, "filesize": long, "certfile": "string", "update_data_url": "string", "auth_scheme": "aws.s3.presigned", "firmware_version": "string", "sig-sha-1-rsa": "string", "job_expiration_utc":"string" } } } ```
Job Document MQTT	```json { "afr_ota": { "protocols": [ "MQTT" ], "files": { "filepath": "string", "fileid": “number”, "filesize": long, "certfile": "string", "firmware_version": "string", "sig-sha-1-rsa": "string" }, "streamname": "string" } } ```

Parameters

filepath: Path where the file has to be placed in device.
fileid: Identifier of the file.
filesize: Size of the file.
certfile: Path where the certificate (need to be used for signature verification) is placed in the device.
firmware_version: Firmware version
sig-sha-1-rsa: This is a custom key, which is formed using the values while the job is created. This key contains the signature of the firmware
streamname: Name of the stream which can be used to download the firmware using streams topics
update_data_url: Download url from which file can be downloaded. The url is of two types based on the expiry set for the download url while creating an OTA update job.
- If expiry is not set, the download url will have a shorter expiry say 1 hour. The download url can be regenerated using DescribeJobExecution. A new url will be sent in the job document.
- The download url with expiry set explicitly while creating an OTA update job will expire after the expiry duration along with the job (CANCELED) and cannot be regenerated.
job_expiration_utc: Time at which the job get canceled.

Error


{
  "timestamp": long,
  "code": "string",
  "message": "string"
}