Module rustot::jobs[−][src]

Expand description

Iot Jobs Data

Programming Devices to Work with Jobs

The examples in this section use MQTT to illustrate how a device works with the AWS IoT Jobs service. Alternatively, you could use the corresponding API or CLI commands. For these examples, we assume a device called MyThing subscribes to the following MQTT topics:

$aws/things/{MyThing}/jobs/notify (or $aws/things/{MyThing}/jobs/notify-next)

$aws/things/{MyThing}/jobs/get/accepted

$aws/things/{MyThing}/jobs/get/rejected

$aws/things/{MyThing}/jobs/{jobId}/get/accepted

$aws/things/{MyThing}/jobs/{jobId}/get/rejected

If you are using Code-signing for AWS IoT your device code must verify the signature of your code file. The signature is in the job document in the codesign property.

Workflow:

When a device first comes online, it should subscribe to the device’s notify-next topic.
Call the DescribeJobExecution MQTT API with jobId $next to get the next job, its job document, and other details, including any state saved in statusDetails. If the job document has a code file signature, you must verify the signature before proceeding with processing the job request.
Call the UpdateJobExecution MQTT API to update the job status. Or, to combine this and the previous step in one call, the device can call StartNextPendingJobExecution.
(Optional) You can add a step timer by setting a value for stepTimeoutInMinutes when you call either UpdateJobExecution or StartNextPendingJobExecution.
Perform the actions specified by the job document using the UpdateJobExecution MQTT API to report on the progress of the job.
Continue to monitor the job execution by calling the DescribeJobExecution MQTT API with this jobId. If the job execution is canceled or deleted while the device is running the job, the device should be capable of recovering to a valid state.
Call the UpdateJobExecution MQTT API when finished with the job to update the job status and report success or failure.
Because this job’s execution status has been changed to a terminal state, the next job available for execution (if any) changes. The device is notified that the next pending job execution has changed. At this point, the device should continue as described in step 2.

If the device remains online, it continues to receive a notifications of the next pending job execution, including its job execution data, when it completes a job or a new pending job execution is added. When this occurs, the device continues as described in step 2.

If the device is unable to execute the job, it should call the UpdateJobExecution MQTT API to update the job status to REJECTED.

Jobs Notifications

The AWS IoT Jobs service publishes MQTT messages to reserved topics when jobs are pending or when the first job execution in the list changes. Devices can keep track of pending jobs by subscribing to these topics.

Job notifications are published to MQTT topics as JSON payloads. There are two kinds of notifications:

A ListNotification contains a list of no more than 10 pending job executions. The job executions in this list have status values of either IN_PROGRESS or QUEUED. They are sorted by status (IN_PROGRESS job executions before QUEUED job executions) and then by the times when they were queued.

A ListNotification is published whenever one of the following criteria is met.

A new job execution is queued or changes to a non-terminal status (IN_PROGRESS or QUEUED).

An old job execution changes to a terminal status (FAILED, SUCCEEDED, CANCELED, TIMED_OUT, REJECTED, or REMOVED).

A NextNotification contains summary information about the one job execution that is next in the queue.

A NextNotification is published whenever the first job execution in the list changes.

A new job execution is added to the list as QUEUED, and it is the first one in the list.

The status of an existing job execution that was not the first one in the list changes from QUEUED to IN_PROGRESS and becomes the first one in the list. (This happens when there are no other IN_PROGRESS job executions in the list or when the job execution whose status changes from QUEUED to IN_PROGRESS was queued earlier than any other IN_PROGRESS job execution in the list.)

The status of the job execution that is first in the list changes to a terminal status and is removed from the list.