AWS IoT
Developer Guide

Managing Jobs

Jobs are created and managed using the Jobs HTTPS API, the AWS Command Line Interface or the AWS SDKs. For more information on these tools, see Job Management and Control API, AWS CLI Command Reference: iot or AWS SDKs and Tools.

Create Jobs

CreateJobmore info (1)granting permissions
CreateJob

You use the CreateJob command to create a job. The job is queued for execution on the targets (things or thing groups) that you specify. To create a job, you need a job document that can be included in the body of the request or as a link to an Amazon S3 document. If the job includes downloading files using presigned Amazon S3 URLs, you need an IAM role ARN that has permission to download the file and grants permission to AWS IoT to assume the role.

more info (1)

If you have a file called job-document.json stored in an Amazon S3 bucket called jobBucket and the role with permission to download files from Amazon S3 is called S3DownloadRole, the CLI command to create a job would look like this:

aws iot create-job \ --job-id 010 \ --targets arn:aws:iot:us-east-1:123456789012:thing/thingOne \ --document-source https://s3.amazonaws.com/jobBucket/job-document.json \ --presigned-url-config "{\"roleArn\":\"arn:aws:iam::123456789012:role/S3DownloadRole\", \"expiresInSec\":3600}"

If you want to specify the job document inline, use the --document parameter instead of the --document-source parameter.

A job is sent to and executed on targets in the order they appear in the --targets list. For example, if the targets list is:

[ arn:aws:iot:us-east-1:123456789012:thing/thingOne, arn:aws:iot:us-east-1:123456789012:thinggroup/thinggroupOne, arn:aws:iot:us-east-1:123456789012:thing/thingTwo, arn:aws:iot:us-east-1:123456789012:thinggroup/thinggroupTwo ]

then the job will be executed on thingOne, followed by the things in thinggroupOne then thingTwo and finally by the things in thinggroupTwo.

Note

Job documents that are specified as Amazon S3 files are retrieved at the time you create the job. Changing the contents of the Amazon S3 file you used as the source of your job document after you have created the job does not change what is sent to the targets of the job.

granting permissions

When creating a job that uses presigned Amazon S3 URLs, you must provide an IAM role ARN that grants permission to download files from the Amazon S3 bucket where the data or updates are stored. The role must also grant permission for AWS IoT to assume the role.

To grant Jobs permission to assume your role:

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the left navigation pane, choose Roles.

  3. Search for your role and choose it.

  4. Choose the Trust Relationships tab.

  5. Choose the Edit Trust Relationship button.

  6. On the Edit Trust Relationship page, replace the policy document with the following JSON:

    { "Version": "2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": [ "iot.amazonaws.com" ] }, "Action": "sts:AssumeRole" } ] }
  7. Choose Update Trust Policy.

  8. If your job uses a job document that is an Amazon S3 object, choose Permissions and add a policy that grants permission to download files from your Amazon S3 bucket with the following JSON:

    { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::your_S3_bucket/*" } ] }

You can optionally specify a timeout for the presigned URL. For more information, see CreateJob.

Cancel a Job

CancelJobmore info (2)
CancelJob

You use the the CancelJob command to cancel a job. Cancelling a job will stop AWS IoT rolling out any new job executions for the job. It will also cancel any job executions that have already been QUEUED. IoT will leave any job executions in a terminal state untouched because the device has already completed the job. If a job execution is IN_PROGRESS, it will also remain untouched unless you use the optional --force parameter.

more info (2)
aws iot cancel-job --job-id 010

The command displays no output.

When you cancel a job, job executions that are QUEUED will be canceled. Job executions that are IN_PROGRESS will be canceled if you specify the optional --force parameter. Job executions in a terminal state are not canceled.

Warning

Canceling a job that is IN_PROGRESS (by setting the --force parameter) will cancel any job executions that are IN_PROGRESS and cause the device that is executing the job to be unable to update the job execution status. Use caution and ensure that each device executing a job that is canceled is able to recover to a valid state.

The status of a canceled job or of one of its job executions is eventually consistent — IoT will stop scheduling new job executions and not present QUEUED job executions for that job to devices as soon as possible. But changing the status of a job execution to CANCELED may take some time depending on the number of devices and other factors.

Cancel a Job Execution

CancelJobExecutionmore info (3)
CancelJobExecution

You use the the CancelJobExecution command to cancel a job execution on a particular device. It will cancel a job execution that is QUEUED. If you want to cancel a job execution that is IN_PROGRESS, you must use the --force parameter.

more info (3)
aws iot cancel-job-execution --job-id 010 --thing-name myThing

The command displays no output.

A job execution that is QUEUED will be canceled. A job execution that is IN_PROGRESS will be canceled if you specify the optional --force parameter. Job executions in a terminal state cannot be canceled.

Warning

Canceling a job execution that is IN_PROGRESS will cause the device to be unable to update the job execution status. Use caution and ensure that the device is able to recover to a valid state.

This command will cause an InvalidStateTransitionException if the job execution is in a terminal state or if the job execution is IN_PROGRESS and the --force parameter is not set to true.

The status of a canceled job execution is eventually consistent — changing the status of a job execution to CANCELED may take some time depending various factors.

Delete a Job

DeleteJobmore info (4)
DeleteJob

You use the the DeleteJob command to delete a job and its related job executions. By default, you can only delete a job which is in a terminal state ("COMPLETED" or "CANCELED") otherwise an exception will occur. However, if the force parameter is set to true, you can delete a job which is "IN_PROGRESS".

more info (4)
aws iot delete-job --job-id 010 --force|--no-force

The command displays no output.

Warning

Deleting a job which is "IN_PROGRESS", will cause a device which is executing the job to be unable to access job information or update the job execution status. Use caution and ensure that each device executing a job which is deleted is able to recover to a valid state.

Deleting a job may take some time, depending on the number of job executions created for the job and various other factors. While the job is being deleted, the status of the job will be shown as "DELETION_IN_PROGRESS". Attempting to delete or cancel a job whose status is already "DELETION_IN_PROGRESS" will result in an error.

Only 10 jobs may have status "DELETION_IN_PROGRESS" at the same time, or a LimitExceededException will occur.

Get a Job Document

GetJobDocumentmore info (5)
GetJobDocument

You use the GetJobDocument command to retrieve a job document for a job. A job document is a description of the remote operations to be performed by the devices.

more info (5)
aws iot get-job-document --job-id 010

The command returns the job document for the specified job:

{ "document": "{\n\t\"operation\":\"install\",\n\t\"url\":\"http://amazon.com/firmWareUpate-01\",\n\t\"data\":\"${aws:iot:s3-presigned-url:https://s3.amazonaws.com/job-test-bucket/datafile}\"\n}" }

Note

When you retrieve a job document using this command, any placeholder URLs are not replaced by presigned Amazon S3 URLs. The placeholder URLs are replaced by presigned Amazon S3 URLs in the job document that is returned when a device calls the GetPendingJobExecutions MQTT API.

List Jobs

ListJobsmore info (6)
ListJobs

You use the ListJobs command to get a list of all jobs in your AWS account. Note that job data and job execution data will be purged after 90 days.

more info (6)
aws iot list-jobs

The command lists all jobs in your account sorted by the job status:

{ "jobs": [ { "status": "IN_PROGRESS", "lastUpdatedAt": 1486687079.743, "jobArn": "arn:aws:iot:us-east-1:123456789012:job/013", "createdAt": 1486687079.743, "targetSelection": "SNAPSHOT", "jobId": "013" }, { "status": "COMPLETED", "lastUpdatedAt": 1486685868.444, "jobArn": "arn:aws:iot:us-east-1:123456789012:job/012", "createdAt": 1486685868.444, "completedAt": 148668789.690, "targetSelection": "SNAPSHOT", "jobId": "012" }, { "status": "CANCELED", "lastUpdatedAt": 1486678850.575, "jobArn": "arn:aws:iot:us-east-1:123456789012:job/011", "createdAt": 1486678850.575, "targetSelection": "SNAPSHOT", "jobId": "011" } ] }

Describe a Job

DescribeJobmore info (7)
DescribeJob

You use the DescribeJob command to get the status of a specific job.

more info (7)
$ aws iot describe-job --job-id 010

The command returns the status of the specified job. For example:

{ "documentSource": "https://s3.amazonaws.com/job-test-bucket/job-document.json", "job": { "status": "IN_PROGRESS", "jobArn": "arn:aws:iot:us-east-1:123456789012:job/010", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/myThing" ], "jobProcessDetails": { "numberOfCanceledThings": 0, "numberOfFailedThings": 0, "numberOfInProgressThings": 0, "numberOfQueuedThings": 0, "numberOfRejectedThings": 0, "numberOfRemovedThings": 0, "numberOfSucceededThings": 0, "processingTargets": [ arn:aws:iot:us-east-1:123456789012:thing/thingOne, arn:aws:iot:us-east-1:123456789012:thinggroup/thinggroupOne, arn:aws:iot:us-east-1:123456789012:thing/thingTwo, arn:aws:iot:us-east-1:123456789012:thinggroup/thinggroupTwo ] }, "presignedUrlConfig": { "expiresInSec": 60, "roleArn": "arn:aws:iam::123456789012:role/S3DownloadRole" }, "jobId": "010", "lastUpdatedAt": 1486593195.006, "createdAt": 1486593195.006, "targetSelection": "SNAPSHOT" } }

List Executions for a Job

ListJobExecutionsForJobmore info (8)
ListJobExecutionsForJob

A job running on a specific device is represented by a job execution object. You use the ListJobExecutionsForJob command to list all job executions for a job.

more info (8)
aws iot list-job-executions-for-job --job-id 010

The command returns a list of job executions:

{ "executionSummaries": [ { "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingOne", "jobExecutionSummary": { "status": "QUEUED", "lastUpdatedAt": 1486593196.378, "queuedAt": 1486593196.378, "executionNumber": 1234567890 } }, { "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingTwo", "jobExecutionSummary": { "status": "IN_PROGRESS", "lastUpdatedAt": 1486593345.659, "queuedAt": 1486593196.378, "startedAt": 1486593345.659, "executionNumber": 4567890123 } } ] }

List Job Executions for a Thing

ListJobExecutionsForThingmore info (9)
ListJobExecutionsForThing

You use the ListJobExecutionsForThing command to list all job executions running on a thing.

more info (9)
aws iot list-job-executions-for-thing --thing-name thingOne

The command returns a list of job executions that are running or have run on the specified thing:

{ "executionSummaries": [ { "jobExecutionSummary": { "status": "QUEUED", "lastUpdatedAt": 1486687082.071, "queuedAt": 1486687082.071, "executionNumber": 9876543210 }, "jobId": "013" }, { "jobExecutionSummary": { "status": "IN_PROCESS", "startAt": 1486685870.729, "lastUpdatedAt": 1486685870.729, "queuedAt": 1486685870.729, "executionNumber": 1357924680 }, "jobId": "012" }, { "jobExecutionSummary": { "status": "COMPLETED", "startAt": 1486678853.415, "lastUpdatedAt": 1486678853.415, "queuedAt": 1486678853.415, "executionNumber": 4357680912 }, "jobId": "011" }, { "jobExecutionSummary": { "status": "CANCELED", "startAt": 1486593196.378, "lastUpdatedAt": 1486593196.378, "queuedAt": 1486593196.378, "executionNumber": 2143174250 }, "jobId": "010" } ] }

Describe Job Execution

DescribeJobExecutionmore info (10)
DescribeJobExecution

You use the DescribeJobExecution command to get the status of a specific job execution. You specify a job ID and thing name (and, optionally, an execution number) to identify the job execution.

The job's execution status must be QUEUED or IN_PROGRESS.

more info (10)
aws iot describe-job-execution --job-id 017 --thing-name thingOne

The command returns the JobExecution. For example:

{ "execution": { "jobId": "017", "executionNumber": 4516820379, "thingArn": "arn:aws:iot:us-east-1:123456789012:thing/thingOne", "versionNumber": 123, "createdAt": 1489084805.285, "lastUpdatedAt": 1489086279.937, "startedAt": 1489086279.937, "status": "IN_PROGRESS", "statusDetails": { "status": "IN_PROGRESS", "detailsMap": { "percentComplete": "10" } } } }

Delete Job Execution

DeleteJobExecutionmore info (11)
DeleteJobExecution

You use the DeleteJobExecution command to delete a specific job execution. You must specify a job ID and a thing name and, optionally, an execution number to identify the job execution.

more info (11)
aws iot delete-job-execution --job-id 017 --thing-name thingOne --execution-number 1234567890 --force|--no-force

The command displays no output.

By default, the job execution must be "QUEUED" or in a terminal state (SUCCEEDED, FAILED, REJECTED, REMOVED or CANCELED) or an error will occur. Otherwise, you can set the force parameter to true to delete a job execution IN_PROGRESS.

Warning

Deleting a job execution which is "IN_PROGRESS", will cause the device which is executing the job to be unable to access job information or update the job execution status. Use caution and ensure that the device is able to recover to a valid state.

Jobs Events

AWS IoT Jobs publishes MQTT messages to reserved topics when jobs are completed, canceled, or deleted, and when a device reports success or failure when executing a job.

Because job cancellation and deletion may take some time, two messages are sent to indicate the start and end of a request. For example, when a cancellation request starts, a message is sent to the $aws/events/job/jobID/cancellation_in_progress topic; and when the cancellation request completes, a message is sent to the $aws/events/job/jobID/canceled topic. A similar process occurs for a job deletion request. Management and monitoring applications can keep track of the status of jobs by subscribing to these topics.

For more information about publishing and subscribing to MQTT topics, see Message Broker for AWS IoT

job completed/canceled/deleted/cancellation_in_progress/deletion_in_progressmore info (12)
job completed/canceled/deleted/cancellation_in_progress/deletion_in_progress

AWS IoT Jobs publishes a message on an MQTT topic when a job is completed, canceled, and deleted:

  • $aws/events/job/jobID/completed

  • $aws/events/job/jobID/canceled

  • $aws/events/job/jobID/deleted

  • $aws/events/job/jobID/cancellation_in_progress

  • $aws/events/job/jobID/deletion_in_progress

more info (12)

The "completed" message contains the following example payload:

{ "eventType": "JOB", "eventId": "7364ffd1-8b65-4824-85d5-6c14686c97c6", "timestamp": 1234567890, "operation": "completed", "jobId": "27450507-bf6f-4012-92af-bb8a1c8c4484", "status": "COMPLETED", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/a39f6f91-70cf-4bd2-a381-9c66df1a80d0", "arn:aws:iot:us-east-1:123456789012:thinggroup/2fc4c0a4-6e45-4525-a238-0fe8d3dd21bb" ], "description": "My Job Description", "completedAt": 1234567890123, "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "comment": "Comment for this operation", "jobProcessDetails": { "numberOfCanceledThings": 0, "numberOfRejectedThings": 0, "numberOfFailedThings": 0, "numberOfRemovedThings": 0, "numberOfSucceededThings": 3 } }

The "canceled" message contains the following example payload:

{ "eventType": "JOB", "eventId": "568d2ade-2e9c-46e6-a115-18afa1286b06", "timestamp": 1234567890, "operation": "canceled", "jobId": "4d2a531a-da2e-47bb-8b9e-ff5adcd53ef0", "status": "CANCELED", "forceCanceled": true, "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/Thing0-947b9c0c-ff10-4a80-b4b3-cd33d0145a0f", "arn:aws:iot:us-east-1:123456789012:thinggroup/ThingGroup1-95c644d5-1621-41a6-9aa5-ad2de581d18f" ], "description": "My job description", "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "comment": "Comment for this operation", "jobProcessDetails": { "numberOfCanceledThings": 0, "numberOfRejectedThings": 0, "numberOfFailedThings": 0, "numberOfRemovedThings": 0, "numberOfSucceededThings": 3 } }

The "deleted" message contains the following example payload:

{ "eventType": "JOB", "eventId": "568d2ade-2e9c-46e6-a115-18afa1286b06", "timestamp": 1234567890, "operation": "deleted", "jobId": "4d2a531a-da2e-47bb-8b9e-ff5adcd53ef0", "status": "DELETED", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/Thing0-947b9c0c-ff10-4a80-b4b3-cd33d0145a0f", "arn:aws:iot:us-east-1:123456789012:thinggroup/ThingGroup1-95c644d5-1621-41a6-9aa5-ad2de581d18f" ], "description": "My job description", "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "comment": "Comment for this operation" }

The "cancellation_in_progress" message contains the following example payload:

{ "eventType": "JOB", "eventId": "568d2ade-2e9c-46e6-a115-18afa1286b06", "timestamp": 1234567890, "operation": "cancellation_in_progress", "jobId": "4d2a531a-da2e-47bb-8b9e-ff5adcd53ef0", "status": "CANCELLATION_IN_PROGRESS", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/Thing0-947b9c0c-ff10-4a80-b4b3-cd33d0145a0f", "arn:aws:iot:us-east-1:123456789012:thinggroup/ThingGroup1-95c644d5-1621-41a6-9aa5-ad2de581d18f" ], "description": "My job description", "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "comment": "Comment for this operation" }

The "deletion_in_progress" message contains the following example payload:

{ "eventType": "JOB", "eventId": "568d2ade-2e9c-46e6-a115-18afa1286b06", "timestamp": 1234567890, "operation": "deletion_in_progress", "jobId": "4d2a531a-da2e-47bb-8b9e-ff5adcd53ef0", "status": "DELETION_IN_PROGRESS", "targetSelection": "SNAPSHOT|CONTINUOUS", "targets": [ "arn:aws:iot:us-east-1:123456789012:thing/Thing0-947b9c0c-ff10-4a80-b4b3-cd33d0145a0f", "arn:aws:iot:us-east-1:123456789012:thinggroup/ThingGroup1-95c644d5-1621-41a6-9aa5-ad2de581d18f" ], "description": "My job description", "createdAt": 1234567890123, "lastUpdatedAt": 1234567890123, "comment": "Comment for this operation" }
job execution terminal statusmore info (13)
job execution terminal status

AWS IoT Jobs publishes a message when a device updates a job execution to terminal status:

  • $aws/events/jobExecution/jobID/succeeded

  • $aws/events/jobExecution/jobID/failed

  • $aws/events/jobExecution/jobID/rejected

  • $aws/events/jobExecution/jobID/canceled

  • $aws/events/jobExecution/jobID/removed

  • $aws/events/jobExecution/jobID/deleted

more info (13)

The message contains the following example payload:

{ "eventType": "JOB_EXECUTION", "eventId": "cca89fa5-8a7f-4ced-8c20-5e653afb3572", "timestamp": 1234567890, "operation": "succeeded|failed|rejected|canceled|removed|deleted", "jobId": "154b39e5-60b0-48a4-9b73-f6f8dd032d27", "thingArn": "arn:aws:iot:us-east-1:123456789012:myThing/6d639fbc-8f85-4a90-924d-a2867f8366a7", "status": "SUCCEEDED|FAILED|REJECTED|CANCELED|REMOVED|DELETED", "statusDetails": { "key": "value" } }

Note

When a job has been deleted, the operation field in the message will show this, but the status field will reflect what the job execution status was prior to the deletion.