# Managing jobs Use jobs to notify devices of a software or firmware update. You can use the [AWS IoT console](https://console.aws.amazon.com/iot/), the [Job management and control API operations](jobs-management-control-api.md#jobs-http-api), the [AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/reference/iot/index.html), or the [AWS SDKs](http://aws.amazon.com/tools/#sdk) to create and manage jobs. ## Code signing for jobs When sending code to devices, for devices to detect whether the code has been modified in transit, we recommend that you sign the code file by using the AWS CLI. For instructions, see [Create and manage jobs by using the AWS CLI](manage-job-cli.md). For more information, see [What Is Code Signing for AWS IoT?](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html). ## Job document Before you create a job, you must create a job document. If you're using code signing for AWS IoT, you must upload your job document to a versioned Amazon S3 bucket. For more information about creating an Amazon S3 bucket and uploading files to it, see [Getting Started with Amazon Simple Storage Service](https://docs.aws.amazon.com/AmazonS3/latest/userguide/GetStartedWithS3.html) in the *Amazon S3 Getting Started Guide*. **Tip** For job document examples, see the [jobs-agent.js](https://www.npmjs.com/package/aws-iot-device-sdk#jobs-agentjs) example in the AWS IoT SDK for JavaScript. ## Presigned URLs Your job document can contain a presigned Amazon S3 URL that points to your code file (or other file). Presigned Amazon S3 URLs are valid only for a limited amount of time and are generated when a device requests a job document. Because the presigned URL isn't created when you're creating the job document, use a placeholder URL in your job document instead. A placeholder URL looks like the following: `${aws:iot:s3-presigned-url-v2:https://s3.region.amazonaws.com//}` where: + *bucket* is the Amazon S3 bucket that contains the code file. + *code file* is the Amazon S3 key of the code file. When a device requests the job document, AWS IoT generates the presigned URL and replaces the placeholder URL with the presigned URL. Your job document is then sent to the device. **IAM role to grant permission to download files from S3** When you create a job that uses presigned Amazon S3 URLs, you must provide an IAM role. The role must grant 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. You can specify an optional timeout for the presigned URL. For more information, see [CreateJob](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html). **Grant AWS IoT Jobs permission to assume your role** 1. Go to the [Roles hub of the IAM console](https://console.aws.amazon.com/iamv2/home#/roles) and choose your role. 1. On the **Trust Relationships** tab, choose **Edit Trust Relationship** and replace the policy document with the following JSON. Choose **Update Trust Policy**. **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "", "Effect": "Allow", "Principal": { "Service": [ "iot.amazonaws.com" ] }, "Action": "sts:AssumeRole" } ] } ``` 1. To protect against the confused deputy problem, add the global condition context keys [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourcearn) and [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceaccount) to the policy. **Important** Your `aws:SourceArn` must comply with the format: `arn:aws:iot:region:account-id:*`. Make sure that *region* matches your AWS IoT Region and *account-id* matches your customer account ID. For more information, see [Cross-service confused deputy prevention](cross-service-confused-deputy-prevention.md). ``` { "Effect": "Allow", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "iot.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals": { "aws:SourceAccount": "123456789012" }, "ArnLike": { "aws:SourceArn": "arn:aws:iot:*:123456789012:job/*" } } } ] } ``` 1. If your job uses a job document that's an Amazon S3 object, choose **Permissions** and use the following JSON. This adds a policy that grants permission to download files from your Amazon S3 bucket: **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "s3:GetObject", "Resource": "arn:aws:s3:::your_S3_bucket/*" } ] } ``` ## Presigned URL for file upload If your devices need to upload files to an Amazon S3 bucket during a job deployment, then you can include the following presigned URL placeholder in your job document: ``` ${aws:iot:s3-presigned-url-upload:https://s3.region.amazonaws.com//} ``` You can use a max of two of each of `${thingName}`, `${jobId}`, and `${executionNumber}` as reserved keywords within the `key` attribute in the file upload placeholder URL located in your job document. The local placeholder representing those reserved keywords in the `key` attribute will be parsed and replaced when the job execution is created. Using a local placeholder with reserved keywords specific to each device ensures each uploaded file from a device is specific to that device and not overwritten by a similar uploaded file from another device targeted by the same job deployment. For information on troubleshooting local placeholders within a presigned URL placeholder for uploading files during a job deployment, see [General Troubleshooting Error Messages](software-package-catalog-troubleshooting.md#spc-general-troubleshooting). **Note** The Amazon S3 bucket name can't contain the local placeholder representing the reserved keywords for the uploaded file. The local placeholder must be located in the `key` attribute. This presigned URL placeholder will be converted to an Amazon S3 presigned upload URL in your job document when a device receives it. Your devices will use this to upload files to a destination Amazon S3 bucket. **Note** When the Amazon S3 bucket and key are not provided in the above placeholder URL, AWS IoT Jobs will automatically generate a key for each device using a max of two of each of `${thingName}`, `${jobId}`, and `${executionNumber}`. ## Presigned URL using Amazon S3 versioning Safeguarding the integrity of a file stored in an Amazon S3 bucket is critical for ensuring secure job deployments using that file to your device fleet. With the use of Amazon S3 versioning, you can add a version identifier for each variant of the file stored in your Amazon S3 bucket for tracking each verison of the file. This provides insight into what version of the file is deployed to your device fleet using AWS IoT Jobs. For more information on Amazon S3 buckets using versioning, see [Using versioning in Amazon S3 buckets](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Versioning.html). If the file is stored in Amazon S3 and the job document contains a presigned URL placeholder, AWS IoT Jobs will generate a presigned URL in the job document using the Amazon S3 bucket, bucket key, and version of the file stored in the Amazon S3 bucket. This presigned URL generated in the job document will replace the presigned URL placeholder originally in the job document. If you update the file stored in your Amazon S3 bucket, a new version of the file and subsequent `versionId` will be created to signal the updates made and provide the ability to target that specific file in future job deployments. Refer to the following examples for a before and during look of the Amazon S3 presigned URLs in your job document using the `versionId`: **Amazon S3 Presigned URL placeholder (Before Job Deployment)** ``` //Virtual-hosted style URL ${aws:iot:s3-presigned-url-v2:https://bucket-name.s3.region-code.amazonaws.com/key-name%3FversionId%3Dversion-id} //Path-style URL ${aws:iot:s3-presigned-url-v2:https://s3.region-code.amazonaws.com/bucket-name/key-name%3FversionId%3Dversion-id} ``` **Amazon S3 Presigned URL (During Job Deployment)** ``` //Virtual-hosted style URL ${aws:iot:s3-presigned-url-v2:https://sample-bucket-name.s3.us-west-2.amazonaws.com/sample-code-file.png%3FversionId%3Dversion1} //Path-style ${aws:iot:s3-presigned-url-v2:https://s3.us-west-2.amazonaws.com/sample-bucket-name/sample-code-file.png%3FversionId%3Dversion1} ``` For more information on Amazon S3 virtual-hosted and path-style object URLs, see [Virtual-hosted-style requests](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html#virtual-hosted-style-access) and [Path-style requests](https://docs.aws.amazon.com/AmazonS3/latest/userguide/VirtualHosting.html#path-style-access). **Note** If you want to append `versionId` to a Amazon S3 presigned URL, it must conform to URL encoding supporting AWS SDK for Java 2.x. For more information, see [Changes in parsing Amazon S3 URIs from version 1 to version 2](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/migration-s3-uri-parser.html#migration-3-uri-parser-api-changes). **Amazon S3 Presigned URL placeholder version differences** The following list outlines the differences between Amazon S3 presigned URL placeholders `${aws:iot:s3-presigned-url-v1` (version 1) and `${aws:iot:s3-presigned-url-v2` (version 2): + The Amazon S3 presigned URL placeholder `${aws:iot:s3-presigned-url-v1` does not support `version-id`. + The Amazon S3 presigned URL placeholder `${aws:iot:s3-presigned-url-v1` receives the Amazon S3 URL as unencoded. The Amazon S3 Presigned URL placeholder `${aws:iot:s3-presigned-url-v2` requires the Amazon S3 URL to be encoded to conform with the Amazon S3 SDK standard. **Topics** + [ ## Code signing for jobs ](#create-manage-jobs-code-signing) + [ ## Job document ](#create-manage-jobs-job-doc) + [ ## Presigned URLs ](#create-manage-jobs-presigned-URLs) + [ ## Presigned URL for file upload ](#create-manage-jobs-presigned-URLs-upload) + [ ## Presigned URL using Amazon S3 versioning ](#create-manage-jobs-presigned-URLs-versioning) + [ # Create and manage jobs by using the AWS Management Console ](manage-job-console.md) + [ # Create and manage jobs by using the AWS CLI ](manage-job-cli.md) # Create and manage jobs by using the AWS Management Console Create and manage jobs using the console This section describes how you can create and manage jobs from the AWS IoT console. After you've created a job, you can view information about the job on the details page, and manage the job. **Note** If you want to perform code signing for AWS IoT jobs, use the AWS CLI. For more information, see [Create and manage jobs by using the AWS CLI](manage-job-cli.md). **Topics** + [ ## Create manage jobs by using the AWS Management Console ](#create-job-console) + [ ## View and manage jobs by using the AWS Management Console ](#view-manage-job-console) ## Create manage jobs by using the AWS Management Console Create jobs (console) To create a job, log in to the AWS IoT console, and go to the [Jobs hub](https://console.aws.amazon.com/iot/home#/jobhub) in the **Remote Actions** section. Then, perform the following steps. 1. On the **Jobs** page, in the **Jobs** dialog box, choose **Create job**. 1. Depending on the device that you're using, you can create a custom job, a FreeRTOS OTA update job, or an AWS IoT Greengrass job. For this example, choose **Create a custom job**. Choose **Next**. 1. On the **Custom job properties** page, in the **Job properties** dialog box, enter your information for the following fields: + **Name**: Enter a unique, alphanumeric job name. + **Description - optional**: Enter an optional description about your Job. + **Tags - optional**: **Note** We recommend that you don't use personally identifiable information in your job IDs and description. Choose **Next**. 1. On the **File configuration** page in the **Job targets** dialog box, select the **Things** or **Thing groups** that you want to run this job. In the **Job document** dialog box, select one of the following options: + **From file**: A JSON job file you previously uploaded to an Amazon S3 bucket + **Code signing** In the job document located in your Amazon S3 URL, `${aws:iot:code-sign-signature:s3://region.bucket/code-file@code-file-version-id}` is required as a placeholder until it is replaced with the signed code file path using your **Code signing profile**. The new signed code file will initially appear in a `SignedImages` folder in your Amazon S3 source bucket. A new job document containing a `Codesigned_` prefix will be created with the signed code file path replacing the code-sign placeholder and placed in your Amazon S3 URL for creating a new job. + **Pre-sign resource URLs** In the **Pre-signing role** drop down, choose the IAM role you created in [Presigned URLs](https://docs.aws.amazon.com/iot/latest/developerguide/create-manage-jobs.html#create-manage-jobs-presigned-URLs). Using `${aws:iot:s3-presigned-url:` to presign URLs for objects located in Amazon S3 is a best security practice for devices downloading objects from Amazon S3. If you want to use presigned URLs for a code signing placeholder, use the following example template: ``` ${aws:iot:s3-presigned-url:${aws:iot:code-sign-signature:} ``` + **From template**: A job template containing a job document and job configurations. The job template can be a custom job template you created or an AWS managed template. If you're creating a job for performing frequently used remote actions such as rebooting your device, you can use an AWS managed template. These templates have already been preconfigured for use. For more information, see [Create a custom job template](job-templates-console.md#job-templates-console-create) and [Create custom job templates from managed templates](job-template-manage-console-create.md#job-template-manage-create-template). 1. On the **Job configuration** page in the **Job configuration** dialog box, select one of the following job types: + **Snapshot job**: A snapshot job is complete when it's finished its run on the target devices and groups. + **Continuous job**: A continuous job applies to thing groups and runs on any device that you later add to a specified target group. 1. In the **Additional configurations - optional** dialog box, review the following optional Job configurations and make your selections accordingly: + **Rollout configuration** + **Scheduling configuration** + **Job executions timeout configuration** + **Job executions retry configuration - new** + **Abort configuration** Refer to the following sections for additional information on Job configurations: + [Job rollout, scheduling, and abort configurations](jobs-configurations-details.md#job-rollout-abort-scheduling) + [Job execution timeout and retry configurations](jobs-configurations-details.md#job-timeout-retry) Review all of your job selections and then choose **Submit** to create your job. ## View and manage jobs by using the AWS Management Console View and manage jobs (console) After you create the job, the console generates a JSON signature and places it in your job document. You can use the [AWS IoT console](https://console.aws.amazon.com/iot/) to view the status, cancel, or delete a job. If you choose the job that you created, you can find: + General job details, such as the job name, description, type, the time when it was created, last updated, and the estimated start time. + Any job configurations that you specified and their status. + The job document. + The job executions and any optional tags that you specified. To manage jobs, go to the [Job hub of the console](https://console.aws.amazon.com/iot/home#/jobhub) and choose whether you want to edit, delete, or cancel the job. # Create and manage jobs by using the AWS CLI Create and manage jobs using the CLI This section describes how to create and manage jobs. ## Create jobs To create an AWS IoT job, use the **CreateJob** command. The job is queued for execution on the targets (things or thing groups) that you specify. To create an AWS IoT 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 Amazon Resource Name (ARN) that has permission to download the file and grants permission to the AWS IoT Jobs service to assume the role. For more information on the syntax when entering the date and time using an API command or the AWS CLI, see [Timestamp](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-types.html#parameter-type-timestamp). ### Code signing with jobs If you're using code signing for AWS IoT, you must start a code signing job and include the output in your job document. This will replace the code sign signature placeholder in your job document, which is required as a placeholder until it is replaced with the signed code file path using your **Code signing profile**. The code sign signature placeholder will look like the following: ``` ${aws:iot:code-sign-signature:s3://region.bucket/code-file@code-file-version-id} ``` Use the [start-signing-job](https://docs.aws.amazon.com/signer/latest/developerguide/api-startsigningjob.html) command to create a code signing job. `start-signing-job` returns a job ID. To get the Amazon S3 location where the signature is stored, use the **describe-signing-job** command. You can then download the signature from Amazon S3. For more information about code signing jobs, see [Code signing for AWS IoT](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html). Your job document must contain a presigned URL placeholder for your code file and the JSON signature output placed in an Amazon S3 bucket using the **start-signing-job** command: ``` { "presign": "${aws:iot:s3-presigned-url:https://s3.region.amazonaws.com/bucket/image}", } ``` ### Create a job with a job document The following command shows how to create a job using a job document (*job-document.json*) stored in an Amazon S3 bucket (*jobBucket*), and a role with permission to download files from Amazon S3 (*S3DownloadRole*). ``` aws iot create-job \ --job-id 010 \ --targets arn:aws:iot:us-east-1:123456789012:thing/thingOne \ --document-source https://s3.amazonaws.com/amzn-s3-demo-bucket/job-document.json \ --timeout-config inProgressTimeoutInMinutes=100 \ --job-executions-rollout-config "{ \"exponentialRate\": { \"baseRatePerMinute\": 50, \"incrementFactor\": 2, \"rateIncreaseCriteria\": { \"numberOfNotifiedThings\": 1000, \"numberOfSucceededThings\": 1000}}, \"maximumPerMinute\": 1000}" \ --abort-config "{ \"criteriaList\": [ { \"action\": \"CANCEL\", \"failureType\": \"FAILED\", \"minNumberOfExecutedThings\": 100, \"thresholdPercentage\": 20}, { \"action\": \"CANCEL\", \"failureType\": \"TIMED_OUT\", \"minNumberOfExecutedThings\": 200, \"thresholdPercentage\": 50}]}" \ --presigned-url-config "{\"roleArn\":\"arn:aws:iam::123456789012:role/S3DownloadRole\", \"expiresInSec\":3600}" ``` The job is run on *thingOne*. The optional `timeout-config` parameter specifies the amount of time each device has to finish its execution of the job. The timer starts when the job execution status is set to `IN_PROGRESS`. If the job execution status isn't set to another terminal state before the time expires, it's set to `TIMED_OUT`. The in-progress timer can't be updated and applies to all job executions for the job. Whenever a job execution remains in the `IN_PROGRESS` state for longer than this interval, it fails and switches to the terminal `TIMED_OUT` status. AWS IoT also publishes an MQTT notification. For more information about creating configurations for job rollouts and aborts, see [Job Rollout and Abort Configuration](job-rollout-abort.html). **Note** Job documents that are specified as Amazon S3 files are retrieved at the time you create the job. If you change the contents of the Amazon S3 file that you used as the source of your job document after you've created the job document, then what's sent to the job targets doesn't change. ## Update a job To update a job, use the **UpdateJob** command. You can update the `description`, `presignedUrlConfig`, `jobExecutionsRolloutConfig`, `abortConfig`, and `timeoutConfig` fields of a job. ``` aws iot update-job \ --job-id 010 \ --description "updated description" \ --timeout-config inProgressTimeoutInMinutes=100 \ --job-executions-rollout-config "{ \"exponentialRate\": { \"baseRatePerMinute\": 50, \"incrementFactor\": 2, \"rateIncreaseCriteria\": { \"numberOfNotifiedThings\": 1000, \"numberOfSucceededThings\": 1000}, \"maximumPerMinute\": 1000}}" \ --abort-config "{ \"criteriaList\": [ { \"action\": \"CANCEL\", \"failureType\": \"FAILED\", \"minNumberOfExecutedThings\": 100, \"thresholdPercentage\": 20}, { \"action\": \"CANCEL\", \"failureType\": \"TIMED_OUT\", \"minNumberOfExecutedThings\": 200, \"thresholdPercentage\": 50}]}" \ --presigned-url-config "{\"roleArn\":\"arn:aws:iam::123456789012:role/S3DownloadRole\", \"expiresInSec\":3600}" ``` For more information, see [Job Rollout and Abort Configuration](job-rollout-abort.html). ## Cancel a job To cancel a job, use the **CancelJob** command. Canceling a job stops AWS IoT from rolling out any new job executions for the job. It also cancels any job executions that are in a `QUEUED` state. AWS IoT keeps any job executions in a terminal state untouched because the device has already completed the job. If the status of a job execution is `IN_PROGRESS`, it also remains untouched unless you use the optional `--force` parameter. The following command shows how to cancel a job with ID 010. ``` aws iot cancel-job --job-id 010 ``` The command displays the following output: ``` { "jobArn": "string", "jobId": "string", "description": "string" } ``` When you cancel a job, job executions that are in a `QUEUED` state are canceled. Job executions that are in an `IN_PROGRESS` state are canceled, but only if you specify the optional `--force` parameter. Job executions in a terminal state aren't canceled. **Warning** Canceling a job that's in the `IN_PROGRESS` state (by setting the `--force` parameter) cancels any job executions that are in progress and causes the device that's running the job to be unable to update the job execution status. Use caution and make sure that each device executing a canceled job can recover to a valid state. The status of a canceled job or of one of its job executions is eventually consistent. AWS IoT stops scheduling new job executions and `QUEUED` job executions for that job to devices as soon as possible. Changing the status of a job execution to `CANCELED` might take some time, depending on the number of devices and other factors. If a job is canceled because it's met the criteria defined by an `AbortConfig` object, the service adds auto-populated values for the `comment` and `reasonCode` fields. You can create your own values for `reasonCode` when the job cancellation is user-driven. ## Cancel a job execution To cancel a job execution on a device, use the **CancelJobExecution** command. It cancels a job execution that's in a `QUEUED` state. If you want to cancel a job execution that's in progress, you must use the `--force` parameter. The following command shows how to cancel the job execution from job 010 running on `myThing`. ``` aws iot cancel-job-execution --job-id 010 --thing-name myThing ``` The command displays no output. A job execution that's in a `QUEUED` state is canceled. A job execution that's in an `IN_PROGRESS` state is canceled, but only if you specify the optional `--force` parameter. Job executions in a terminal state can't be canceled. **Warning** When you cancel a job execution that's in the `IN_PROGRESS` state, the device can't update the job execution status. Use caution and make sure that the device can recover to a valid state. If the job execution is in a terminal state, or if the job execution is in an `IN_PROGRESS` state and the `--force` parameter isn't set to `true`, this command causes an `InvalidStateTransitionException`. The status of a canceled job execution is eventually consistent. Changing the status of a job execution to `CANCELED` might take some time, depending on various factors. ## Delete a job To delete a job and its job executions, use the **DeleteJob** command. By default, you can only delete a job that's in a terminal state (`SUCCEEDED` or `CANCELED`). Otherwise, an exception occurs. You can delete a job in the `IN_PROGRESS` state, however, only if the `force` parameter is set to `true`. To delete a job, run the following command: ``` aws iot delete-job --job-id 010 --force|--no-force ``` The command displays no output. **Warning** When you delete a job that's in the `IN_PROGRESS` state, the device that's deploying the job can't access job information or update the job execution status. Use caution and make sure that each device deploying a job that's been deleted can recover to a valid state. It can take some time to delete a job, depending on the number of job executions created for the job and other factors. While the job is being deleted, `DELETION_IN_PROGRESS` appears as the status of the job. An error results if you attempt to delete or cancel a job with a status that's already `DELETION_IN_PROGRESS`. Only 10 jobs can have a status of `DELETION_IN_PROGRESS` at the same time. Otherwise, a `LimitExceededException` occurs. ## Get a job document To retrieve a job document for a job, use the **GetJobDocument** command. A job document is a description of the remote operations to be performed by the devices. To get a job document, run the following command: ``` 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/amzn-s3-demo-bucket/datafile}\"\n}" } ``` **Note** When you use this command to retrieve a job document, placeholder URLs aren't replaced by presigned Amazon S3 URLs. When a device calls the [GetPendingJobExecutions](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html) API operation, the placeholder URLs are replaced by presigned Amazon S3 URLs in the job document. ## List jobs To get a list of all jobs in your AWS account, use the **ListJobs** command. Job data and job execution data are retained for a [limited time](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#job-limits). Run the following command to list all jobs in your AWS account: ``` aws iot list-jobs ``` The command returns 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": "SUCCEEDED", "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 To get the status of a job, run the **DescribeJob** command. The following command shows how to describe a job: ``` $ aws iot describe-job --job-id 010 ``` The command returns the status of the specified job. For example: ``` { "documentSource": "https://s3.amazonaws.com/amzn-s3-demo-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, "numberOfTimedOutThings": 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", "jobExecutionsRolloutConfig": { "exponentialRate": { "baseRatePerMinute": integer, "incrementFactor": integer, "rateIncreaseCriteria": { "numberOfNotifiedThings": integer, // Set one or the other "numberOfSucceededThings": integer // of these two values. }, "maximumPerMinute": integer } }, "abortConfig": { "criteriaList": [ { "action": "string", "failureType": "string", "minNumberOfExecutedThings": integer, "thresholdPercentage": integer } ] }, "timeoutConfig": { "inProgressTimeoutInMinutes": number } } } ``` ## List executions for a job A job running on a specific device is represented by a job execution object. Run the **ListJobExecutionsForJob** command to list all job executions for a job. The following shows how to list the executions for a job: ``` 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 Run the **ListJobExecutionsForThing** command to list all job executions running on a thing. The following shows how to list job executions for a thing: ``` 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_PROGRESS", "startAt": 1486685870.729, "lastUpdatedAt": 1486685870.729, "queuedAt": 1486685870.729, "executionNumber": 1357924680 }, "jobId": "012" }, { "jobExecutionSummary": { "status": "SUCCEEDED", "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 Run the **DescribeJobExecution** command to get the status of a job execution. You must specify a job ID and thing name and, optionally, an execution number to identify the job execution. The following shows how to describe a job execution: ``` aws iot describe-job-execution --job-id 017 --thing-name thingOne ``` The command returns the [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html). 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", "approximateSecondsBeforeTimedOut": 100, "statusDetails": { "status": "IN_PROGRESS", "detailsMap": { "percentComplete": "10" } } } } ``` ## Delete job execution Run the **DeleteJobExecution** command to delete a job execution. You must specify a job ID, a thing name, and an execution number to identify the job execution. The following shows how to delete a job execution: ``` 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 status of the job execution must be `QUEUED` or in a terminal state (`SUCCEEDED`, `FAILED`, `REJECTED`, `TIMED_OUT`, `REMOVED`, or `CANCELED`). Otherwise, an error occurs. To delete a job execution with a status of `IN_PROGRESS`, you can set the `force` parameter to `true`. **Warning** When you delete a job execution with a status of `IN_PROGRESS`, the device that's executing the job can't access job information or update the job execution status. Use caution and make sure that the device can recover to a valid state.