Menu
AWS IoT
Developer Guide

Devices and Jobs

device communication with Jobsusing the MQTT protocolusing HTTP SigV4using HTTP TLS
device communication with Jobs

Devices can communicate with Jobs through one of three methods:

  • MQTT

  • HTTP SigV4

  • HTTP TLS

using the MQTT protocol

Communication between the Jobs service and your devices can occur over the MQTT protocol. Devices subscribe to MQTT topics to be notified of new jobs and to receive responses from the Jobs service. Devices publish on MQTT topics to query or update the state of a job execution. Each device has its own general MQTT topic. For more information about publishing and subscribing to MQTT topics, see Message Broker for AWS IoT

Note

You must use the correct endpoint when communicating with Jobs via MQTT. To find it, use the DescribeEndpoint command. For example, using the CLI:

aws iot describe-endpoint --endpoint-type iot:Data

you will get a result similar to:

{ "endpointAddress": "a1b2c3d4e5f6g7.iot.us-west-2.amazonaws.com" }

With this method, your device uses its device-specific certificate and private key to authenticate with the Jobs service.

Devices can:

  • Be notified whenever a job execution is added or removed from the list of pending job executions for a device by subscribing to the $aws/things/thing-name/jobs/notify MQTT topic, where thing-name is the name of the thing associated with the device.

  • Be notified when the next pending job execution has changed by subscribing to the $aws/things/thing-name/jobs/notify-next MQTT topic, where thing-name is the name of the thing associated with the device.

  • Update the status of a job execution by calling the UpdateJobExecution API.

  • Query the status of a job execution by calling the DescribeJobExecution API.

  • Retrieve a list of pending job executions by calling the GetPendingJobExecutions API.

  • Retrieve the next pending job execution by calling the DescribeJobExecution API with jobId $next.

  • Get and start the next pending job execution by calling the StartNextPendingJobExecution API.

The Jobs service publishes success and failure messages on an MQTT topic formed by appending accepted or rejected to the topic used to make the request. For example, if a request message is published on the $aws/things/myThing/jobs/get topic, the Jobs service publishes success messages on the $aws/things/myThing/jobs/get/accepted topic and publishes rejected messages on the $aws/things/myThing/jobs/get/rejected topic.

using HTTP SigV4

Communication between the Jobs service and your devices can occur over HTTP SigV4 on port 443. This is the method used by the AWS SDKs and CLI. For more information about those tools, see AWS CLI Command Reference: iot-jobs-data or AWS SDKs and Tools and refer to the IotJobsDataPlane section for your preferred language.

Note

You must use the correct endpoint when communicating with Jobs via HTTP SigV4 or using an AWS SDK or CLI IotJobsDataPlane command. To find it, use the DescribeEndpoint command. For example, using the CLI:

aws iot describe-endpoint --endpoint-type iot:Jobs

you will get a result similar to:

{ "endpointAddress": "a1b2c3d4e5f6g7.jobs.iot.us-west-2.amazonaws.com" }

With this method of communication, your device will use IAM credentials to authenticate with the Jobs service.

The following commands are available using this method:

  • DescribeJobExecution

    aws iot-jobs-data describe-job-execution ...

  • GetPendingJobExecutions

    aws iot-jobs-data get-pending-job-executions ...

  • StartNextPendingJobExecution

    aws iot-jobs-data start-next-pending-job-execution ...

  • UpdateJobExecution

    aws iot-jobs-data update-job-execution ...

using HTTP TLS

Communication between the Jobs service and your devices can occur over HTTP TLS on port 8443 using a third-party software client that supports this protocol.

Note

You must use the correct endpoint when communicating with Jobs via HTTP TLS. To find it, use the DescribeEndpoint command. For example, using the CLI:

aws iot describe-endpoint --endpoint-type iot:Jobs

you will get a result similar to:

{ "endpointAddress": "a1b2c3d4e5f6g7.jobs.iot.us-west-2.amazonaws.com" }

With this method, your device uses X509 certificate based authentication (for example, using its device-specific certificate and private key.)

The following commands are available using this method:

  • DescribeJobExecution

  • GetPendingJobExecutions

  • StartNextPendingJobExecution

  • UpdateJobExecution

Programming Devices to Work with Jobs

The examples in this section use MQTT to illustrate how a device works with Jobs. Alternatively, you could use the corresponding API or CLI commands if you want. For these examples, we assume a device called MyThing will subscribe 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

Device Workflow

In general, there are two ways a device can handle the jobs it is given to execute.

Option A: Get the next jobOption B: Pick from available jobs
Option A: Get the next job
  1. When a device first comes online, it should subscribe to the device's notify-next topic.

  2. 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.

  3. 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.

  4. Perform the actions specified by the job document using the UpdateJobExecution MQTT API to report on the progress of the job.

  5. Call the UpdateJobExecution MQTT API again to update the job status and report success or failure.

  6. Because this job's execution status has been changed to a terminal status, the next job available for execution (if any) will change. 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 will continue to receive a notifications of the next pending job execution, including its JobExecutionData, whenever it completes a job or when a new pending job execution is added. When this occurs, the device continues as described in step 2.

Option B: Pick from available jobs
  1. When a device first comes online, it should subscribe to the thing's notify topic.

  2. Call the GetPendingJobExecutions MQTT API to get a list of pending job executions.

  3. If the list contains one or more job executions, pick one.

  4. Call the DescribeJobExecution MQTT API to get the job document and other details, including any state saved in statusDetails.

  5. Call the UpdateJobExecution MQTT API to update the job status. If the includeJobDocument field is set to true in this command, the device can skip the previous step and retrieve the job document at this point.

  6. Perform the actions specified by the job document using the UpdateJobExecution MQTT API to report on the progress of the job.

  7. Call the UpdateJobExecution MQTT API again to update the job status and report success or failure.

If the device remains online, it will be notified of all pending job executions whenever a new pending job execution becomes available. When this occurs, the device can continue 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.

Starting a New Job

new job notificationmore info (13)
new job notification

When a new job is created, Jobs publishes a message on the $aws/things/thing-name/jobs/notify topic for each target device.

more info (13)

The message contains the following information:

{ "timestamp":1476214217017, "jobs":{ "QUEUED":[{ "jobId":"0001", "queuedAt":1476214216981, "lastUpdatedAt":1476214216981, "versionNumber" : 1 }] } }

The device receives this message on the '$aws/things/thingName/jobs/notify' topic when the job execution is queued.

get job informationmore info (14)
get job information

To get more information about a job execution, the device calls the DescribeJobExecution MQTT API with the includeJobDocument field set to true.

more info (14)

If the request is successful, Jobs publishes a message on the $aws/things/MyThing/jobs/0023/get/accepted topic:

{ "clientToken" : "client-001", "timestamp" : 1489097434407, "execution" : { "jobId" : "023", "status" : "QUEUED", "queuedAt" : 1489097374841, "lastUpdatedAt" : 1489097374841, "versionNumber" : 1, "jobDocument" : { < contents of job document > } } }

Note

If the request fails, Jobs publishes a message on the $aws/things/MyThing/jobs/0023/get/rejected topic.

The device now has the job document, which it can interpret to perform the remote operations for the job. If the job document contains an Amazon S3 presigned URL, the device can use that URL to download any required files for the job.

The device can call the StartNextPendingJobExecution MQTT API to request more information and start any pending job execution, in one step.

Report Job Execution Status

update execution statusmore info (15)
update execution status

As the device is executing the job, it can call the UpdateJobExecution MQTT API to update the status of the job execution.

more info (15)

For example, a device can update the job execution status to IN_PROGRESS by publishing the following message on the $aws/things/MyThing/jobs/0023/update topic:

{ "status":"IN_PROGRESS", "statusDetails": { "progress":"50%" }, "expectedVersion":"1", "clientToken":"client001" }

Jobs responds by publishing a message to the $aws/things/MyThing/jobs/0023/update/accepted or $aws/things/MyThing/jobs/0023/update/rejected topic:

{ "clientToken":"client001", "timestamp":1476289222841 }

The device can combine the two previous requests by calling StartNextPendingJobExecution, which gets and starts the next pending job execution and allows the device to update the job execution status. This request also returns the job document when there is a job execution pending.

The status field can be set to QUEUED, IN_PROGRESS, SUCCESS, FAILED, REJECTED, REMOVED, or CANCELED. You cannot update the status of a job execution that is already in a terminal state.

report execution completedmore info (16)
report execution completed

When the device is finished executing the job, it calls the UpdateJobExecution MQTT API. If the job was successful, set status to SUCCESS and, in statusDetails in the message payload, add other information about the job as name/value pairs.

more info (16)

For example:

{ "status":"SUCCESS", "statusDetails": { "progress":"100%" }, "expectedVersion":"2", "clientToken":"client-001" }

If the job was not successful, set status to FAILED and, in statusDetails, add information about the error that occurred:

{ "status":"FAILED", "statusDetails": { "errorCode":"101", "errorMsg":"Unable to install update" }, "expectedVersion":"2", "clientToken":"client-001" }

Note

The statusDetails attribute can contain any number of name/value pairs.

When Jobs receives this update, it publishes a message on the $aws/things/MyThing/jobs/notify topic to indicate the job execution is complete:

{ "timestamp":1476290692776, "jobs":{} }

Additional Jobs

additional jobsmore info (17)
additional jobs

If there are other job executions pending for the device, they are included in the message published to $aws/things/MyThing/jobs/notify.

more info (17)

For example:

{ "timestamp":1476290692776, "jobs":{ "QUEUED":[{ "jobId":"0002", "queuedAt":1476290646230, "lastUpdatedAt":1476290646230 }], "IN_PROCESS":[{ "jobId":"0003", "queuedAt":1476290646230, "lastUpdatedAt":1476290646230 }] } }