# AWS IoT Jobs
Jobs
Use AWS IoT Jobs to define a set of remote operations that can be sent to and run on one or more devices connected to AWS IoT. For example, you can define a job that instructs a set of devices to download and install applications, run firmware updates, reboot, rotate certificates, or perform remote troubleshooting operations.
## Accessing AWS IoT jobs
You can get started with AWS IoT Jobs by using the console or the AWS IoT Core API.
**Using the console**
Sign in to the AWS Management Console, and go to the AWS IoT console. In the navigation pane, choose **Manage**, and then choose **Jobs**. You can create and manage jobs from this section. If you want to create and manage job templates, in the navigation pane, choose **Job templates**. For more information, see [Create and manage jobs by using the AWS Management Console](manage-job-console.md).
**Using the API or CLI**
You can get started by using the AWS IoT Core API operations. For more information, see [AWS IoT API Reference](https://docs.aws.amazon.com/iot/latest/apireference/). The AWS IoT Core API that AWS IoT jobs is built on is supported by the AWS SDK. For more information, see [AWS SDKs and Toolkits](https://aws.amazon.com/getting-started/tools-sdks/).
You can use the AWS CLI to run commands for creating and managing jobs and job templates. For more information, see [AWS IoT CLI reference](https://docs.aws.amazon.com/cli/latest/reference/iot/index.html).
## AWS IoT Jobs Regions and endpoints
AWS IoT Jobs supports control plane and data plane API endpoints that are specific to your AWS Region. The data plane API endpoints are specific to your AWS account and AWS Region. For more information about the AWS IoT Jobs endpoints, see [AWS IoT Device Management - jobs data endpoints](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#iot_device_management_region_jobs) in the *AWS General Reference*.
# What is a remote operation?
**Note**
Over-the-air (OTA) updates are not available in the following regions:
Europe (Spain)
Asia Pacific (Malaysia)
A remote operation is any update or action you can perform on a physical device, virtual device, or endpoint that can be done remotely without the need for the physical presence of an operator or technician. The remote operation is performed using an over-the-air (OTA) update so your devices don't have to be physically present. Managing your device fleet in the AWS Cloud allows you to perform remote operations on your devices when they are registered with AWS IoT Core.
AWS IoT Device Management Jobs offers a scalable approach for performing remote actions on your devices registered with AWS IoT Core. A job is created in the AWS Cloud and pushed out to all targeted devices using an OTA update via the MQTT or HTTP protocol.
AWS IoT Device Management Jobs provide you the capability to perform remote operations such as factory resets, device reboots, and software OTA updates in a secure, scalable, and more cost-effective way.
For more information on AWS IoT Core, see [What is AWS IoT?](what-is-aws-iot.md).
For more information on AWS IoT Device Management Jobs, see [What is AWS IoT Jobs?](jobs-what-is.md).
## Benefits of using AWS IoT Device Management Jobs for remote operations
Using AWS IoT Device Management Jobs to perform your remote operations streamlines the management of your device fleet. The following list highlights some of the key benefits for using AWS IoT Device Management Jobs to perform your remote operations:
+ **Seamless integration with other AWS services**
+ AWS IoT Device Management Jobs integrates closely with the following value-added AWS services and features:
+ **Amazon S3**: Store your remote operation instructions in a secure Amazon S3 bucket where you control the access permissions for that content. Using an Amazon S3 bucket provides a scalable and durable storage solution that natively intergrates with AWS IoT Device Management Software Package Catalog allowing AWS IoT Device Management Jobs to reference and substitute in update instructions. For more information, see [What is Amazon S3?](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html).
+ **Amazon CloudWatch**: Monitor and log the remote operation implementation status of the job execution for each device in addition to other device activity to track and analyze the overall job performance in AWS IoT Device Management Jobs. For more information, see [What is Amazon CloudWatch?](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/WhatIsCloudWatch.html) Monitoring jobs logs and capturing historical data for troubleshooting. How it works with jobs.
+ **AWS IoT Device Shadow service**: Maintain a digital representation of your AWS IoT thing via a device shadow using AWS IoT Device Management Jobs so your device's state is available to applications and other services regardless of device connectivity. For more information, see [AWS IoT Device Shadow service](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html).
+ **Security best practices**
+ **Permission control**: Control the access permissions to your remote operating instructions using Amazon S3 and determine which IAM users can deploy your remote operating instructions to your device fleet using AWS IoT policies and IAM user roles.
+ For more information on AWS IoT policies, see [Create an AWS IoT policy](create-iot-resources.md#create-iot-policy).
+ For more information on IAM user roles, see [Identity and access management for AWS IoT](security-iam.md).
+ **Scalability**
+ **Targeted job deployment**: Control which devices receive the job document from a job with a targeted job deployment using specific device grouping criteria entered in your job document when creating the job. Creating an AWS IoT thing for each device and storing that information in the AWS IoT registry allows you to perform targeted searches using fleet indexing. You can create custom groups based on the fleet indexing search results to support your target job deployment. For more information, see [Managing devices with AWS IoT](iot-thing-management.md). Use jobs to do snapshot vs continuous jobs.
+ **Job status**: Track the status of the job document rollout to your device fleet and overall job status from a device fleet level in addition to the individual implementation status of the job document on each device. For more information, see [Jobs and job execution states](iot-jobs-lifecycle.md).
+ **New device scalability**: Easily deploy your job document to a new device by adding it to an existing, custom group created using fleet indexing via a continuous job. This will save you time over having to deploy the job document to each new device separately. Or, you can use a more targeted approach with a snapshot shot by deploying a job document to a predetermined group of devices once and then the job is completed.
+ **Flexibility**
+ **Job configurations**: Customize your job and job document with the optional job configurations rollout, scheduling, abort, timeout, and retry to meet your specific needs. For more information, see [Job configurations](jobs-configurations.md).
+ **Cost effective**
+ Introduce a more efficient cost structure for maintaining your device fleet by leveraging AWS IoT Device Management Jobs to deploy critical updates and perform routine maintenance tasks. A do-it-yourself (DIY) solution to maintain your device fleet includes recurring, variable costs such as infrastructure required to host and manage the DIY solution, labor costs to develop, maintain, and scale the DIY solution, and data transmission costs. Leveraging the transparent, fixed cost structure of AWS IoT Device Management Jobs, you know exactly what each job execution for a device will cost in addition to the data transmission costs required to facilitate the job document rollout to your device fleet and tracking the job execution status for each device. For more information, see [AWS IoT Core pricing](https://docs.aws.amazon.com/iot/latest/developerguide/iot-price.html).
# What is AWS IoT Jobs?
Use AWS IoT Jobs to define a set of remote operations that can be sent to and run on one or more devices connected to AWS IoT.
To create jobs, first define a *job document* that contains a list of instructions describing operations that the device must perform remotely. To perform these operations, specify a list of *targets*, which are individual things, [thing groups](thing-groups.md), or both. The job document and targets together constitute a *deployment*.
Each deployment can have additional configurations:
+ **Rollout**: This configuration defines how many devices receive the job document every minute.
+ **Abort**: If a certain number of devices don't receive the job notification, use this configuration to cancel the job. This avoids sending a bad update to an entire fleet.
+ **Timeout**: If a response isn't received from your job targets within a certain duration, the job can fail. You can track the job that's running on these devices.
+ **Retry**: If a device reports failure or a job times out, you can use AWS IoT Jobs to resend the job document to the device automatically.
+ **Scheduling**: This configuration enables you to schedule a job for a future date and time. It also enables you to create recurring maintenance windows that update devices during predefined, low-traffic periods.
AWS IoT Jobs sends a message to inform the targets that a job is available. The target starts the *execution* of the job by downloading the job document, performing the operations it specifies, and reporting its progress to AWS IoT. You can track the progress of a job for a specific target or for all targets by running commands that are provided by AWS IoT Jobs. When a job starts, it has a status of *In progress*. The devices then report incremental updates while displaying this status until the job succeeds, fails, or times out.
The following topics describe some key concepts of jobs and the lifecycle of jobs and job executions.
**Topics**
+ [
# Jobs key concepts
](key-concepts-jobs.md)
+ [
# Jobs and job execution states
](iot-jobs-lifecycle.md)
# Jobs key concepts
The following concepts provide details about AWS IoT Jobs and how to create and deploy jobs to run remote operations on your devices.
## Basic concepts
The following are basic concepts you must know when using AWS IoT Jobs.
**Job**
A job is a remote operation that is sent to and run on one or more devices connected to AWS IoT. For example, you can define a job that instructs a set of devices to download and install an application or run firmware updates, reboot, rotate certificates, or perform remote troubleshooting operations.
**Job document**
To create a job, you must first create a job document that is a description of the remote operations to be performed by the devices.
Job documents are UTF-8 encoded JSON documents and contain information that your devices require to perform a job. A job document contains one or more URLs where the device can download an update or other data. The job document can be stored in an Amazon S3 bucket, or be included inline with the command that creates the job.
In MQTT responses, the `jobDocument` field is a JSON object. In HTTP responses, it's a string representation of the JSON object.
**Target**
When you create a job, you specify a list of targets that are the devices that should perform the operations. The targets can be things or [thing groups](thing-groups.md) or both. The AWS IoT Jobs service sends a message to each target to inform it that a job is available.
**Deployment**
After you create a job by providing the job document and specifying your list of targets, the job document is then deployed to the remote target devices for which you want to perform the update. For snapshot jobs, the job will complete after deploying to the target devices. For continuous jobs, a job is deployed to a group of devices as they are added to the groups.
**Job execution**
A job execution is an instance of a job on a target device. The target starts an execution of a job by downloading the job document. It then performs the operations specified in the document, and reports its progress to AWS IoT. An execution number is a unique identifier of a job execution on a specific target. The AWS IoT Jobs service provides commands to track the progress of a job execution on a target and the progress of a job across all targets.
## Job types concepts
The following concepts can help you understand more about the different types of jobs that you can create with AWS IoT Jobs.
**Snapshot job**
By default, a job is sent to all targets that you specify when you create the job. After those targets complete the job (or report that they're unable to do so), the job is complete.
**Continuous job**
A continuous job is sent to all targets that you specify when you create the job. It continues to run and is sent to any new devices (things) that are added to the target group. For example, a continuous job can be used to onboard or upgrade devices as they're added to a group. You can make a job continuous by setting an optional parameter when you create the job.
When targeting your IoT fleet using dynamic thing groups, we recommend that you use continuous jobs instead of snapshot jobs. By using continuous jobs, devices that join the group receive the job execution even after the job has been created.
## Presigned URLs
For secure, time-limited access to data that's not included in the job document, you can use presigned Amazon S3 URLs. Place your data in an Amazon S3 bucket and add a placeholder link to the data in the job document. When AWS IoT Jobs receives a request for the job document, it parses the job document by looking for the placeholder links, and then replaces the links with presigned Amazon S3 URLs.
The placeholder link is in the following format:
```
${aws:iot:s3-presigned-url:https://s3.amazonaws.com/bucket/key}
```
where *bucket* is your bucket name and *key* is the object in the bucket to which you are linking.
In the Beijing and Ningxia Regions, presigned URLs work only if the resource owner has an ICP (Internet Content Provider) license. For more information, see [Amazon Simple Storage Service](https://docs.amazonaws.cn/en_us/aws/latest/userguide/s3.html) in the *Getting Started with AWS Services in China* documentation.
## Job configuration concepts
The following concepts can help you understand how to configure jobs.
**Rollouts**
You can specify how quickly targets are notified of a pending job execution. This allows you to create a staged rollout to better manage updates, reboots, and other operations. You can create a rollout configuration by using either a static rollout rate or an exponential rollout rate. To specify the maximum number of job targets to inform per minute, use a static rollout rate.
For examples of setting rollout rates and for more information about configuring job rollouts, see [Job rollout, scheduling, and abort configurations](jobs-configurations-details.md#job-rollout-abort-scheduling).
**Scheduling**
Job scheduling enables you to schedule the rollout timeframe of a job document to all devices in the target group for continuous and snapshot jobs. Additionally, you can create an optional maintenance window containing specific dates and times that a job will rollout the job document to all devices in the target group. A maintenance window is a recurring instance with a frequency of daily, weekly, monthly, or custom dates and times selected during the initial job or job template creation. Only continuous jobs can be scheduled to perform a rollout during a maintenance window.
Jobs Scheduling is specific to your job. Individual Job Executions can't be scheduled. For more information, see [Job rollout, scheduling, and abort configurations](jobs-configurations-details.md#job-rollout-abort-scheduling).
**Abort**
You can create a set of conditions to cancel rollouts when criteria that you specify have been met. For more information, see [Job rollout, scheduling, and abort configurations](jobs-configurations-details.md#job-rollout-abort-scheduling).
**Timeouts**
Job timeouts notify you whenever a job deployment gets stuck in the `IN_PROGRESS` state for an unexpectedly long period of time. There are two types of timers: in-progress timers and step timers. When the job is `IN_PROGRESS`, you can monitor and track the progress of your job deployment.
Rollouts and abort configurations are specific to your job, whereas the timeout configuration is specific to a job deployment. For more information, see [Job execution timeout and retry configurations](jobs-configurations-details.md#job-timeout-retry).
**Retries**
Job retries make it possible to retry the job execution when a job fails, times out, or both. You can have up to 10 attempted retries to execute the job. You can monitor and track the progress of your retry attempt and whether the job execution succeeded.
Rollouts and abort configurations are specific to your job, whereas the timeout and retry configurations are specific to a job execution. For more information, see [Job execution timeout and retry configurations](jobs-configurations-details.md#job-timeout-retry).
# Jobs and job execution states
The following sections describe the lifecycle of an AWS IoT job and the lifecycle of a job execution.
## Job states
The following diagram shows the different states of an AWS IoT job.
![\[Image showing the different states of an AWS IoT job.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/job-states-diagram.png)
A job that you create using AWS IoT Jobs can be in one of the following states:
+
**SCHEDULED**
During the initial job or job template creation using the AWS IoT console, [CreateJob](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) API, or [CreateJobTemplate](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) API, you can select the optional scheduling configuration in the AWS IoT console or the `SchedulingConfig` in the [CreateJob](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) API or [CreateJobTemplate](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) API. When you start a scheduled job containing a specific `startTime`, `endTime`, and `endBehavior`, the job status updates to `SCHEDULED`. When the job reaches your selected `startTime` or the `startTime` of the next maintenance window (if you selected job rollout during a maintenance window), the status will update from `SCHEDULED` to `IN_PROGRESS` and begin rollout of the job document to all devices in the target group.
+
**IN\$1PROGRESS**
When you create a job using the AWS IoT console or the [CreateJob](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) API, the job status updates to `IN_PROGRESS`. During job creation, AWS IoT Jobs starts rolling out job executions to the devices in your target group. After all the job executions have rolled out, AWS IoT Jobs waits for devices to complete the remote action.
For information about concurrency and limits that apply to in-progress jobs, see [AWS IoT Jobs limits](job-limits.md).
**Note**
When an `IN_PROGRESS` job reaches the end of the current maintenance window, the rollout of the job document will stop. The job will update to `SCHEDULED` until the `startTime` of the next maintenance window.
+
**COMPLETED**
A continuous job is handled in one of the following ways:
+ For a continuous job *without* the optional scheduling configuration selected, it's always in progress and continues to run for any new devices that are added to the target group. It will never reach a status state of `COMPLETED`.
+ For a continuous job *with* the optional scheduling configuration selected, the following is true:
+ If an `endTime` *was* provided, a continuous job will reach `COMPLETED` status when `endTime` has passed and all job executions have reached a terminal status state.
+ If an `endTime` *was not* provided in the optional scheduling configuration, the continuous job will continue to perform the job document rollout.
For a snapshot job, the job status changes to `COMPLETED` when all of its job executions enter a terminal state, such as `SUCCEEDED`, `FAILED`, `TIMED_OUT`, `REMOVED`, or `CANCELED`.
+
**CANCELED**
When you cancel a job using the AWS IoT console, the [CancelJob](https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJob.html) API, or the [Job abort configuration](jobs-configurations-details.md#job-abort-using), the job status changes to `CANCELED`. During job cancellation, AWS IoT Jobs starts canceling previously created job executions.
For information about concurrency and limits that apply to jobs that are being canceled, see [AWS IoT Jobs limits](job-limits.md).
+
**DELETION\$1IN\$1PROGRESS**
When you delete a job using the AWS IoT console or the [DeleteJob](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJob.html) API, the job status changes to `DELETION_IN_PROGRESS`. During job deletion, AWS IoT Jobs starts deleting previously created job executions. After all job executions have been deleted, the job disappears from your AWS account.
## Job execution states
The following table shows the different states of an AWS IoT job execution and whether the state change is initiated by the device or by AWS IoT Jobs.
**Job execution states and source**
| Job execution state | Initiated by device? | Initiated by AWS IoT Jobs? | Terminal status? | Can be retried? |
| --- | --- | --- | --- | --- |
| QUEUED | No | Yes | No | Not applicable |
| IN\$1PROGRESS | Yes | No | No | Not applicable |
| SUCCEEDED | Yes | No | Yes | Not applicable |
| FAILED | Yes | No | Yes | Yes |
| TIMED\$1OUT | No | Yes | Yes | Yes |
| REJECTED | Yes | No | Yes | No |
| REMOVED | No | Yes | Yes | No |
| CANCELED | No | Yes | Yes | No |
The following section describes more about the states of a job execution that's rolled out when you create a job with AWS IoT Jobs.
+
**QUEUED**
When AWS IoT Jobs rolls out a job execution for a target device, the job execution status is set to `QUEUED`. The job execution remains in the `QUEUED` state until:
+ Your device receives the job execution and invokes the Jobs API operations and reports the status as `IN_PROGRESS`.
+ You cancel the job or job execution, or when the abort criteria that you specified is met, and the status changes to `CANCELED`.
+ Your device is removed from the target group and the status changes to `REMOVED`.
![\[Image showing how a queued job execution changes state to IN_PROGRESS and how a job can get REJECTED if the device doesn't accept the job creation request.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/JE-queued-inprogress.png)
+
**IN\$1PROGRESS**
If your IoT device subscribes to the reserved [Job topics](reserved-topics.md#reserved-topics-job) `$notify` and `$notify-next`, and your device invokes either the `StartNextPendingJobExecution` API or the `UpdateJobExecution` API with a status of `IN_PROGRESS`, AWS IoT Jobs will set the job execution status to `IN_PROGRESS`.
The `UpdateJobExecution` API can be invoked multiple times with a status of `IN_PROGRESS`. You can specify additional details about the execution steps using the `statusDetails` object.
**Note**
If you create multiple jobs for each device, AWS IoT Jobs and the MQTT protocol don't guarantee order of delivery.
+
**SUCCEEDED**
When your device successfully completes the remote operation, the device must invoke the `UpdateJobExecution` API with a status of `SUCCEEDED` to indicate that the job execution succeeded. AWS IoT Jobs then updates and returns the job execution status as `SUCCEEDED`.
![\[Image showing how an in-progress job execution can fail and how to retry the execution.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/JE-success-path.png)
+
**FAILED**
When your device fails to complete the remote operation, the device must invoke the `UpdateJobExecution` API with a status of `Failed` to indicate that the job execution failed. AWS IoT Jobs then updates and returns the job execution status as `Failed`. You can retry this job execution for the device using the [Job execution retry configuration](jobs-configurations-details.md#job-retry-configuration).
![\[Image showing how an in-progress job execution can fail and how to retry the execution.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/JE-inprogress-failed.png)
+
**TIMED\$1OUT**
When your device fails to complete a job step when the status is `IN_PROGRESS`, or when it fails to complete the remote operation within the timeout duration of the in-progress timer, AWS IoT Jobs sets the job execution status to `TIMED_OUT`. You also have a step timer for each job step of an in-progress job and applies only to the job execution. The in-progress timer duration is specified using the `inProgressTimeoutInMinutes` property of the [Job execution timeout configuration](jobs-configurations-details.md#job-timeout-configuration). You can retry this job execution for the device using the [Job execution retry configuration](jobs-configurations-details.md#job-retry-configuration).
![\[Image showing how an in-progress job execution can time out and how to retry the execution.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/JE-inprogress-timedout.png)
+
**REJECTED**
When your device receives an invalid or incompatible request, the device must invoke the `UpdateJobExecution` API with a status of `REJECTED`. AWS IoT Jobs then updates and returns the job execution status as `REJECTED`.
+
**REMOVED**
When your device is no longer a valid target for the job execution, such as when it's detached from a dynamic thing group, AWS IoT Jobs sets the job execution status to `REMOVED`. You can re-attach the thing to your target group and restart the job execution for the device.
+
**CANCELED**
When you cancel a job or cancel a job execution using the console or the `CancelJob` or `CancelJobExecution` API, or when the abort criteria specified using the [Job abort configuration](jobs-configurations-details.md#job-abort-using) is met, AWS IoT Jobs cancels the job and sets the job execution status to `CANCELED`.
# 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.
# Job templates
Use job templates to preconfigure jobs that you can deploy to multiple sets of target devices. To deploy frequently performed remote actions to your devices, like rebooting or installing an application, you can use templates to define standard configurations. To perform operations such as deploying security patches and bug fixes, you can create templates from existing jobs.
When creating a job template, specify the following additional configurations and resources.
+ Job properties
+ Job documents and targets
+ Rollout, scheduling, and cancel criteria
+ Timeout and retry criteria
## Custom and AWS managed templates
Depending on the remote action that you want to perform, you can either create a custom job template or use an AWS managed template. Use custom job templates to provide your own custom job document and create reusable jobs to deploy to your devices. AWS managed templates are job templates provided by AWS IoT Jobs for commonly performed actions. These templates have a predefined job document for some remote actions so you don't have to create your own job document. Managed templates help you create reusable jobs for faster launch to your devices.
**Topics**
+ [
## Custom and AWS managed templates
](#job-templates-types)
+ [
# Use AWS managed templates to deploy common remote operations
](job-templates-managed.md)
+ [
# Create custom job templates
](job-templates-create.md)
# Use AWS managed templates to deploy common remote operations
Use AWS managed templates
AWS managed templates are job templates provided by AWS. They're used for frequently performed remote actions such as rebooting, downloading a file, or installing an application on your devices. These templates have a predefined job document for each remote action so you don't have to create your own job document.
You can choose from a set of predefined configurations and create jobs using these templates without writing any additional code. Using managed templates, you can view the job document deployed to your fleets. You can create a job using these templates and create a custom job template that you can reuse for your remote operations.
## What do managed templates contain?
Each AWS managed template contains:
+ The environment to run the commands in the job document.
+ A job document that specifies the name of the operation and its parameters. For example, if you use a **Download file** template, the operation name is *Download file* and the parameters can be:
+ The URL of the file that you want to download to your device. This can be an internet resource or a public or pre-signed Amazon Simple Storage Service((Amazon S3) URL.
+ A local file path on the device to store the downloaded file.
For more information about the job documents and its parameters, see [Managed template remote actions and job documents](#job-template-manage-actions).
## Prerequisites
For your devices to run the remote actions specified by the managed template job document, you must:
+ **Install the specific software on your device**
Use your own device software and job handlers, or the AWS IoT Device Client. Depending on your business case, you can also run them both so that they perform different functions.
+ **Use your own device software and job handlers**
You can write your own code for the devices by using the AWS IoT Device SDK and its library of handlers that support the remote operations. To deploy and run jobs, verify that the device agent libraries have been installed correctly and are running on the devices.
You can also choose to use your own handlers that support the remote operations. For more information, see [Sample job handlers](https://github.com/awslabs/aws-iot-device-client/tree/main/sample-job-handlers) in the AWS IoT Device Client GitHub repository.
+ **Use the AWS IoT Device Client**
Or, you can install and run the AWS IoT Device Client on your devices because it supports using all managed templates directly from the console by default.
The Device Client is an open-source software written in C\$1\$1 that you can compile and install on your embedded Linux-based IoT devices. The Device Client has a *base client* and discrete *client-side features*. The base client establishes connectivity with AWS IoT over MQTT protocol and can connect with the different client-side features.
To perform remote operations on your devices, use the *client-side Jobs feature* of the Device Client. This feature contains a parser to receive the job document and job handlers that implement the remote actions specified in the job document. For more information about the Device Client and its features, see [AWS IoT Device Client](https://github.com/awslabs/aws-iot-device-client#readme).
When running on devices, the Device Client receives the job document and has a platform-specific implementation that it uses to run commands in the document. For more information about setting up the Device Client and using the Jobs feature, see [AWS IoT tutorials](https://docs.aws.amazon.com/iot/latest/developerguide/iot-tutorials.html).
+ **Use a supported environment**
For each managed template, you'll find information about the environment that you can use to run the remote actions. We recommend that you use the template with a supported Linux environment as specified in the template. Use the AWS IoT Device Client to run the managed template remote actions because it supports common microprocessors and Linux environments, like Debian and Ubuntu.
## Managed template remote actions and job documents
The following section lists the different AWS managed templates for AWS IoT Jobs, and describes the remote actions that can be performed on the devices. The following section has information about the job document and a description of the job document parameters for each remote action. Your device-side software uses the template name and the parameters to perform the remote action.
AWS managed templates accept input parameters for which you specify a value when creating a job using the template. All managed templates have two optional input parameters in common: `runAsUser` and `pathToHandler`. Except for the `AWS-Reboot` template, the templates require additional input parameters for which you must specify a value when creating a job using the template. These required input parameters vary depending on the template that you choose. For example, if you choose the `AWS-Download-File` template, you must specify a list of packages to install, and a URL to download files from.
Specify a value for the input parameters when using the AWS IoT console or the AWS Command Line Interface (AWS CLI) to create a job that uses a managed template. When using the CLI, provide these values by using the `document-parameters` object. For more information, see [ documentParameters](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html#iot-CreateJob-request-documentParameters).
**Note**
Use `document-parameters` only when creating jobs from AWS managed templates. This parameter can't be used with custom job templates or to create jobs from them.
The following shows a description of the common optional input parameters. You'll see a description of other input parameters that each managed template requires in the next section.
`runAsUser`
This parameter specifies whether to run the job handler as another user. If it's not specified during job creation, the job handler is run as the same user as the Device Client. When you run the job handler as another user, specify a string value that's not longer than 256 characters.
`pathToHandler`
The path to the job handler running on the device. If it's not specified during job creation, the Device Client uses the current working directory.
The following shows the different remote actions, their job documents, and parameters that they accept. All these templates support the Linux environment for running the remote operation on the device.
### AWS–Download–File
**Template name**
`AWS–Download–File`
**Template description**
A managed template provided by AWS for downloading a file.
**Input parameters**
This template has the following required parameters. You can also specify the optional parameters `runAsUser` and `pathToHandler`.
`downloadUrl`
The URL to download the file from. This can be an internet resource, an object in Amazon S3 that can be publicly accessed, or an object in Amazon S3 that can only be accessed by your device using a presigned URL. For more information about using presigned URLs and granting permissions, see [Presigned URLs](create-manage-jobs.md#create-manage-jobs-presigned-URLs).
`filePath`
A local file path that shows the location in the device to store the downloaded file.
**Device behavior**
The device downloads the file from the specified location, verifies that the download is complete, and stores it locally.
**Job document**
The following shows the job document and its latest version. The template shows the path to the job handler and the shell script, `download-file.sh`, that the job handler must run to download the file. It also shows the required parameters `downloadUrl` and `filePath`.
```
{
"version": "1.0",
"steps": [
{
"action": {
"name": "Download-File",
"type": "runHandler",
"input": {
"handler": "download-file.sh",
"args": [
"${aws:iot:parameter:downloadUrl}",
"${aws:iot:parameter:filePath}"
],
"path": "${aws:iot:parameter:pathToHandler}"
},
"runAsUser": "${aws:iot:parameter:runAsUser}"
}
}
]
}
```
### AWS–Install–Application
**Template name**
`AWS–Install–Application`
**Template description**
A managed template provided by AWS for installing one or more applications.
**Input parameters**
This template has the following required parameter, `packages`. You can also specify the optional parameters `runAsUser` and `pathToHandler`.
`packages`
A space-separated list of one or more applications to be installed.
**Device behavior**
The device installs the applications as specified in the job document.
**Job document**
The following shows the job document and its latest version. The template shows the path to the job handler and the shell script, `install-packages.sh`, that the job handler must run to download the file. It also shows the required parameter `packages`.
```
{
"version": "1.0",
"steps": [
{
"action": {
"name": "Install-Application",
"type": "runHandler",
"input": {
"handler": "install-packages.sh",
"args": [
"${aws:iot:parameter:packages}"
],
"path": "${aws:iot:parameter:pathToHandler}"
},
"runAsUser": "${aws:iot:parameter:runAsUser}"
}
}
]
}
```
### AWS–Reboot
**Template name**
`AWS–Reboot`
**Template description**
A managed template provided by AWS for rebooting your device.
**Input parameters**
This template has no required parameters. You can specify the optional parameters `runAsUser` and `pathToHandler`.
**Device behavior**
The device reboots successfully.
**Job document**
The following shows the job document and its latest version. The template shows the path to the job handler and the shell script, `reboot.sh`, that the job handler must run to reboot the device.
```
{
"version": "1.0",
"steps": [
{
"action": {
"name": "Reboot",
"type": "runHandler",
"input": {
"handler": "reboot.sh",
"path": "${aws:iot:parameter:pathToHandler}"
},
"runAsUser": "${aws:iot:parameter:runAsUser}"
}
}
]
}
```
### AWS–Remove–Application
**Template name**
`AWS–Remove–Application`
**Template description**
A managed template provided by AWS for uninstalling one or more applications.
**Input parameters**
This template has the following required parameter, `packages`. You can also specify the optional parameters `runAsUser` and `pathToHandler`.
`packages`
A space-separated list of one or more applications to be uninstalled.
**Device behavior**
The device uninstalls the applications as specified in the job document.
**Job document**
The following shows the job document and its latest version. The template shows the path to the job handler and the shell script, `remove-packages.sh`, that the job handler must run to download the file. It also shows the required parameter `packages`.
```
{
"version": "1.0",
"steps": [
{
"action": {
"name": "Remove-Application",
"type": "runHandler",
"input": {
"handler": "remove-packages.sh",
"args": [
"${aws:iot:parameter:packages}"
],
"path": "${aws:iot:parameter:pathToHandler}"
},
"runAsUser": "${aws:iot:parameter:runAsUser}"
}
}
]
}
```
### AWS–Restart–Application
**Template name**
`AWS–Restart–Application`
**Template description**
A managed template provided by AWS for stopping and restarting one or more services.
**Input parameters**
This template has the following required parameter, `services`. You can also specify the optional parameters `runAsUser` and `pathToHandler`.
**Services**
A space-separated list of one or more applications to be restarted.
**Device behavior**
The specified applications are stopped and then restarted on the device.
**Job document**
The following shows the job document and its latest version. The template shows the path to the job handler and the shell script, `restart-services.sh`, that the job handler must run to restart the system services. It also shows the required parameter `services`.
```
{
"version": "1.0",
"steps": [
{
"action": {
"name": "Restart-Application",
"type": "runHandler",
"input": {
"handler": "restart-services.sh",
"args": [
"${aws:iot:parameter:services}"
],
"path": "${aws:iot:parameter:pathToHandler}"
},
"runAsUser": "${aws:iot:parameter:runAsUser}"
}
}
]
}
```
### AWS–Start–Application
**Template name**
`AWS-Start-Application`
**Template description**
A managed template provided by AWS for starting one or more services.
**Input parameters**
This template has the following required parameter, `services`. You can also specify the optional parameters `runAsUser` and `pathToHandler`.
`services`
A space-separated list of one or more applications to be started.
**Device behavior**
The specified applications start running on the device.
**Job document**
The following shows the job document and its latest version. The template shows the path to the job handler and the shell script, `start-services.sh`, that the job handler must run to start the system services. It also shows the required parameter `services`.
```
{
"version": "1.0",
"steps": [
{
"action": {
"name": "Start-Application",
"type": "runHandler",
"input": {
"handler": "start-services.sh",
"args": [
"${aws:iot:parameter:services}"
],
"path": "${aws:iot:parameter:pathToHandler}"
},
"runAsUser": "${aws:iot:parameter:runAsUser}"
}
}
]
}
```
### AWS–Stop–Application
**Template name**
`AWS–Stop–Application`
**Template description**
A managed template provided by AWS for stopping one or more services.
**Input parameters**
This template has the following required parameter, `services`. You can also specify the optional parameters `runAsUser` and `pathToHandler`.
`services`
A space-separated list of one or more applications to be stopped.
**Device behavior**
The specified applications stop running on the device.
**Job document**
The following shows the job document and its latest version. The template shows the path to the job handler and the shell script, `stop-services.sh`, that the job handler must run to stop the system services. It also shows the required parameter `services`.
```
{
"version": "1.0",
"steps": [
{
"action": {
"name": "Stop-Application",
"type": "runHandler",
"input": {
"handler": "stop-services.sh",
"args": [
"${aws:iot:parameter:services}"
],
"path": "${aws:iot:parameter:pathToHandler}"
},
"runAsUser": "${aws:iot:parameter:runAsUser}"
}
}
]
}
```
### AWS–Run–Command
**Template name**
`AWS–Run–Command`
**Template description**
A managed template provided by AWS for running a shell command.
**Input parameters**
This template has the following required parameter, `command`. You can also specify the optional parameter `runAsUser`.
`command`
A comma separated string of command. Any comma contained in the command itself must be escaped.
**Device behavior**
The device runs the shell command as specified in the job document.
**Job document**
The following shows the job document and its latest version. The template shows the path to the job command and the command that you provided which the device will run.
```
{
"version": "1.0",
"steps": [
{
"action": {
"name": "Run-Command",
"type": "runCommand",
"input": {
"command": "${aws:iot:parameter:command}"
},
"runAsUser": "${aws:iot:parameter:runAsUser}"
}
}
]
}
```
**Topics**
+ [
## What do managed templates contain?
](#job-template-managed-contains)
+ [
## Prerequisites
](#job-template-managed-prereq)
+ [
## Managed template remote actions and job documents
](#job-template-manage-actions)
+ [
# Create a job from AWS managed templates by using the AWS Management Console
](job-template-manage-console-create.md)
+ [
# Create a job from AWS managed templates by using the AWS CLI
](job-template-manage-cli-create.md)
# Create a job from AWS managed templates by using the AWS Management Console
Create a job from AWS managed templates using the console
Use the AWS Management Console to get information about AWS managed templates and create a job by using these templates. You can then save the job you create as your own custom template.
## Get details about managed templates
You can get information about the different managed templates that are available to use from the AWS IoT console.
1. To see your available managed templates, go to the [Job templates hub of the AWS IoT console](https://console.aws.amazon.com/iot/home#/jobtemplatehub) and choose the **Managed templates** tab.
1. To view details, choose a managed template.
The details page contains the following information:
+ Name, description, and Amazon Resource Name (ARN) of the managed template.
+ The environment on which the remote operations can be performed, such as Linux.
+ The JSON job document that specifies the path to the job handler and the commands to run on the device. For example, the following shows an example job document for the **AWS-Reboot** template. The template shows the path to the job handler and the shell script, `reboot.sh`, that the job handler must run to reboot the device.
```
{
"version": "1.0",
"steps": [
{
"action": {
"name": "Reboot",
"type": "runHandler",
"input": {
"handler": "reboot.sh",
"path": "${aws:iot:parameter:pathToHandler}"
},
"runAsUser": "${aws:iot:parameter:runAsUser}"
}
}
]
}
```
For more information about the job document and its parameters for various remote actions, see [Managed template remote actions and job documents](job-templates-managed.md#job-template-manage-actions).
+ The latest version of the job document.
## Create a job using managed templates
You can use the AWS Management console to choose an AWS managed template to use to create a job. This section shows you how.
You can also start the job creation workflow and then choose the AWS managed template that you want to use while creating the job. For more information about this workflow, see [Create and manage jobs by using the AWS Management Console](manage-job-console.md).
1.
**Choose your AWS managed template**
Go to the [Job templates hub of the AWS IoT console](https://console.aws.amazon.com/iot/home#/jobtemplatehub), choose the **Managed templates** tab, and then choose your template.
1.
**Create a job using your managed template**
1. In the details page of your template, choose **Create job**.
The console switches to the **Custom job properties** step of the **Create job** workflow where your template configuration has been added.
1. Enter a unique alphanumeric job name, and optional description and tags, and then choose **Next**.
1. Choose the things or thing groups as job targets that you want to run in this job.
1. In the **Job document** section, your template is displayed with its configuration settings and input parameters. Enter values for the input parameters of your chosen template. For example, if you chose the **AWS-Download-File** template:
+ For **downloadUrl**, enter the URL of the file to download, for example: `https://example.com/index.html`.
+ For **filePath**, enter the path on the device to store the downloaded file, for example: `path/to/file`.
You can also optionally enter values for the parameters `runAsUser` and `pathToHandler`. For more information about the input parameters of each template, see [Managed template remote actions and job documents](job-templates-managed.md#job-template-manage-actions).
1. On the **Job configuration** page, choose the job type as continuous or a snapshot job. A snapshot job is complete when it finishes its run on the target devices and groups. A continuous job applies to thing groups and runs on any device that you add to a specified target group.
1. Continue to add any additional configurations for your job and then review and create your job. For information about the additional configurations, see:
+ [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)
## Create custom job templates from managed templates
You can use an AWS managed template and a custom job as a starting point to create your own custom job template. To create a custom job template, first create a job from your AWS managed template as described in the previous section.
You can then save the custom job as a template to create your own custom job template. To save as template:
1. Go to the [Job hub of the AWS IoT console](https://console.aws.amazon.com/iot/home#/jobhub) and choose the job containing your managed template.
1. Choose **Save as a job template** and then create your custom job template. For more information about creating a custom job template, see [Create a job template from an existing job](job-templates-console.md#job-templates-console-create-exist-job).
# Create a job from AWS managed templates by using the AWS CLI
Create a job from AWS managed templates using the CLI
Use the AWS CLI to get information about AWS managed templates and create a job by using these templates. You can then save the job as a template and then create your own custom template.
## List managed templates
The [https://docs.aws.amazon.com/cli/latest/reference/iot/list-managed-job-templates.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-managed-job-templates.html) AWS CLI command lists all of the job templates in your AWS account.
```
aws iot list-managed-job-templates
```
By default, running this command displays all available AWS managed templates and their details.
```
{
"managedJobTemplates": [
{
"templateArn": "arn:aws:iot:region::jobtemplate/AWS-Reboot:1.0",
"templateName": "AWS-Reboot",
"description": "A managed job template for rebooting the device.",
"environments": [
"LINUX"
],
"templateVersion": "1.0"
},
{
"templateArn": "arn:aws:iot:region::jobtemplate/AWS-Remove-Application:1.0",
"templateName": "AWS-Remove-Application",
"description": "A managed job template for uninstalling one or more applications.",
"environments": [
"LINUX"
],
"templateVersion": "1.0"
},
{
"templateArn": "arn:aws:iot:region::jobtemplate/AWS-Stop-Application:1.0",
"templateName": "AWS-Stop-Application",
"description": "A managed job template for stopping one or more system services.",
"environments": [
"LINUX"
],
"templateVersion": "1.0"
},
...
{
"templateArn": "arn:aws:iot:us-east-1::jobtemplate/AWS-Restart-Application:1.0",
"templateName": "AWS-Restart-Application",
"description": "A managed job template for restarting one or more system services.",
"environments": [
"LINUX"
],
"templateVersion": "1.0"
}
]
}
```
For more information, see [ListManagedJobTemplates](https://docs.aws.amazon.com/iot/latest/apireference/API_ListManagedJobTemplates.html).
## Get details about a managed template
The [https://docs.aws.amazon.com/cli/latest/reference/iot/describe-managed-job-template.html](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-managed-job-template.html) AWS CLI command gets details about a specified job template. Specify the job template name and an optional template version. If the template version is not specified, the predefined, default version is returned. The following shows an example of running the command to get details about the `AWS-Download-File` template.
```
aws iot describe-managed-job-template \
--template-name AWS-Download-File
```
The command displays the template details and ARN, its job document, and the `documentParameters` parameter, which is a list of key-value pairs of input parameters of the template. For information about the different templates and input parameters, see [Managed template remote actions and job documents](job-templates-managed.md#job-template-manage-actions).
**Note**
The `documentParameters` object returned when you use this API must only be used when creating jobs from AWS managed templates. The object must not be used for custom job templates. For an example that shows how to use this parameter, see [Create a job by using managed templates](#job-template-manage-cli-create-job).
```
{
"templateName": "AWS-Download-File",
"templateArn": "arn:aws:iot:region::jobtemplate/AWS-Download-File:1.0",
"description": "A managed job template for downloading a file.",
"templateVersion": "1.0",
"environments": [
"LINUX"
],
"documentParameters": [
{
"key": "downloadUrl",
"description": "URL of file to download.",
"regex": "(.*?)",
"example": "http://www.example.com/index.html",
"optional": false
},
{
"key": "filePath",
"description": "Path on the device where downloaded file is written.",
"regex": "(.*?)",
"example": "/path/to/file",
"optional": false
},
{
"key": "runAsUser",
"description": "Execute handler as another user. If not specified, then handler is executed as the same user as device client.",
"regex": "(.){0,256}",
"example": "user1",
"optional": true
},
{
"key": "pathToHandler",
"description": "Path to handler on the device. If not specified, then device client will use the current working directory.",
"regex": "(.){0,4096}",
"example": "/path/to/handler/script",
"optional": true
}
],
"document": "{\"version\":\"1.0\",\"steps\":[{\"action\":{\"name\":\"Download-File\",\"type\":\"runHandler\",\"input\":{\"handler\":\"download-file.sh\",\"args\":[\"${aws:iot:parameter:downloadUrl}\",\"${aws:iot:parameter:filePath}\"],\"path\":\"${aws:iot:parameter:pathToHandler}\"},\"runAsUser\":\"${aws:iot:parameter:runAsUser}\"}}]}"
}
```
For more information, see [DescribeManagedJobTemplate](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeManagedJobTemplate.html).
## Create a job by using managed templates
The [https://docs.aws.amazon.com/cli/latest/reference/iot/create-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/create-job.html) AWS CLI command can be used to create a job from a job template. It targets a device named `thingOne` and specifies the Amazon Resource Name (ARN) of the managed template to use as the basis for the job. You can override advanced configurations, such as timeout and cancel configurations, by passing the associated parameters of the `create-job` command.
The example shows how to create a job that uses the `AWS-Download-File` template. It also shows how to specify the input parameters of the template by using the `document-parameters` parameter.
**Note**
Use the `document-parameters` object only with AWS managed templates. This object must not be used with custom job templates.
```
aws iot create-job \
--targets arn:aws:iot:region:account-id:thing/thingOne \
--job-id "new-managed-template-job" \
--job-template-arn arn:aws:iot:region::jobtemplate/AWS-Download-File:1.0 \
--document-parameters downloadUrl=https://example.com/index.html,filePath=path/to/file
```
where:
+ *region* is the AWS Region.
+ *account-id* is the unique AWS account number.
+ `thingOne` is the name of the IoT thing for which the job is targeted.
+ *AWS-Download-File:1.0* is the name of the managed template.
+ `https://example.com/index.html` is the URL to download the file from.
+ `https://pathto/file/index` is the path on the device to store the downloaded file.
Run the following command to create a job for the template, `AWS-Download-File`.
```
{
"jobArn": "arn:aws:iot:region:account-id:job/new-managed-template-job",
"jobId": "new-managed-template-job",
"description": "A managed job template for downloading a file."
}
```
## Create a custom job template from managed templates
1. Create a job using a managed template as described in the previous section.
1. Create a custom job template by using the ARN of the job that you created. For more information, see [Create a job template from an existing job](job-templates-cli.md#job-templates-cli-create-from-job).
# Create custom job templates
You can create job templates by using the AWS CLI and the AWS IoT console. You can also create jobs from job templates by using the AWS CLI, the AWS IoT console, and Fleet Hub for AWS IoT Device Management web applications. For more information about working with job templates in Fleet Hub applications, see [Working with job templates in Fleet Hub for AWS IoT Device Management](https://docs.aws.amazon.com/iot/latest/fleethubuserguide/aws-iot-monitor-technician-job-templates.html).
**Note**
The total number of substitution patterns in a job document should be less than or equal to ten.
**Topics**
+ [
# Create custom job templates by using the AWS Management Console
](job-templates-console.md)
+ [
# Create custom job templates by using the AWS CLI
](job-templates-cli.md)
# Create custom job templates by using the AWS Management Console
Create custom job templates using the console
This topic explains how to create, delete, and view details about job templates by using the AWS IoT console.
## Create a custom job template
You can either create an original custom job template or create a job template from an existing job. You can also create a custom job template from an existing job that was created using an AWS managed template. For more information, see [Create custom job templates from managed templates](job-template-manage-console-create.md#job-template-manage-create-template).
### Create an original job template
1.
**Start creating your job template**
1. Go to the [Job templates hub of the AWS IoT console](https://console.aws.amazon.com/iot/home#/jobtemplatehub) and choose the **Custom templates** tab.
1. Choose **Create job template**.
**Note**
You can also navigate to the **Job templates** page from the **Related services** page under **Fleet Hub**.
1.
**Specify job template properties**
In the **Create job template** page, enter an alphanumeric identifier for your job name and an alphanumeric description to provide additional details about the template.
**Note**
We don't recommend using personally identifiable information in your job IDs or descriptions.
1.
**Provide job document**
Provide a JSON job file that is either stored in an S3 bucket or as an inline job document that is specified within the job. This job file will become the job document when you create a job using this template.
If the job file is stored in an S3 bucket, enter the S3 URL or choose **Browse S3**, and then navigate to your job document and select it.
**Note**
You can select only S3 buckets in your current Region.
1. Continue to add any additional configurations for your job and then review and create your job. For information about the additional, optional configurations, refer to the following links:
+ [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)
### Create a job template from an existing job
1.
**Choose your job**
1. Go to the [Job hub of the AWS IoT console](https://console.aws.amazon.com/iot/home#/jobhub) and choose the job that you want to use as the basis for your job template.
1. Choose **Save as a job template**.
**Note**
Optionally, you can choose a different job document or edit the advanced configurations from the original job, and then choose **Create job template**. Your new job template appears on the **Job templates** page.
1.
**Specify job template properties**
In the **Create job template** page, enter an alphanumeric identifier for your job name and an alphanumeric description to provide additional details about the template.
**Note**
The job document is the job file that you specified when creating the template. If the job document is specified within the job instead of an S3 location, you can see the job document in the details page of this job.
1. Continue to add any additional configurations for your job and then review and create your job. For information about the additional configurations, see:
+ [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)
## Create a job from a custom job template
You can create a job from a custom job template by going to the details page of your job template as described in this topic. You can also create a job or by choosing the job template you want to use when running the job creation workflow. For more information, see [Create and manage jobs by using the AWS Management Console](manage-job-console.md).
This topic shows how to create a job from the details page of a custom job template. You can also create a job from an AWS managed template. For more information, see [Create a job using managed templates](job-template-manage-console-create.md#job-template-manage-create-job).
1.
**Choose your custom job template**
Go to the [Job templates hub of the AWS IoT console](https://console.aws.amazon.com/iot/home#/jobtemplatehub) and choose the **Custom templates** tab, and then choose your template.
1.
**Create a job using your custom template**
To create a job:
1. In the details page of your template, choose **Create job**.
The console switches to the **Custom job properties** step of the **Create job** workflow where your template configuration has been added.
1. Enter a unique alphanumeric job name, and optional description and tags, and then choose **Next**.
1. Choose the things or thing groups as job targets that you want to run in this job.
In the **Job document** section, your template is displayed with its configuration settings. If you want to use a different job document, choose **Browse** and select a different bucket and document. Choose **Next**.
1. On the **Job configuration** page, choose the job type as continuous or a snapshot job. A snapshot job is complete when it finishes its run on the target devices and groups. A continuous job applies to thing groups and runs on any device that you add to a specified target group.
1. Continue to add any additional configurations for your job and then review and create your job. For information about the additional configurations, see:
+ [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)
**Note**
When a job created from a job template updates the existing parameters provided by the job template, those updated parameters will override the existing parameters provided by the job template for that job.
You can also create jobs from job templates with Fleet Hub web applications. For information about creating jobs in Fleet Hub, see [Working with job templates in Fleet Hub for AWS IoT Device Management](https://docs.aws.amazon.com/iot/latest/fleethubuserguide/aws-iot-monitor-technician-job-templates.html).
## Delete a job template
To delete a job template, first go to the [Job templates hub of the AWS IoT console](https://console.aws.amazon.com/iot/home#/jobtemplatehub) and choose the **Custom templates** tab. Then, choose the job template you want to delete and choose **Next**.
**Note**
A deletion is permanent and the job template no longer appears on the **Custom templates** tab.
# Create custom job templates by using the AWS CLI
Create custom job templates using the CLI
This topic explains how to create, delete, and retrieve details about job templates by using the AWS CLI.
## Create a job template from scratch
The following AWS CLI command shows how to create a job using a job document (*job-document.json*) stored in an S3 bucket and a role with permission to download files from Amazon S3 (*S3DownloadRole*).
```
aws iot create-job-template \
--job-template-id 010 \
--description "My custom job template for updating the device firmware"
--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 optional `timeout-config` parameter specifies the amount of time each device has to finish running 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 launches for the job. Whenever a job launch remains in the `IN_PROGRESS` state for longer than this interval, the job launch fails and switches to the terminal `TIMED_OUT` status. AWS IoT also publishes an MQTT notification.
For more information about creating configurations about job rollouts and aborts, see [Job rollout and abort configuration](job-rollout-abort-scheduling.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 you used as the source of your job document after you create the job, what is sent to the targets of the job doesn't change.
## Create a job template from an existing job
The following AWS CLI command creates a job template by specifying the Amazon Resource Name (ARN) of an existing job. The new job template uses all of the configurations specified in the job. Optionally, you can change any of the configurations in the existing job by using any of the optional parameters.
```
aws iot create-job-template \
--job-arn arn:aws:iot:region:123456789012:job/job-name \
--timeout-config inProgressTimeoutInMinutes=100
```
## Get details about a job template
The following AWS CLI command gets details about a specified job template.
```
aws iot describe-job-template \
--job-template-id template-id
```
The command displays the following output.
```
{
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": number,
"thresholdPercentage": number
}
]
},
"createdAt": number,
"description": "string",
"document": "string",
"documentSource": "string",
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": number,
"incrementFactor": number,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": number,
"numberOfSucceededThings": number
}
},
"maximumPerMinute": number
},
"jobTemplateArn": "string",
"jobTemplateId": "string",
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
}
```
## List job templates
The following AWS CLI command lists all of the job templates in your AWS account.
```
aws iot list-job-templates
```
The command displays the following output.
```
{
"jobTemplates": [
{
"createdAt": number,
"description": "string",
"jobTemplateArn": "string",
"jobTemplateId": "string"
}
],
"nextToken": "string"
}
```
To retrieve additional pages of results, use the value of the `nextToken` field.
## Delete a job template
The following AWS CLI command deletes a specified job template.
```
aws iot delete-job-template \
--job-template-id template-id
```
The command displays no output.
## Create a job from a custom job template
The following AWS CLI command creates a job from a custom job template. It targets a device named `thingOne` and specifies the Amazon Resource Name (ARN) of the job template to use as the basis for the job. You can override advanced configurations, such as timeout and cancel configurations, by passing the associated parameters of the `create-job` command.
**Warning**
The `document-parameters` object must be used with the `create-job` command only when creating jobs from AWS managed templates. This object must not be used with custom job templates. For an example that shows how to create jobs using this parameter, see [Create a job by using managed templates](job-template-manage-cli-create.md#job-template-manage-cli-create-job).
```
aws iot create-job \
--targets arn:aws:iot:region:123456789012:thing/thingOne \
--job-template-arn arn:aws:iot:region:123456789012:jobtemplate/template-id
```
# Job configurations
You can have the following additional configurations for each job that you deploy to the specified targets.
+ **Rollout**: Defines how many devices receive the job document every minute.
+ **Scheduling**: Schedules a job for a future date and time in addition to using recurring maintenance windows.
+ **Abort**: Cancels a job in cases such as when some devices don't receive the job notification, or your devices report failure for their job executions.
+ **Timeout**: If there isn't a response from your job targets within a certain duration after their job executions have started, the job can fail.
+ **Retry**: Retries the job execution if your device reports failure when attempting to complete a job execution, or if your job execution times out.
By using these configurations, you can monitor the status of your job execution and avoid a bad update from being sent to an entire fleet.
**Topics**
+ [
# How job configurations work
](jobs-configurations-details.md)
+ [
# Specify additional configurations
](jobs-configurations-specify.md)
# How job configurations work
You use the rollout and abort configurations when you're deploying a job, and the timeout and retry configurations for job execution. The following sections show more information about how these configurations work.
**Topics**
+ [
## Job rollout, scheduling, and abort configurations
](#job-rollout-abort-scheduling)
+ [
## Job execution timeout and retry configurations
](#job-timeout-retry)
## Job rollout, scheduling, and abort configurations
You can use the job rollout, scheduling, and abort configurations to define how many devices receive the job document, schedule a job rollout, and determine the criteria for canceling a job.
### Job rollout configuration
You can specify how quickly targets are notified of a pending job execution. You can also create a staged rollout to manage updates, reboots, and other operations. To specify how your targets are notified, use job rollout rates.
#### Job rollout rates
You can create a rollout configuration by using either a constant rollout rate or an exponential rollout rate. To specify the maximum number of job targets to inform per minute, use a constant rollout rate.
AWS IoT jobs can be deployed using exponential rollout rates as various criteria and thresholds are met. If the number of failed jobs matches a set of criteria that you specify, then you can cancel the job rollout. You set the job rollout rate criteria when you create a job by using the [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionsRolloutConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionsRolloutConfig.html) object. You also set the job abort criteria at job creation by using the [https://docs.aws.amazon.com/iot/latest/apireference/API_AbortConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_AbortConfig.html) object.
The following example shows how rollout rates work. For example, a job rollout with a base rate of 50 per minute, increment factor of 2, and number of notified and succeeded devices each as 1,000, would work as follows: The job will start at a rate of 50 job executions per minute and continue at that rate until either 1,000 things have received job execution notifications, or 1,000 successful job executions have occurred.
The following table illustrates how the rollout would proceed over the first four increments.
| | | | | |
| --- |--- |--- |--- |--- |
| Rollout rate per minute | 50 | 100 | 200 | 400 |
| Number of notified devices or successful job executions to satisfy a rate increase | 1,000 | 2,000 | 3,000 | 4,000 |
**Note**
If you're at your max concurrent limit of 500 Jobs (`isConcurrent = True`), then all active jobs will remain with a status of `IN-PROGRESS` and not roll out any new job executions until the number of concurrent jobs is 499 or less (`isConcurrent = False)`. This applies to snapshot and continuous jobs.
If `isConcurrent = True`, the job is currently rolling out job executions to all devices in your target group. If `isConcurrent = False`, the job has completed the rollout of all job executions to all devices in your target group. It will update its status state once all devices in your target group reach a terminal state, or a threshold percentage of your target group if you selected a job abort configuration. The Job level status states for `isConcurrent = True` and `isConcurrent = False` are both `IN_PROGRESS`.
For more information about active and concurrent job limits, see [Active and concurrent job limits](job-limits.md#job-limits-active-concurrent).
#### Job rollout rates for continuous jobs using dynamic thing groups
When you use a continuous job to roll out remote operations on your fleet, AWS IoT Jobs rolls out job executions for devices in your target thing group. For new devices that are added to the dynamic thing group, these job executions continue to roll out to those devices even after the job has been created.
The rollout configuration can control the rollout rates only for devices that are added to the group until job creation. After a job has been created, for any new devices, the job executions are created in near real time as soon as the devices join the target group.
### Job scheduling configuration
You can schedule a continuous or snapshot job up to a year in advance using a pre-determined start time, end time, and end behavior for what will happen to each job execution upon reaching the end time. Additionally, you can create an optional recurring maintenance window with a flexible frequency, start time, and duration for continuous jobs to roll out a job document to all devices within the target group.
#### Job scheduling configurations
**Start time**
The start time of a scheduled job is the future date and time that job will begin rollout of the job document to all devices in the target group. Start time for a scheduled job applies to continuous jobs and snapshot jobs. When a scheduled job is initially created, it maintains a status state of `SCHEDULED`. Upon arriving at the `startTime` that you selected, it updates to `IN_PROGRESS` and begins the job document rollout. The `startTime` must be less than or equal to one year from the initial date and time that you created the scheduled job.
For more information on the syntax for `startTime` when 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).
For a job with the optional scheduling configuration that takes place during a recurring maintenance window in a location observing daylight savings time (DST), the time will change by one hour when switching from DST to standard time and from standard time to DST.
**Note**
The time zone displayed in the AWS Management Console is your current system time zone. However, these time zones will be converted into UTC in the system.
**End time**
The end time of a scheduled job is the future date and time that the job will stop rollout of the job document to any remaining devices in the target group. End time for a scheduled job applies to continuous jobs and snapshot jobs. After a scheduled job arrives at the selected `endTime`, and all job executions have reached a terminal state, it updates its status state from `IN_PROGRESS` to `COMPLETED`. The `endTime` must be less than or equal to two years from the initial date and time that you created the scheduled job. The minimum duration between `startTime` and `endTime` is 30 minutes. Job execution retry attempts will occur until the job reaches the `endTime`, then the `endBehavior` will dictate how to proceed.
For more information on the syntax for `endTime` when 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).
For a job with the optional scheduling configuration that takes place during a recurring maintenance window in a location observing daylight savings time (DST), the time will change by one hour when switching from DST to standard time and from standard time to DST.
**Note**
The time zone displayed in the AWS Management Console is your current system time zone. However, these time zones will be converted into UTC in the system.
**End behavior**
The end behavior of a scheduled job determines what happens to the job and all unfinished job executions when the job reaches the selected `endTime`.
The following lists the end behaviors that you can select from when creating the job or job template:
+ `STOP_ROLLOUT`
+ `STOP_ROLLOUT` stops the rollout of the job document to all remaining devices in the target group for the job. Additionally, all `QUEUED` and `IN_PROGRESS` job executions will continue until they reach a terminal state. This is the default end behavior unless you select `CANCEL` or `FORCE_CANCEL`.
+ `CANCEL`
+ `CANCEL` stops the rollout of the job document to all remaining devices in the target group for the job. Additionally, all `QUEUED` job executions will be cancelled while all `IN_PROGRESS` job executions will continue until they reach a terminal state.
+ `FORCE_CANCEL`
+ `FORCE_CANCEL` stops the rollout of the job document to all remaining devices in the target group for the job. Additionally, all `QUEUED` and `IN_PROGRESS` job executions will be cancelled.
**Note**
To select an `endbehavior`, you must select an `endtime`
**Max duration**
The max duration of a scheduled job must be less than or equal to two years regardless of the `startTime` and `endTime`.
The following table lists common duration scenarios of a scheduled job:
| **Scheduled Job example number** | **startTime** | **endTime** | **Max duration** |
| --- | --- | --- | --- |
| 1 | Immediately after initial job creation. | One year after initial job creation. | One year |
| 2 | One month after initial job creation. | 13 months after initial job creation. | One year |
| 3 | One year after initial job creation. | Two years after initial job creation. | One year |
| 4 | Immediately after initial job creation. | Two years after initial job creation. | Two years |
#### Recurring maintenance window
The maintenance window is an optional configuration within the scheduling configuration of the AWS Management Console and `SchedulingConfig` within the `CreateJob` and `CreateJobTemplate` APIs. You can set up a recurring maintenance window with a predetermined start time, duration, and frequency (daily, weekly, or monthly) that the maintenance window occurs. Maintenance windows only apply to continuous jobs. The maximum duration of a recurring maintenance window is 23 hours, 50 minutes.
The following diagram illustrates the job status states for various scheduled job scenarios with an optional maintenance window:
![\[A diagram showing the lifecycle of a continuous job, progressing through states of SCHEDULED, IN_PROGRESS, CANCELLED, and DELETION_IN_PROGRESS upon certain events.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/job-states-diagram-scheduled-maintenance-window.png)
For more information about job status states, see [Jobs and job execution states](iot-jobs-lifecycle.md).
**Note**
If a job arrives at the `endTime` during a maintenance window, it will update from `IN_PROGRESS` to `COMPLETED`. Additionally, any remaining job executions will follow the `endBehavior` for the job.
**Cron expressions**
For scheduled jobs rolling out the job document during a maintenance window with a custom frequency, the custom frequency is entered using a cron expression. A cron expression has six required fields, which are separated by white space.
**Syntax**
```
cron(fields)
```
| **Field** | **Values** | **Wildcards** |
| --- | --- | --- |
| Minutes | 0-59 | , - \$1 / |
| Hours | 0-23 | , - \$1 / |
| Day-of-month | 1-31 | , - \$1 ? / L W |
| Month | 1-12 or JAN-DEC | , - \$1 / |
| Day-of-week | 1-7 or SUN-SAT | , - \$1 ? L \$1 |
| Year | 1970-2199 | , - \$1 / |
**Wildcards**
+ The **,** (comma) wildcard includes additional values. In the Month field, JAN,FEB,MAR would include January, February, and March.
+ The **-** (dash) wildcard specifies ranges. In the Day field, 1-15 would include days 1 through 15 of the specified month.
+ The **\$1** (asterisk) wildcard includes all values in the field. In the Hours field, **\$1** would include every hour. You can't use **\$1** in both the Day-of-month and Day-of-week fields. If you use it in one, you must use **?** in the other.
+ The **/** (forward slash) wildcard specifies increments. In the Minutes field, you could enter 1/10 to specify every tenth minute, starting from the first minute of the hour (for example, the 11th, 21st, and 31st minute, and so on).
+ The **?** (question mark) wildcard specifies one or another. In the Day-of-month field, you could enter **7** and if you didn't care what day of the week the 7th was, you could enter **?** in the Day-of-week field.
+ The **L** wildcard in the Day-of-month or Day-of-week fields specifies the last day of the month or week.
+ The **W** wildcard in the Day-of-month field specifies a weekday. In the Day-of-month field, **3W** specifies the weekday closest to the third day of the month.
+ The **\$1** wildcard in the Day-of-week field specifies a certain instance of the specified day of the week within a month. For example, 3\$12 would be the second Tuesday of the month: the 3 refers to Tuesday because it is the third day of each week, and the 2 refers to the second day of that type within the month.
**Note**
If you use a '\$1' character, you can define only one expression in the day-of-week field. For example, `"3#1,6#3"` isn't valid because it's interpreted as two expressions.
**Restrictions**
+ You can't specify the Day-of-month and Day-of-week fields in the same cron expression. If you specify a value (or a \$1) in one of the fields, you must use a **?**in the other.
**Examples**
Refer to the following sample cron strings when using a cron expression for the `startTime` of a recurring maintenance window.
| **Minutes** | **Hours** | **Day of month** | **Month** | **Day of week** | **Year** | **Meaning** |
| --- | --- | --- | --- | --- | --- | --- |
| 0 | 10 | \$1 | \$1 | ? | \$1 | Run at 10:00 am (UTC) every day |
| 15 | 12 | \$1 | \$1 | ? | \$1 | Run at 12:15 pm (UTC) every day |
| 0 | 18 | ? | \$1 | MON-FRI | \$1 | Run at 6:00 pm (UTC) every Monday through Friday |
| 0 | 8 | 1 | \$1 | ? | \$1 | Run at 8:00 am (UTC) every first day of the month |
#### Recurring maintenance window duration end logic
When a job rollout during a maintenance window reaches the end of the current maintenance window occurrence duration, the following actions will occur:
+ The Job will cease all rollouts of the job document to any remaining devices in your target group. It will resume at the `startTime` of the next maintenance window.
+ All job executions with a status of `QUEUED` will remain in `QUEUED` until the `startTime` of the next maintenance window occurrence. In the next window, they can switch to `IN_PROGRESS` when the device is ready to begin performing the actions specified in the job document.
+ All job executions with a status of `IN_PROGRESS` will continue performing the actions specified in the job document until they reach a terminal state. Any retry attempts as specified in `JobExecutionsRetryConfig` will take place at the `startTime` of the next maintenance window.
### Job abort configuration
Use this configuration to create a criteria to cancel a job when a threshold percentage of devices meet that criteria. For example, you can use this configuration to cancel a job in the following cases:
+ When a threshold percentage of devices don't receive the job execution notifications, such as when your device is incompatible for an Over-The-Air (OTA) update. In this case, your device can report a `REJECTED` status.
+ When a threshold percentage of devices report failure for their job executions, such as when your device encounters a disconnection when attempting to download the job document from an Amazon S3 URL. In such cases, your device must be programmed to report the `FAILURE` status to AWS IoT.
+ When a `TIMED_OUT` status is reported because the job execution times out for a threshold percentage of devices after the job executions have started.
+ When there are multiple retry failures. When you add a retry configuration, each retry attempt can incur additional charges to your AWS account. In such cases, canceling the job can cancel queued job executions and avoid retry attempts for these executions. For more information about the retry configuration and using it with the abort configuration, see [Job execution timeout and retry configurations](#job-timeout-retry).
You can set up a job abort condition by using the AWS IoT console or the AWS IoT Jobs API.
## Job execution timeout and retry configurations
Use the job execution timeout configuration to send you [Jobs notifications](jobs-comm-notifications.md) when a job execution has been in progress for longer than the set duration. Use the job execution retry configuration to retry the execution when the job fails or times out.
### Job execution timeout configuration
Use the job execution timeout configuration to notify you whenever a job execution gets stuck in the `IN_PROGRESS` state for an unexpectedly long period of time. When the job is `IN_PROGRESS`, you can monitor the progress of your job execution.
#### Timers for job timeouts
There are two types of timers: in-progress timers and step timers.
**In-progress timers**
When you create a job or a job template, you can specify a value for the in-progress timer that's between 1 minute and 7 days. You can update the value of this timer until the start of your job execution. After your timer starts, it can't be updated, and the timer value applies to all job executions for the job. Whenever a job execution remains in the `IN_PROGRESS` status for longer than this interval, the job execution fails and switches to the terminal `TIMED_OUT` status. AWS IoT also publishes an MQTT notification.
**Step timer**
You can also set a step timer that applies to only the job execution that you want to update. This timer has no effect on the in-progress timer. Each time you update a job execution, you can set a new value for the step timer. You can also create a new step timer when starting the next pending job execution for a thing. If the job execution remains in the `IN_PROGRESS` status for longer than the step timer interval, it fails and switches to the terminal `TIMED_OUT` status.
**Note**
You can set the in-progress timer by using the AWS IoT console or the AWS IoT Jobs API. To specify the step timer, use the API.
#### How timers work for job timeouts
The following illustrates the ways in which in-progress timeouts and step timeouts interact with each other in a 20-minute timeout period.
![\[A timeline showing an in-progress timer of 20 minutes with nested step timers of 7, 5, and 8 minutes.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/timeout-diagram.png)
The following shows the different steps:
1.
**12:00**
A new job is created and an in-progress timer for twenty minutes is started when creating a job. The in-progress timer starts to run and the job execution switches to `IN_PROGRESS` status.
1.
**12:05 PM**
A new step timer with a value of 7 minutes is created. The job execution will now time out at 12:12 PM.
1.
**12:10 PM**
A new step timer with a value of 5 minutes is created. When a new step timer is created, the previous step timer is discarded, and the job execution will now time out at 12:15 PM.
1.
**12:13 PM**
A new step timer with a value of 9 minutes is created. The previous step timer is discarded and the job execution will now time out at 12:20 PM because the in-progress timer times out at 12:20 PM. The step timer can't exceed the in-progress timer's absolute bound.
### Job execution retry configuration
You can use the retry configuration to retry the job execution when a certain set of criteria is met. A retry can be attempted when a job times out or when the device fails. To retry execution because of a timeout failure, you must enable the timeout configuration.
**How to use the retry configuration**
Use the following steps to retry the configuration:
1. Determine whether to use the retry configuration for `FAILED`, `TIMED_OUT`, or both failure criteria. For the `TIMED_OUT` status, after the status is reported, AWS IoT Jobs automatically retries the job execution for the device.
1. For the `FAILED` status, check whether your job execution failure can be retried. If it's retryable, program your device to report a `FAILURE` status to AWS IoT. The following section describes more about retryable and non-retryable failures.
1. Specify the number of retries to use for each failure type by using the preceding information. For a single device, you can specify up to 10 retries for both failure types combined. The retry attempts stop automatically when an execution succeeds or when it reaches the specified number of attempts.
1. Add an abort configuration to cancel the job if there are repeated retry failures to avoid additional charges from being incurred with a large number of retry attempts.
**Note**
When a job reaches the end of a recurring maintenance window occurrence, all `IN_PROGRESS` job executions will continue performing actions identified in the job document until they reach a terminal state. If a job execution reaches a terminal state of `FAILED` or `TIMED_OUT` outside of a maintenance window, a retry attempt will occur in the next window if the attempts aren't exhausted. At the `startTime` of the next maintenance window occurrence, a new job execution will be created and enter a status state of `QUEUED` until the device is ready to begin.
**Retry and abort configuration**
Each retry attempt incurs additional charges to your AWS account. To avoid incurring additional charges from repeated retry failures, we recommend adding an abort configuration. For more information about pricing, see [AWS IoT Device Management pricing](https://aws.amazon.com/iot-device-management/pricing/).
You might encounter multiple retry failures when a high threshold percentage of your devices either time out or report failure. In this case, you can use the abort configuration to cancel the job and avoid any queued job executions or further retry attempts.
**Note**
When the abort criteria is met for canceling a job execution, only `QUEUED` job executions are canceled. Any queued retries for the device will not be attempted. However, current job executions that have an `IN_PROGRESS` status will not be canceled.
Before retrying a failed job execution, we also recommend that you check whether your job execution failure is retryable, as described in the following section.
**Retry for failure type of `FAILED`**
To attempt retries for failure type of `FAILED`, your devices must be programmed to report the `FAILURE` status for a failed job execution to AWS IoT. Set the retry configuration with the criteria to retry `FAILED` job executions and specify the number of retries to be performed. When AWS IoT Jobs detects the `FAILURE` status, it will then automatically attempt to retry the job execution for the device. The retries continue until the job execution succeeds or when it reaches the maximum number of retry attempts.
You can track each retry attempt and the job that's running on these devices. By tracking the execution status, after the specified number of retries have been attempted, you can use your device to report failures and initiate another retry attempt.
**Retryable and non-retryable failures**
Your job execution failure can be retryable or non-retryable. Each retry attempt can incur charges to your AWS account. To avoid incurring additional charges from multiple retry attempts, first consider checking whether your job execution failure is retryable. An example of retryable failure includes a connection error that your device encounters while attempting to download the job document from an Amazon S3 URL. If your job execution failure is retryable, program your device to report a `FAILURE` status in case the job execution fails. Then, set the retry configuration to retry `FAILED` executions.
If the execution can't be retried, to avoid retrying and potentially incurring additional charges to your account, we recommend that you program the device to report a `REJECTED` status to AWS IoT. Examples of non-retryable failure include when your device is incompatible of receiving a job update, or when it experiences a memory error while executing a job. In these cases, AWS IoT Jobs will not retry the job execution because it retries the job execution only when it detects a `FAILED` or `TIMED_OUT` status.
After you've determined that a job execution failure is retryable, if a retry attempt still fails, consider checking the device logs.
**Note**
When a job with the optional scheduling configuration reaches its `endTime`, the selected `endBehavior` will stop the rollout of the job document to all remaining devices in the target group and dictate how to proceed with the remaining job executions. The attempts are retried if selected via the retry configuration.
**Retry for failure type of `TIMEOUT`**
If you enable timeout when creating a job, then AWS IoT Jobs will attempt to retry the job execution for the device when the status changes from `IN_PROGRESS` to `TIMED_OUT`. This status change can occur when the in-progress timer times out, or when a step timer that you specify is in `IN_PROGRESS` and then times out. The retries continue until the job execution succeeds, or when it reaches the maximum number of retry attempts for this failure type.
**Continuous jobs and thing group membership updates**
For continuous jobs that have a job status as `IN_PROGRESS`, the number of retry attempts is reset to zero when there are updates to a thing's group membership. For example, consider that you specified five retry attempts and three retries have already been performed. If a thing is now removed from the thing group and then rejoins the group, such as with dynamic thing groups, the number of retry attempts is reset to zero. You can now perform five retry attempts for your thing group instead of the two attempts that were remaining. In addition, when a thing is removed from the thing group, additional retry attempts are canceled.
# Specify additional configurations
When you create a job or job template, you can specify these additional configurations. The following shows when you can specify these configurations.
+ When creating a custom job template. The additional configuration settings that you specify will be saved when you create a job from the template.
+ When creating a custom job by using a job file. The job file can be a JSON file that's uploaded in an S3 bucket.
+ When creating a custom job by using a custom job template. If the template already has these settings specified, you can either reuse them or override them by specifying new configuration settings.
+ When creating a custom job by using an AWS managed template.
**Topics**
+ [
# Specify job configurations by using the AWS Management Console
](job-configurations-console.md)
+ [
# Specify job configurations by using the AWS IoT Jobs API
](job-configurations-api.md)
# Specify job configurations by using the AWS Management Console
Specify job configurations by using the console
You can add the different configurations for your job by using the AWS IoT console. After you've created a job, you can see the status details of your job configurations on the job details page. For more information about the different configurations and how they work, see [How job configurations work](jobs-configurations-details.md).
Add the job configurations when you create a job or a job template.
**When creating a custom job template**
To specify the rollout configuration when creating a custom job template
1. Go to the [Job templates hub of the AWS IoT console](https://console.aws.amazon.com/iot/home#/jobtemplatehub) and choose **Create job template**.
1. Specify the job template properties, provide the job document, expand the configuration that you want to add, and then specify the configuration parameters.
**When creating a custom job**
To specify the rollout configuration when creating a custom job
1. Go to the [Job hub of the AWS IoT console](https://console.aws.amazon.com/iot/home#/jobhub) and choose **Create job**.
1. Choose **Create a custom job** and specify the job properties, targets, and whether to use a job file or a template for the job document. You can use a custom template or an AWS managed template.
1. Choose the job configuration and then expand **Rollout configuration** to specify whether to use a **Constant rate** or **Exponential rate**. Then, specify the configuration parameters.
The next section shows the parameters that you can specify for each configuration.
## Rollout configuration
You can specify whether to use a constant rollout rate or an exponential rate.
+
**Set a constant rollout rate**
To set a constant rate for job executions, choose **Constant rate**, then specify the **Maximum per minute** for the upper limit of the rate. This value is optional and ranges from 1 to 1000. If you don't set it, it uses 1000 as the default value.
+
**Set an exponential rollout rate**
To set an exponential rate, choose **Exponential rate** and then specify these parameters:
+
**Base rate per minute**
The rate at which the jobs are executed until the **Number of notified devices** or **Number of succeeded devices** threshold is met for **Rate increase criteria**.
+
**Increment factor**
The exponential factor by which the rollout rate increases after the **Number of notified devices** or **Number of succeeded devices** threshold is met for **Rate increase criteria**.
+
**Rate increase criteria**
The threshold for either **Number of notified devices** or **Number of succeeded devices**.
## Abort configuration
Choose **Add new configuration** and specify the following parameters for each configuration:
+
**Failure type**
Specifies the failure types that initiate a job abort. These include **FAILED**, **REJECTED**, **TIMED\$1OUT**, or **ALL**.
+
**Increment factor**
Specifies the number of completed job executions that must occur before the job abort criteria has been met.
+
**Threshold percentage**
Specifies the total number of executed things that initiate a job abort.
## Scheduling configuration
Each job can start immediately upon initial creation, scheduled to start at a later date and time, or take place during a recurring maintenance window.
Choose **Add new configuration** and specify the following parameters for each configuration:
+
**Job start**
Specify the date and time when the job will start.
+
**Recurring maintenance window**
A recurring maintenance window defines the specific date and time that a job can deploy the job document to the target devices in the job. The maintenance window can repeat daily, weekly, monthly, or a custom day and time recurrence.
+
**Job end**
Specify the date and time when the job will end.
+
**Job end behavior**
Select an end behavior for all unfinished job executions when the job is over.
**Note**
When a job with the optional scheduling configuration and selected end time reaches the end time, the job stops the rollout to all remaining devices in the target group. It also leverages the selected end behavior on how to proceed with the remaining job executions and their retry attempts per the retry configuration.
## Timeout configuration
By default, there's no timeout and your job runs canceled or deleted. To use timeouts, choose **Enable timeout**, and then specify a timeout value between 1 minute and 7 days.
## Retry configuration
**Note**
After a job has been created, the number of retries can't be updated. You can only remove the retry configuration for all failure types. When you're creating a job, consider the appropriate number of retries to use for your configuration. To avoid incurring excess costs because of potential retry failures, add an abort configuration.
Choose **Add new configuration** and specify the following parameters for each configuration:
+
**Failure type**
Specifies the failure types that should trigger a job execution retry. These include **Failed**, **Timeout**, and **All**.
+
**Number of retries**
Specifies the number of retries for the chosen **Failure type**. For both failure types combined, up to 10 retries can be attempted.
# Specify job configurations by using the AWS IoT Jobs API
Specify job configurations using the API
You can use the [CreateJob](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) or the [CreateJobTemplate](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) API to specify the different job configurations. The following sections describe how to add these configurations. After you've added the configurations, you can use [JobExecutionSummary](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html) and [JobExecutionSummaryForJob](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummaryForJob.html) to view their status.
For more information about the different configurations and how they work, see [How job configurations work](jobs-configurations-details.md).
## Rollout configuration
You can specify a constant rollout rate or an exponential rollout rate for your rollout configuration.
+
**Set a constant rollout rate**
To set a constant rollout rate, use the [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionsRolloutConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionsRolloutConfig.html) object to add the `maximumPerMinute` parameter to the `CreateJob` request. This parameter specifies the upper limit of the rate at which job executions can occur. This value is optional and ranges from 1 to 1000. If you don't set the value, it uses 1000 as the default value.
```
"jobExecutionsRolloutConfig": {
"maximumPerMinute": 1000
}
```
+
**Set an exponential rollout rate**
To set a variable job rollout rate, use the [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionsRolloutConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionsRolloutConfig.html) object. You can configure the `ExponentialRolloutRate`property when you run the `CreateJob` API operation. The following example sets an exponential rollout rate by using the `exponentialRate` parameter. For more information about the parameters, see [https://docs.aws.amazon.com/iot/latest/apireference/API_ExponentialRolloutRate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ExponentialRolloutRate.html).
```
{
...
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": 50,
"incrementFactor": 2,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": 1000,
"numberOfSucceededThings": 1000
},
"maximumPerMinute": 1000
}
}
...
}
```
Where the parameter:
**baseRatePerMinute**
Specifies the rate at which the jobs are executed until the `numberOfNotifiedThings` or `numberOfSucceededThings` threshold has been met.
**incrementFactor**
Specifies the exponential factor by which the rollout rate increases after the `numberOfNotifiedThings` or `numberOfSucceededThings` threshold has been met.
**rateIncreaseCriteria**
Specifies either the `numberOfNotifiedThings` or `numberOfSucceededThings` threshold.
## Abort configuration
To add this configuration by using the API, specify the [https://docs.aws.amazon.com/iot/latest/apireference/API_AbortConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_AbortConfig.html) parameter when you run the [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html), or the [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) API operation. The following example shows an abort configuration for a job rollout that was experiencing multiple failed executions, as specified with the `CreateJob` API operation.
**Note**
Deleting a job execution affects the computation value of the total completed execution. When a job aborts, the service creates an automated `comment` and `reasonCode` to differentiate a user-driven cancellation from a job abort cancellation.
```
"abortConfig": {
"criteriaList": [
{
"action": "CANCEL",
"failureType": "FAILED",
"minNumberOfExecutedThings": 100,
"thresholdPercentage": 20
},
{
"action": "CANCEL",
"failureType": "TIMED_OUT",
"minNumberOfExecutedThings": 200,
"thresholdPercentage": 50
}
]
}
```
Where the parameter:
**action**
Specifies the action to take when the abort criteria has been met. This parameter is required, and `CANCEL` is the only valid value.
**failureType**
Specifies which failure types should initiate a job abort. Valid values are `FAILED`, `REJECTED`, `TIMED_OUT`, and `ALL`.
**minNumberOfExecutedThings**
Specifies the number of completed job executions that must occur before the job abort criteria has been met. In this example, AWS IoT doesn't check to see if a job abort should occur until at least 100 devices have completed job executions.
**thresholdPercentage**
Specifies the total number of things for which jobs are executed that can initiate a job abort. In this example, AWS IoT checks sequentially and initiates a job abort if the threshold percentage is met. If at least 20% of the complete executions failed after 100 executions are complete, it cancels the job rollout. If this criteria isn't met, AWS IoT then checks if at least 50% of completed executions timed out after 200 executions are complete. If this is the case, it cancels the job rollout.
## Scheduling configuration
To add this configuration by using the API, specify the optional [https://docs.aws.amazon.com/iot/latest/apireference/API_SchedulingConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_SchedulingConfig.html) when you run the [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html), or the [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) API operation.
```
"SchedulingConfig": {
"endBehavior": string
"endTime": string
"maintenanceWindows": string
"startTime": string
}
```
Where the parameter:
**startTime**
Specifies the date and time when the job will start.
**endTime**
Specifies the date and time when the job will end.
**maintenanceWindows**
Specifies if an optional maintenance window was selected for the scheduled job to rollout the job document to all devices in the target group. The string format for `maintenanceWindow` is YYYY/MM/DD for the date and hh:mm for the time.
**endBehavior**
Specifies the job behavior for a scheduled job upon reaching the `endTime`.
**Note**
The optional `SchedulingConfig` for a job is viewable in the [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJob.html) and [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobTemplate.html) APIs.
## Timeout configuration
To add this configuration by using the API, specify the [https://docs.aws.amazon.com/iot/latest/apireference/API_TimeoutConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_TimeoutConfig.html) parameter when you run the [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html), or the [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) API operation.
To use the timeout configuration
1. To set the in-progress timer when you're creating a job or job template, set a value for the `inProgressTimeoutInMinutes` property of the optional [TimeoutConfig](https://docs.aws.amazon.com//iot/latest/apireference/API_TimeoutConfig.html) object.
```
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
```
1. To specify a step timer for a job execution, set a value for `stepTimeoutInMinutes` when you call [UpdateJobExecution](https://docs.aws.amazon.com//iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html). The step timer applies only to the job execution that you update. You can set a new value for this timer each time you update a job execution.
**Note**
`UpdateJobExecution` can discard a step timer that's already been created by creating a new step timer with a value of -1.
```
{
...
"statusDetails": {
"string" : "string"
},
"stepTimeoutInMinutes": number
}
```
1. To create a new step timer, you can also call the [StartNextPendingJobExecution](https://docs.aws.amazon.com//iot/latest/apireference/API_iot-jobs-data_StartNextPendingJobExecution.html) API operation.
## Retry configuration
**Note**
When you're creating a job, consider the appropriate number of retries to use for your configuration. To avoid incurring excess costs because of potential retry failures, add an abort configuration. After a job has been created, the number of retries can't be updated. You can only set the number of retries to 0 by using the [UpdateJob](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateJob.html) API operation.
To add this configuration by using the API, specify the [https://docs.aws.amazon.com/iot/latest/apireference/API_jobExecutionsRetryConfig.html](https://docs.aws.amazon.com/iot/latest/apireference/API_jobExecutionsRetryConfig.html) parameter when you run the [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html), or the [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) API operation.
```
{
...
"jobExecutionsRetryConfig": {
"criteriaList": [
{
"failureType": "string",
"numberOfRetries": number
}
]
}
...
}
```
Where **criteriaList** is an array specifying the list of criteria that determines the number of retries permitted for each failure type for a job.
# Devices and jobs
Devices can communicate with AWS IoT Jobs using MQTT, HTTP Signature Version 4, or HTTP TLS. To determine the endpoint to use when your device communicates with AWS IoT Jobs, run the **DescribeEndpoint** command. For example, if you run this command:
```
aws iot describe-endpoint --endpoint-type iot:Data-ATS
```
you get a result similar to the following:
```
{
"endpointAddress": "a1b2c3d4e5f6g7-ats.iot.us-west-2.amazonaws.com"
}
```
## Using the MQTT protocol
Devices can communicate with AWS IoT Jobs using MQTT protocol. Devices subscribe to MQTT topics to be notified of new jobs and to receive responses from the AWS IoT Jobs service. Devices publish on MQTT topics to query or update the state of a job launch. Each device has its own general MQTT topic. For more information about publishing and subscribing to MQTT topics, see [Device communication protocols](protocols.md).
With this method of communication, your device uses its device-specific certificate and private key to authenticate with AWS IoT Jobs.
Your devices can subscribe to the following topics. `thing-name` is the name of the thing associated with the device.
+
**`$aws/things/thing-name/jobs/notify`**
Subscribe to this topic to notify you when a job launch is added or removed from the list of pending job launches.
+
**`$aws/things/thing-name/jobs/notify-next`**
Subscribe to this topic to notify you when the next pending job execution has changed.
+
**`$aws/things/thing-name/jobs/request-name/accepted`**
The AWS IoT Jobs service publishes success and failure messages on an MQTT topic. The topic is formed by appending `accepted` or `rejected` to the topic used to make the request. Here, `request-name` is the name of a request such as `Get` and the topic can be: `$aws/things/myThing/jobs/get`. AWS IoT Jobs then publishes success messages on the `$aws/things/myThing/jobs/get/accepted` topic.
+
**`$aws/things/thing-name/jobs/request-name/rejected`**
Here, `request-name` is the name of a request such as `Get`. If the request failed, AWS IoT Jobs publishes failure messages on the `$aws/things/myThing/jobs/get/rejected` topic.
You can also use the following HTTPS API operations:
+ Update the status of a job execution by calling the [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html) API.
+ Query the status of a job execution by calling the [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html) API.
+ Retrieve a list of pending job executions by calling the [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html) API.
+ Retrieve the next pending job execution by calling the [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html) API with `jobId` as `$next`.
+ Get and start the next pending job execution by calling the [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_StartNextPendingJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_StartNextPendingJobExecution.html) API.
## Using HTTP Signature Version 4
Devices can communicate with AWS IoT Jobs using HTTP Signature Version 4 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](https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/index.html) or [AWS SDKs and Tools](http://aws.amazon.com/tools/#sdk) and refer to the IotJobsDataPlane section for your preferred language.
With this method of communication, your device uses IAM credentials to authenticate with AWS IoT Jobs.
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
Devices can communicate with AWS IoT Jobs using HTTP TLS on port 8443 using a third-party software client that supports this protocol.
With this method, your device uses X.509 certificate-based authentication (for example, 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 the AWS IoT Jobs service. Or, you could use the corresponding API or CLI commands. For these examples, we assume a device called `MyThing` that 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're 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. For more information about verifying a code file signature, see [Device Agent Sample](https://github.com/aws/aws-iot-device-sdk-js#jobsAgent).
**Topics**
+ [
## Programming devices to work with jobs
](#programming-devices)
+ [
# Device workflow
](jobs-workflow-device-online.md)
+ [
# Jobs workflow
](jobs-workflow-jobs-online.md)
+ [
# Jobs notifications
](jobs-comm-notifications.md)
# Device workflow
A device can handle jobs that it runs using either of the following ways.
+
**Get the next job**
1. When a device first comes online, it should subscribe to the device's `notify-next` topic.
1. Call the [DescribeJobExecution](jobs-mqtt-api.md#mqtt-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.
1. Call the [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution) MQTT API to update the job status. Or, to combine this and the previous step in one call, the device can call [StartNextPendingJobExecution](jobs-mqtt-api.md#mqtt-startnextpendingjobexecution).
1. (Optional) You can add a step timer by setting a value for `stepTimeoutInMinutes` when you call either [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution) or [StartNextPendingJobExecution](jobs-mqtt-api.md#mqtt-startnextpendingjobexecution).
1. Perform the actions specified by the job document using the [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution) MQTT API to report on the progress of the job.
1. Continue to monitor the job execution by calling the [DescribeJobExecution](jobs-mqtt-api.md#mqtt-describejobexecution) MQTT API with this jobId. If the job execution is deleted, [DescribeJobExecution](jobs-mqtt-api.md#mqtt-describejobexecution) returns a `ResourceNotFoundException`.
The device should be able to recover to a valid state if the job execution is canceled or deleted while the device is running the job.
1. Call the [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution) MQTT API when finished with the job to update the job status and report success or failure.
1. 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 notifications of the next pending job execution. This includes 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.
+
**Select from available jobs**
1. When a device first comes online, it should subscribe to the thing's `notify` topic.
1. Call the [GetPendingJobExecutions](jobs-mqtt-api.md#mqtt-getpendingjobexecutions) MQTT API to get a list of pending job executions.
1. If the list contains one or more job executions, select one.
1. Call the [DescribeJobExecution](jobs-mqtt-api.md#mqtt-describejobexecution) MQTT API to get the job document and other details, including any state saved in `statusDetails`.
1. Call the [UpdateJobExecution](jobs-mqtt-api.md#mqtt-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.
1. Optionally, you can add a step timer by setting a value for `stepTimeoutInMinutes` when you call [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution).
1. Perform the actions specified by the job document using the [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution) MQTT API to report on the progress of the job.
1. Continue to monitor the job execution by calling the [DescribeJobExecution](jobs-mqtt-api.md#mqtt-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 able to recover to a valid state.
1. Call the [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution) MQTT API when finished with the job to update the job status and to report success or failure.
If the device remains online, it is notified of all pending job executions when 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 carry out the job, it should call the [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution) MQTT API to update the job status to `REJECTED`.
# Jobs workflow
The following shows the different steps in the jobs workflow from starting a new job to reporting the completion status of a job execution.
## Start a new job
When a new job is created, AWS IoT Jobs publishes a message on the `$aws/things/thing-name/jobs/notify` topic for each target device.
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.
**Note**
For jobs with the optional `SchedulingConfig`, the job will maintain an initial status state of `SCHEDULED`. When the job reaches the selected `startTime`, the following will occur:
The job status state will update to `IN_PROGRESS`.
The job will begin rollout of the job document to all devices in the target group.
## Get job information
To get more information about a job execution, the device calls the [DescribeJobExecution](jobs-mqtt-api.md#mqtt-describejobexecution) MQTT API with the `includeJobDocument` field set to `true` (the default).
If the request is successful, the AWS IoT Jobs service publishes a message on the `$aws/things/MyThing/jobs/0023/get/accepted` topic:
```
{
"clientToken" : "client-001",
"timestamp" : 1489097434407,
"execution" : {
"approximateSecondsBeforeTimedOut": number,
"jobId" : "023",
"status" : "QUEUED",
"queuedAt" : 1489097374841,
"lastUpdatedAt" : 1489097374841,
"versionNumber" : 1,
"jobDocument" : {
< contents of job document >
}
}
}
```
If the request fails, the AWS IoT Jobs service publishes a message on the `$aws/things/MyThing/jobs/0023/get/rejected` topic.
The device now has the job document that it can use 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.
## Report job execution status
As the device is executing the job, it can call the [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution) MQTT API to update the status of the job execution.
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 respond 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](jobs-mqtt-api.md#mqtt-startnextpendingjobexecution). That 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.
If the job contains a [TimeoutConfig](https://docs.aws.amazon.com//iot/latest/apireference/API_TimeoutConfig.html), the in-progress timer starts running. You can also set a step timer for a job execution by setting a value for `stepTimeoutInMinutes` when you call [UpdateJobExecution](https://docs.aws.amazon.com//iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html). The step timer applies only to the job execution that you update. You can set a new value for this timer each time you update a job execution. You can also create a step timer when you call [StartNextPendingJobExecution](https://docs.aws.amazon.com//iot/latest/apireference/API_iot-jobs-data_StartNextPendingJobExecution.html). If the job execution remains in the `IN_PROGRESS` status for longer than the step timer interval, it fails and switches to the terminal `TIMED_OUT` status. The step timer has no effect on the in-progress timer that you set when you create a job.
The `status` field can be set to `IN_PROGRESS`, `SUCCEEDED`, or `FAILED`. You cannot update the status of a job execution that is already in a terminal state.
## Report execution completed
When the device is finished executing the job, it calls the [UpdateJobExecution](jobs-mqtt-api.md#mqtt-updatejobexecution) MQTT API. If the job was successful, set `status` to `SUCCEEDED` and, in the message payload, in `statusDetails`, add other information about the job as name-value pairs. The in-progress and step timers end when the job execution is complete.
For example:
```
{
"status":"SUCCEEDED",
"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 the AWS IoT Jobs service receives this update, it publishes a message on the `$aws/things/MyThing/jobs/notify` topic to indicate that the job execution is complete:
```
{
"timestamp":1476290692776,
"jobs":{}
}
```
## 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`.
For example:
```
{
"timestamp":1476290692776,
"jobs":{
"QUEUED":[{
"jobId":"0002",
"queuedAt":1476290646230,
"lastUpdatedAt":1476290646230
}],
"IN_PROGRESS":[{
"jobId":"0003",
"queuedAt":1476290646230,
"lastUpdatedAt":1476290646230
}]
}
}
```
# 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 track pending jobs by subscribing to these topics.
## Job notification types
Job notifications are published to MQTT topics as JSON payloads. There are two kinds of notifications:
**ListNotification**
A `ListNotification` contains a list of no more than 15 pending job executions. 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`).
For more information about the limits with and without the scheduling configuration, see [Job executions limits](job-limits.md#job-execution-limits).
**NextNotification**
+ A `NextNotification` contains summary information about the job execution that's 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's the first one in the list.
+ The status of an existing job execution that wasn't 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.
For more information about publishing and subscribing to MQTT topics, see [Device communication protocols](protocols.md).
**Note**
Notifications are not available when you use HTTP Signature Version 4 or HTTP TLS to communicate with jobs.
## Job pending
The AWS IoT Jobs service publishes a message on an MQTT topic when a job is added to or removed from the list of pending job executions for a thing or the first job execution in the list changes:
+ `$aws/things/thingName/jobs/notify`
+ `$aws/things/thingName/jobs/notify-next`
The messages contain the following example payloads:
`$aws/things/thingName/jobs/notify`:
```
{
"timestamp" : 10011,
"jobs" : {
"IN_PROGRESS" : [ {
"jobId" : "other-job",
"queuedAt" : 10003,
"lastUpdatedAt" : 10009,
"executionNumber" : 1,
"versionNumber" : 1
} ],
"QUEUED" : [ {
"jobId" : "this-job",
"queuedAt" : 10011,
"lastUpdatedAt" : 10011,
"executionNumber" : 1,
"versionNumber" : 0
} ]
}
}
```
If the job execution called `this-job` originated from a job with the optional scheduling configuration selected and the job document rollout scheduled to take place during a maintenance window, it'll only appear during a recurring maintenance window. Outside of a maintenance window, the job called `this-job` will be excluded from the list of pending job executions as shown in the following example.
```
{
"timestamp" : 10011,
"jobs" : {
"IN_PROGRESS" : [ {
"jobId" : "other-job",
"queuedAt" : 10003,
"lastUpdatedAt" : 10009,
"executionNumber" : 1,
"versionNumber" : 1
} ],
"QUEUED" : []
}
}
```
`$aws/things/thingName/jobs/notify-next`:
```
{
"timestamp" : 10011,
"execution" : {
"jobId" : "other-job",
"status" : "IN_PROGRESS",
"queuedAt" : 10009,
"lastUpdatedAt" : 10009,
"versionNumber" : 1,
"executionNumber" : 1,
"jobDocument" : {"c":"d"}
}
}
```
If the job execution called `other-job` originated from a job with the optional scheduling configuration selected and the job document rollout scheduled to take place during a maintenance window, it'll only appear during a recurring maintenance window. Outside of a maintenance window, the job called `other-job` won't be listed as the next job execution as shown in the following example.
```
{} //No other pending jobs
```
```
{
"timestamp" : 10011,
"execution" : {
"jobId" : "this-job",
"queuedAt" : 10011,
"lastUpdatedAt" : 10011,
"executionNumber" : 1,
"versionNumber" : 0,
"jobDocument" : {"a":"b"}
}
} // "this-job" is pending next to "other-job"
```
Possible job execution status values are `QUEUED`, `IN_PROGRESS`, `FAILED`, `SUCCEEDED`, `CANCELED`, `TIMED_OUT`, `REJECTED`, and `REMOVED`.
The following series of examples show the published notifications to each topic as job executions are created and changed from one state to another.
First, one job, called `job1`, is created. This notification is published to the `jobs/notify` topic:
```
{
"timestamp": 1517016948,
"jobs": {
"QUEUED": [
{
"jobId": "job1",
"queuedAt": 1517016947,
"lastUpdatedAt": 1517016947,
"executionNumber": 1,
"versionNumber": 1
}
]
}
}
```
This notification is published to the `jobs/notify-next` topic:
```
{
"timestamp": 1517016948,
"execution": {
"jobId": "job1",
"status": "QUEUED",
"queuedAt": 1517016947,
"lastUpdatedAt": 1517016947,
"versionNumber": 1,
"executionNumber": 1,
"jobDocument": {
"operation": "test"
}
}
}
```
When another job is created (`job2`), this notification is published to the `jobs/notify` topic:
```
{
"timestamp": 1517017192,
"jobs": {
"QUEUED": [
{
"jobId": "job1",
"queuedAt": 1517016947,
"lastUpdatedAt": 1517016947,
"executionNumber": 1,
"versionNumber": 1
},
{
"jobId": "job2",
"queuedAt": 1517017191,
"lastUpdatedAt": 1517017191,
"executionNumber": 1,
"versionNumber": 1
}
]
}
}
```
A notification is not published to the `jobs/notify-next` topic because the next job in the queue (`job1`) has not changed. When `job1` starts to execute, its status changes to `IN_PROGRESS`. No notifications are published because the list of jobs and the next job in the queue have not changed.
When a third job (`job3`) is added, this notification is published to the `jobs/notify` topic:
```
{
"timestamp": 1517017906,
"jobs": {
"IN_PROGRESS": [
{
"jobId": "job1",
"queuedAt": 1517016947,
"lastUpdatedAt": 1517017472,
"startedAt": 1517017472,
"executionNumber": 1,
"versionNumber": 2
}
],
"QUEUED": [
{
"jobId": "job2",
"queuedAt": 1517017191,
"lastUpdatedAt": 1517017191,
"executionNumber": 1,
"versionNumber": 1
},
{
"jobId": "job3",
"queuedAt": 1517017905,
"lastUpdatedAt": 1517017905,
"executionNumber": 1,
"versionNumber": 1
}
]
}
}
```
A notification is not published to the `jobs/notify-next` topic because the next job in the queue is still `job1`.
When `job1` is complete, its status changes to `SUCCEEDED`, and this notification is published to the `jobs/notify` topic:
```
{
"timestamp": 1517186269,
"jobs": {
"QUEUED": [
{
"jobId": "job2",
"queuedAt": 1517017191,
"lastUpdatedAt": 1517017191,
"executionNumber": 1,
"versionNumber": 1
},
{
"jobId": "job3",
"queuedAt": 1517017905,
"lastUpdatedAt": 1517017905,
"executionNumber": 1,
"versionNumber": 1
}
]
}
}
```
At this point, `job1` has been removed from the queue, and the next job to be executed is `job2`. This notification is published to the `jobs/notify-next` topic:
```
{
"timestamp": 1517186269,
"execution": {
"jobId": "job2",
"status": "QUEUED",
"queuedAt": 1517017191,
"lastUpdatedAt": 1517017191,
"versionNumber": 1,
"executionNumber": 1,
"jobDocument": {
"operation": "test"
}
}
}
```
If `job3` must begin executing before `job2` (which is not recommended), the status of `job3` can be changed to `IN_PROGRESS`. If this happens, `job2` is no longer next in the queue, and this notification is published to the `jobs/notify-next` topic:
```
{
"timestamp": 1517186779,
"execution": {
"jobId": "job3",
"status": "IN_PROGRESS",
"queuedAt": 1517017905,
"startedAt": 1517186779,
"lastUpdatedAt": 1517186779,
"versionNumber": 2,
"executionNumber": 1,
"jobDocument": {
"operation": "test"
}
}
}
```
No notification is published to the `jobs/notify` topic because no job has been added or removed.
If the device rejects `job2` and updates its status to `REJECTED`, this notification is published to the `jobs/notify` topic:
```
{
"timestamp": 1517189392,
"jobs": {
"IN_PROGRESS": [
{
"jobId": "job3",
"queuedAt": 1517017905,
"lastUpdatedAt": 1517186779,
"startedAt": 1517186779,
"executionNumber": 1,
"versionNumber": 2
}
]
}
}
```
If `job3` (which is still in progress) is force deleted, this notification is published to the `jobs/notify` topic:
```
{
"timestamp": 1517189551,
"jobs": {}
}
```
At this point, the queue is empty. This notification is published to the `jobs/notify-next` topic:
```
{
"timestamp": 1517189551
}
```
# AWS IoT jobs API operations
AWS IoT Jobs API can be used for either of the following categories:
+ Administrative tasks such as management and control of jobs. This is the *control plane*.
+ Devices carrying out those jobs. This is the *data plane*, which permits you to send and receive data.
Job management and control uses an HTTPS protocol API. Devices can use either an MQTT or an HTTPS protocol API. The control plane API is designed for a low volume of calls typical when creating and tracking jobs. It usually opens a connection for a single request, and then closes the connection after the response is received. The data plane HTTPS and MQTT API permit long polling. These API operations are designed for large amounts of traffic that can scale to millions of devices.
Each AWS IoT Jobs HTTPS API has a corresponding command that permits you to call the API from the AWS Command Line Interface (AWS CLI). The commands are lowercase, with hyphens between the words that make up the name of the API. For example, you can invoke the `CreateJob` API on the CLI by typing:
```
aws iot create-job ...
```
If an error occurs during an operation, you get an error response that contains information about the error.
## ErrorResponse
Contains information about an error that occurred during an AWS IoT Jobs service operation.
The following example shows the syntax of this operation:
```
{
"code": "ErrorCode",
"message": "string",
"clientToken": "string",
"timestamp": timestamp,
"executionState": JobExecutionState
}
```
The following is a description of this `ErrorResponse`:
`code`
ErrorCode can be set to:
InvalidTopic
The request was sent to a topic in the AWS IoT Jobs namespace that doesn't map to any API operation.
InvalidJson
The contents of the request couldn't be interpreted as valid UTF-8-encoded JSON.
InvalidRequest
The contents of the request were not valid. For example, this code is returned when an `UpdateJobExecution` request contains invalid status details. The message contains details about the error.
InvalidStateTransition
An update attempted to change the job execution to a state that is not valid because of the job execution's current state. For example, an attempt to change a request in state SUCCEEDED to state IN\$1PROGRESS. In this case, the body of the error message also contains the `executionState` field.
ResourceNotFound
The `JobExecution` specified by the request topic doesn't exist.
VersionMismatch
The expected version specified in the request doesn't match the version of the job execution in the AWS IoT Jobs service. In this case, the body of the error message also contains the `executionState` field.
InternalError
There was an internal error during the processing of the request.
RequestThrottled
The request was throttled.
TerminalStateReached
Occurs when a command to describe a job is performed on a job that is in a terminal state.
`message`
An error message string.
`clientToken`
An arbitrary string used to correlate a request with its reply.
`timestamp`
The time, in seconds since the epoch.
`executionState`
A [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionState.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionState.html) object. This field is included only when the `code` field has the value `InvalidStateTransition` or `VersionMismatch`. This makes it unnecessary in these cases to perform a separate `DescribeJobExecution` request to obtain the current job execution status data.
**Topics**
+ [
# Jobs management and control API and data types
](jobs-management-control-api.md)
+ [
# Jobs device MQTT and HTTPS API operations and data types
](jobs-mqtt-https-api.md)
# Jobs management and control API and data types
**Topics**
+ [
## Job management and control data types
](#jobs-control-plane-data-types)
+ [
## Job management and control API operations
](#jobs-http-api)
To determine the *endpoint-url* parameter for your CLI commands, run this command.
```
aws iot describe-endpoint --endpoint-type=iot:Jobs
```
This command returns the following output.
```
{
"endpointAddress": "account-specific-prefix.jobs.iot.aws-region.amazonaws.com"
}
```
**Note**
The Jobs endpoint doesn't support ALPN `x-amzn-http-ca`.
If you're using dual-stack endpoints (IPv6 and IPv6), use the `iot:Data-ATS` endpoint. The `iot:Jobs` endpoint supports only IPv4.
## Job management and control data types
The following data types are used by management and control applications to communicate with AWS IoT Jobs.
### Job
The `Job` object contains details about a job. The following example shows the syntax:
```
{
"jobArn": "string",
"jobId": "string",
"status": "IN_PROGRESS|CANCELED|SUCCEEDED",
"forceCanceled": boolean,
"targetSelection": "CONTINUOUS|SNAPSHOT",
"comment": "string",
"targets": ["string"],
"description": "string",
"createdAt": timestamp,
"lastUpdatedAt": timestamp,
"completedAt": timestamp,
"jobProcessDetails": {
"processingTargets": ["string"],
"numberOfCanceledThings": long,
"numberOfSucceededThings": long,
"numberOfFailedThings": long,
"numberOfRejectedThings": long,
"numberOfQueuedThings": long,
"numberOfInProgressThings": long,
"numberOfRemovedThings": long,
"numberOfTimedOutThings": long
},
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"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
}
]
},
"SchedulingConfig": {
"startTime": string
"endTime": string
"timeZone": string
"endTimeBehavior": string
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": long
}
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_Job.html](https://docs.aws.amazon.com/iot/latest/apireference/API_Job.html) or [https://docs.aws.amazon.com/cli/latest/reference/iot/job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job.html).
### JobSummary
The `JobSummary` object contains a job summary. The following example shows the syntax:
```
{
"jobArn": "string",
"jobId": "string",
"status": "IN_PROGRESS|CANCELED|SUCCEEDED|SCHEDULED",
"targetSelection": "CONTINUOUS|SNAPSHOT",
"thingGroupId": "string",
"createdAt": timestamp,
"lastUpdatedAt": timestamp,
"completedAt": timestamp
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_JobSummary.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobSummary.html) or [https://docs.aws.amazon.com/cli/latest/reference/iot/job-summary.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job-summary.html).
### JobExecution
The `JobExecution` object represents the execution of a job on a device. The following example shows the syntax:
**Note**
When you use the control plane API operations, the `JobExecution` data type doesn't contain a `JobDocument` field. To obtain this information, you can use the [https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html) API operation or the [https://docs.aws.amazon.com/cli/latest/reference/get-job-document.html](https://docs.aws.amazon.com/cli/latest/reference/get-job-document.html) CLI command.
```
{
"approximateSecondsBeforeTimedOut": 50,
"executionNumber": 1234567890,
"forceCanceled": true|false,
"jobId": "string",
"lastUpdatedAt": timestamp,
"queuedAt": timestamp,
"startedAt": timestamp,
"status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED",
"forceCanceled": boolean,
"statusDetails": {
"detailsMap": {
"string": "string" ...
},
"status": "string"
},
"thingArn": "string",
"versionNumber": 123
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html) or [https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution.html).
### JobExecutionSummary
The `JobExecutionSummary` object contains job execution summary information. The following example shows the syntax:
```
{
"executionNumber": 1234567890,
"queuedAt": timestamp,
"lastUpdatedAt": timestamp,
"startedAt": timestamp,
"status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED"
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html) or [https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary.html).
### JobExecutionSummaryForJob
The `JobExecutionSummaryForJob` object contains a summary of information about job executions for a specific job. The following example shows the syntax:
```
{
"executionSummaries": [
{
"thingArn": "arn:aws:iot:us-west-2:123456789012:thing/MyThing",
"jobExecutionSummary": {
"status": "IN_PROGRESS",
"lastUpdatedAt": 1549395301.389,
"queuedAt": 1541526002.609,
"executionNumber": 1
}
},
...
]
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummaryForJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummaryForJob.html) or [https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary-for-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary-for-job.html).
### JobExecutionSummaryForThing
The `JobExecutionSummaryForThing` object contains a summary of information about a job execution on a specific thing. FThe following example shows the syntax:
```
{
"executionSummaries": [
{
"jobExecutionSummary": {
"status": "IN_PROGRESS",
"lastUpdatedAt": 1549395301.389,
"queuedAt": 1541526002.609,
"executionNumber": 1
},
"jobId": "MyThingJob"
},
...
]
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummaryForThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummaryForThing.html) or [https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary-for-thing.html](https://docs.aws.amazon.com/cli/latest/reference/iot/job-execution-summary-for-thing.html).
## Job management and control API operations
Use the following API operations or CLI commands:
### AssociateTargetsWithJob
Associates a group with a continuous job. The following criteria must be met:
+ The job must have been created with the `targetSelection` field set to `CONTINUOUS`.
+ The job status must currently be `IN_PROGRESS`.
+ The total number of targets associated with a job must not exceed 100.
------
#### [ HTTPS request ]
```
POST /jobs/jobId/targets
{
"targets": [ "string" ],
"comment": "string"
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_AssociateTargetsWithJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_AssociateTargetsWithJob.html).
------
#### [ CLI syntax ]
```
aws iot associate-targets-with-job \
--targets \
--job-id \
[--comment ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"targets": [
"string"
],
"jobId": "string",
"comment": "string"
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/associate-targets-with-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/associate-targets-with-job.html).
------
### CancelJob
Cancels a job.
------
#### [ HTTPS request ]
```
PUT /jobs/jobId/cancel
{
"force": boolean,
"comment": "string",
"reasonCode": "string"
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJob.html).
------
#### [ CLI syntax ]
```
aws iot cancel-job \
--job-id \
[--force ] \
[--comment ] \
[--reasonCode ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"force": boolean,
"comment": "string"
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/cancel-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/cancel-job.html).
------
### CancelJobExecution
Cancels a job execution on a device.
------
#### [ HTTPS request ]
```
PUT /things/thingName/jobs/jobId/cancel
{
"force": boolean,
"expectedVersion": "string",
"statusDetails": {
"string": "string"
...
}
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJobExecution.html).
------
#### [ CLI syntax ]
```
aws iot cancel-job-execution \
--job-id \
--thing-name \
[--force | --no-force] \
[--expected-version ] \
[--status-details ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"thingName": "string",
"force": boolean,
"expectedVersion": long,
"statusDetails": {
"string": "string"
}
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/cancel-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot/cancel-job-execution.html).
------
### CreateJob
Creates a job. You can provide the job document as a link to a file in an Amazon S3 bucket (`documentSource` parameter), or in the body of the request (`document` parameter).
A job can be made *continuous* by setting the optional `targetSelection` parameter to `CONTINUOUS` (the default is `SNAPSHOT`). A continuous job can be used to onboard or upgrade devices as they are added to a group because it continues to run and is launched on newly added things. This can occur even after the things in the group at the time the job was created have completed the job.
A job can have an optional [TimeoutConfig](https://docs.aws.amazon.com//iot/latest/apireference/API_TimeoutConfig.html), which sets the value of the in-progress timer. The in-progress timer can't be updated and applies to all executions of the job.
The following validations are performed on arguments to the `CreateJob` API:
+ The `targets` argument must be a list of valid thing or thing group ARNs. All things and thing groups must be in your AWS account.
+ The `documentSource` argument must be a valid Amazon S3 URL to a job document. Amazon S3 URLs are in the form: `https://s3.amazonaws.com/bucketName/objectName`.
+ The document stored in the URL specified by the `documentSource` argument must be a UTF-8 encoded JSON document.
+ The size of a job document is limited to 32 KB due to the limit on the size of an MQTT message (128 KB) and encryption.
+ The `jobId` must be unique in your AWS account.
------
#### [ HTTPS request ]
```
PUT /jobs/jobId
{
"targets": [ "string" ],
"document": "string",
"documentSource": "string",
"description": "string",
"jobTemplateArn": "string",
"presignedUrlConfigData": {
"roleArn": "string",
"expiresInSec": "integer"
},
"targetSelection": "CONTINUOUS|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
}
]
},
"SchedulingConfig": {
"startTime": string
"endTime": string
"timeZone": string
"endTimeBehavior": string
}
"timeoutConfig": {
"inProgressTimeoutInMinutes": long
}
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html).
------
#### [ CLI syntax ]
```
aws iot create-job \
--job-id \
--targets \
[--document-source ] \
[--document ] \
[--description ] \
[--job-template-arn ] \
[--presigned-url-config ] \
[--target-selection ] \
[--job-executions-rollout-config ] \
[--abort-config ] \
[--timeout-config ] \
[--document-parameters ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"targets": [ "string" ],
"documentSource": "string",
"document": "string",
"description": "string",
"jobTemplateArn": "string",
"presignedUrlConfig": {
"roleArn": "string",
"expiresInSec": long
},
"targetSelection": "string",
"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": long
},
"documentParameters": {
"string": "string"
}
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/create-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/create-job.html).
------
### DeleteJob
Deletes a job and its related job executions.
Deleting a job can take 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 is shown as "DELETION\$1IN\$1PROGRESS". Attempting to delete or cancel a job whose status is already "DELETION\$1IN\$1PROGRESS" results in an error.
------
#### [ HTTPS request ]
```
DELETE /jobs/jobId?force=force
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJob.html).
------
#### [ CLI syntax ]
```
aws iot delete-job \
--job-id \
[--force | --no-force] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"force": boolean
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/delete-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-job.html).
------
### DeleteJobExecution
Deletes a job execution.
------
#### [ HTTPS request ]
```
DELETE /things/thingName/jobs/jobId/executionNumber/executionNumber?force=force
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJobExecution.html).
------
#### [ CLI syntax ]
```
aws iot delete-job-execution \
--job-id \
--thing-name \
--execution-number \
[--force | --no-force] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"thingName": "string",
"executionNumber": long,
"force": boolean
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/delete-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot/delete-job-execution.html).
------
### DescribeJob
Gets the details of the job execution.
------
#### [ HTTPS request ]
```
GET /jobs/jobId
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJob.html).
------
#### [ CLI syntax ]
```
aws iot describe-job \
--job-id \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string"
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/describe-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-job.html).
------
### DescribeJobExecution
Gets details of a job execution. The job's execution status must be `SUCCEEDED` or `FAILED`.
------
#### [ HTTPS request ]
```
GET /things/thingName/jobs/jobId?executionNumber=executionNumber
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html).
------
#### [ CLI syntax ]
```
aws iot describe-job-execution \
--job-id \
--thing-name \
[--execution-number ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"thingName": "string",
"executionNumber": long
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/describe-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-job-execution.html).
------
### GetJobDocument
Gets the job document for a job.
**Note**
Placeholder URLs are not replaced with presigned Amazon S3 URLs in the document returned. Presigned URLs are generated only when the AWS IoT Jobs service receives a request over MQTT.
------
#### [ HTTPS request ]
```
GET /jobs/jobId/job-document
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html).
------
#### [ CLI syntax ]
```
aws iot get-job-document \
--job-id \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string"
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/get-job-document.html](https://docs.aws.amazon.com/cli/latest/reference/iot/get-job-document.html).
------
### ListJobExecutionsForJob
Gets a list of job executions for a job.
------
#### [ HTTPS request ]
```
GET /jobs/jobId/things?status=status&maxResults=maxResults&nextToken=nextToken
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForJob.html).
------
#### [ CLI syntax ]
```
aws iot list-job-executions-for-job \
--job-id \
[--status ] \
[--max-results ] \
[--next-token ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"status": "string",
"maxResults": "integer",
"nextToken": "string"
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/list-job-executions-for-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-job-executions-for-job.html).
------
### ListJobExecutionsForThing
Gets a list of job executions for a thing.
------
#### [ HTTPS request ]
```
GET /things/thingName/jobs?status=status&maxResults=maxResults&nextToken=nextToken
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForThing.html).
------
#### [ CLI syntax ]
```
aws iot list-job-executions-for-thing \
--thing-name \
[--status ] \
[--max-results ] \
[--next-token ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"thingName": "string",
"status": "string",
"maxResults": "integer",
"nextToken": "string"
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/list-job-executions-for-thing.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-job-executions-for-thing.html).
------
### ListJobs
Gets a list of jobs in your AWS account.
------
#### [ HTTPS request ]
```
GET /jobs?status=status&targetSelection=targetSelection&thingGroupName=thingGroupName&thingGroupId=thingGroupId&maxResults=maxResults&nextToken=nextToken
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobs.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobs.html).
------
#### [ CLI syntax ]
```
aws iot list-jobs \
[--status ] \
[--target-selection ] \
[--max-results ] \
[--next-token ] \
[--thing-group-name ] \
[--thing-group-id ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"status": "string",
"targetSelection": "string",
"maxResults": "integer",
"nextToken": "string",
"thingGroupName": "string",
"thingGroupId": "string"
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/list-jobs.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-jobs.html).
------
### UpdateJob
Updates supported fields of the specified job. Updated values for `timeoutConfig` take effect for only newly in-progress launches. Currently, in-progress launches continue to launch with the previous timeout configuration.
------
#### [ HTTPS request ]
```
PATCH /jobs/jobId
{
"description": "string",
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": number,
"incrementFactor": number,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": number,
"numberOfSucceededThings": number
},
"maximumPerMinute": number
},
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": number,
"thresholdPercentage": number
}
]
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateJob.html).
------
#### [ CLI syntax ]
```
aws iot update-job \
--job-id \
[--description ] \
[--presigned-url-config ] \
[--job-executions-rollout-config ] \
[--abort-config ] \
[--timeout-config ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"description": "string",
"presignedUrlConfig": {
"expiresInSec": number,
"roleArn": "string"
},
"jobExecutionsRolloutConfig": {
"exponentialRate": {
"baseRatePerMinute": number,
"incrementFactor": number,
"rateIncreaseCriteria": {
"numberOfNotifiedThings": number,
"numberOfSucceededThings": number
}
},
"maximumPerMinute": number
},
"abortConfig": {
"criteriaList": [
{
"action": "string",
"failureType": "string",
"minNumberOfExecutedThings": number,
"thresholdPercentage": number
}
]
},
"timeoutConfig": {
"inProgressTimeoutInMinutes": number
}
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot/update-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/update-job.html).
------
# Jobs device MQTT and HTTPS API operations and data types
The following commands are available over the MQTT and HTTPS protocols. Use these API operations on the data plane for devices executing the jobs.
## Jobs device MQTT and HTTPS data types
The following data types are used to communicate with the AWS IoT Jobs service over the MQTT and HTTPS protocols.
### JobExecution
The `JobExecution` object represents the execution of a job on a device. The following example shows the syntax:
**Note**
When you use the MQTT and HTTP data plane API operations, the `JobExecution` data type contains a `JobDocument` field. Your devices can use this information to retrieve the job document from a job execution.
```
{
"jobId" : "string",
"thingName" : "string",
"jobDocument" : "string",
"status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED",
"statusDetails": {
"string": "string"
},
"queuedAt" : "timestamp",
"startedAt" : "timestamp",
"lastUpdatedAt" : "timestamp",
"versionNumber" : "number",
"executionNumber": long
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecution.html) or [https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution.html).
### JobExecutionState
The `JobExecutionState` contains information about the state of a job execution. The following example shows the syntax:
```
{
"status": "QUEUED|IN_PROGRESS|FAILED|SUCCEEDED|CANCELED|TIMED_OUT|REJECTED|REMOVED",
"statusDetails": {
"string": "string"
...
}
"versionNumber": "number"
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionState.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionState.html) or [https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution-state.html](https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution-state.html).
### JobExecutionSummary
Contains a subset of information about a job execution. The following example shows the syntax:
```
{
"jobId": "string",
"queuedAt": timestamp,
"startedAt": timestamp,
"lastUpdatedAt": timestamp,
"versionNumber": "number",
"executionNumber": long
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionSummary.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_JobExecutionSummary.html) or [https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution-summary.html](https://docs.aws.amazon.com/cli/latest/reference/iot-data/job-execution-summary.html).
**Topics**
+ [
## Jobs device MQTT and HTTPS data types
](#jobs-data-plane-data-types)
+ [
# Jobs device MQTT API operations
](jobs-mqtt-api.md)
+ [
# Jobs device HTTP API
](jobs-http-device-api.md)
# Jobs device MQTT API operations
You can issue jobs device commands by publishing MQTT messages to the [Reserved topics used for Jobs commands](reserved-topics.md#reserved-topics-job).
Your device-side client must be subscribed to the response message topics of these commands. If you use the AWS IoT Device Client, your device will automatically subscribe to the response topics. This means that the message broker will publish response message topics to the client that published the command message, whether or not your client has subscribed to the response message topics. These response messages don't pass through the message broker and can't be subscribed to by other clients or rules.
When subscribing to the job and `jobExecution` event topics for your fleet-monitoring solution, first enable [job and job execution events](iot-events.md) to receive any events on the cloud side. Job progress messages that are processed through the message broker and can be used by AWS IoT rules are published as [Jobs events](events-jobs.md). Because the message broker publishes response messages, even without an explicit subscription to them, your client must be configured to receive and identify the messages it receives. Your client must also confirm that the *thingName* in the incoming message topic applies to the client's thing name before the client acts on the message.
**Note**
Messages that AWS IoT sends in response to MQTT Jobs API command messages are charged to your account, whether or not you subscribed to them explicitly.
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 used to correlate requests and responses. Enter an arbitrary value here and it's 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 thing.
To invoke this API, publish a message on `$aws/things/thingName/jobs/get`.
Request payload:
```
{ "clientToken": "string" }
```
The message broker will publish `$aws/things/thingName/jobs/get/accepted` and `$aws/things/thingName/jobs/get/rejected` even without a specific subscription to them. However, for your client to receive the messages, it must be listening for them. For more information, see [the note about Jobs API messages](#jobs-mqtt-note).
Response payload:
```
{
"inProgressJobs" : [ JobExecutionSummary ... ],
"queuedJobs" : [ JobExecutionSummary ... ],
"timestamp" : 1489096425069,
"clientToken" : "client-001"
}
```
Where `inProgressJobs` and `queuedJobs` return a list of [JobExecutionSummary](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-summary) objects that have status of `IN_PROGRESS` or `QUEUED`.
## StartNextPendingJobExecution
Gets and starts the next pending job execution for a thing (status `IN_PROGRESS` or `QUEUED`).
+ Any job executions with status `IN_PROGRESS` are returned first.
+ Job executions are returned in the order in which they were queued. When a thing is added or removed from the target group for your job, confirm the rollout order of any new job executions compared to existing job executions.
+ If the next pending job execution is `QUEUED`, its state changes to `IN_PROGRESS` and the job execution's status details are set as specified.
+ If the next pending job execution is already `IN_PROGRESS`, its status details aren't changed.
+ If no job executions are pending, the response doesn't include the `execution` field.
+ Optionally, you can create a step timer by setting a value for the `stepTimeoutInMinutes` property. If you don't update the value of this property by running `UpdateJobExecution`, the job execution times out when the step timer expires.
To invoke this API, publish a message on `$aws/things/thingName/jobs/start-next`.
Request payload:
```
{
"statusDetails": {
"string": "job-execution-state"
...
},
"stepTimeoutInMinutes": long,
"clientToken": "string"
}
```
`statusDetails`
A collection of name-value pairs that describe the status of the job execution. If not specified, the `statusDetails` are unchanged.
`stepTimeOutInMinutes`
Specifies the amount of time this device has to finish execution of this job. If the job execution status isn't set to a terminal state before this timer expires, or before the timer is reset, (by calling `UpdateJobExecution`, setting the status to `IN_PROGRESS` and specifying a new timeout value in field `stepTimeoutInMinutes`) the job execution status is set to `TIMED_OUT`. Setting this timeout has no effect on that job execution timeout that might have been specified when the job was created (`CreateJob` using the `timeoutConfig` field).
Valid values for this parameter range from 1 to 10080 (1 minute to 7 days). A value of -1 is also valid and will cancel the current step timer (created by an earlier use of UpdateJobExecutionRequest).
The message broker will publish `$aws/things/thingName/jobs/start-next/accepted` and `$aws/things/thingName/jobs/start-next/rejected` even without a specific subscription to them. However, for your client to receive the messages, it must be listening for them. For more information, see [the note about Jobs API messages](#jobs-mqtt-note).
Response payload:
```
{
"execution" : JobExecutionData,
"timestamp" : timestamp,
"clientToken" : "string"
}
```
Where `execution` is a [JobExecution](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-data) object. For example:
```
{
"execution" : {
"jobId" : "022",
"thingName" : "MyThing",
"jobDocument" : "< contents of job document >",
"status" : "IN_PROGRESS",
"queuedAt" : 1489096123309,
"lastUpdatedAt" : 1489096123309,
"versionNumber" : 1,
"executionNumber" : 1234567890
},
"clientToken" : "client-1",
"timestamp" : 1489088524284,
}
```
## DescribeJobExecution
Gets detailed information about a job execution.
You can set the `jobId` to `$next` to return the next pending job execution for a thing (with a status of `IN_PROGRESS` or `QUEUED`).
To invoke this API, publish a message on `$aws/things/thingName/jobs/jobId/get`.
Request payload:
```
{
"jobId" : "022",
"thingName" : "MyThing",
"executionNumber": long,
"includeJobDocument": boolean,
"clientToken": "string"
}
```
`thingName`
The name of the thing associated with the device.
`jobId`
The unique identifier assigned to this job when it was created.
Or use `$next` to return the next pending job execution for a thing (with a status of `IN_PROGRESS` or `QUEUED`). In this case, any job executions with status `IN_PROGRESS` are returned first. Job executions are returned in the order in which they were created.
`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`.
The message broker will publish `$aws/things/thingName/jobs/jobId/get/accepted` and `$aws/things/thingName/jobs/jobId/get/rejected` even without a specific subscription to them. However, for your client to receive the messages, it must be listening for them. For more information, see [the note about Jobs API messages](#jobs-mqtt-note).
Response payload:
```
{
"execution" : JobExecutionData,
"timestamp": "timestamp",
"clientToken": "string"
}
```
Where `execution` is a [JobExecution](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-data) object.
## UpdateJobExecution
Updates the status of a job execution. You can optionally create a step timer by setting a value for the `stepTimeoutInMinutes` property. If you don't update the value of this property by running `UpdateJobExecution` again, the job execution times out when the step timer expires.
To invoke this API, publish a message on `$aws/things/thingName/jobs/jobId/update`.
Request payload:
```
{
"status": "job-execution-state",
"statusDetails": {
"string": "string"
...
},
"expectedVersion": "number",
"executionNumber": long,
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"stepTimeoutInMinutes": long,
"clientToken": "string"
}
```
`status`
The new status for the job execution (`IN_PROGRESS`, `FAILED`, `SUCCEEDED`, or `REJECTED`). This must be specified on every update.
`statusDetails`
A collection of name-value pairs that describe the status of the job execution. If not specified, the `statusDetails` are unchanged.
`expectedVersion`
The expected current version of the job execution. Each time you update the job execution, its version is incremented. If the version of the job execution stored in the AWS IoT Jobs service doesn't match, the update is rejected with a `VersionMismatch` error. An [ErrorResponse](jobs-api.md#jobs-mqtt-error-response) that contains the current job execution status data is also returned. (This makes it unnecessary to perform a separate `DescribeJobExecution` request to obtain the job execution status data.)
`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`
Specifies the amount of time this device has to finish execution of this job. If the job execution status is not set to a terminal state before this timer expires, or before the timer is reset, the job execution status is set to `TIMED_OUT`. Setting or resetting this timeout has no effect on the job execution timeout that might have been specified when the job was created.
The message broker will publish `$aws/things/thingName/jobs/jobId/update/accepted` and `$aws/things/thingName/jobs/jobId/update/rejected` even without a specific subscription to them. However, for your client to receive the messages, it must be listening for them. For more information, see [the note about Jobs API messages](#jobs-mqtt-note).
Response payload:
```
{
"executionState": JobExecutionState,
"jobDocument": "string",
"timestamp": timestamp,
"clientToken": "string"
}
```
`executionState`
A [JobExecutionState](jobs-mqtt-https-api.md#jobs-mqtt-job-execution-state) object.
`jobDocument`
A [job document](key-concepts-jobs.md) object.
In MQTT responses, the `jobDocument` field is a JSON object. In HTTP responses, it's a string representation of the JSON object.
`timestamp`
The time in seconds since the epoch, when the message was sent.
`clientToken`
A client token used to correlate requests and responses.
When you use the MQTT protocol, you can also perform the following updates:
## JobExecutionsChanged
Sent whenever a job execution is added to or removed from the list of pending job executions for a thing.
Use the topic:
`$aws/things/thingName/jobs/notify`
Message payload:
```
{
"jobs" : {
"JobExecutionState": [ [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecutionSummary.html) ... ]
},
"timestamp": timestamp
}
```
## NextJobExecutionChanged
Sent whenever there is a change to which job execution is next on the list of pending job executions for a thing, as defined for [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html) 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.
Use the topic:
`$aws/things/thingName/jobs/notify-next`
Message payload:
```
{
"execution" : [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html),
"timestamp": timestamp,
}
```
# Jobs device HTTP API
Devices can communicate with AWS IoT Jobs using HTTP Signature Version 4 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](https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/index.html) or [AWS SDKs and Tools](http://aws.amazon.com/tools/#sdk).
The following commands are available for devices executing the jobs. For information about using API operations with the MQTT protocol, see [Jobs device MQTT API operations](jobs-mqtt-api.md).
## GetPendingJobExecutions
Gets the list of all jobs that aren't in a terminal state, for a specified thing.
------
#### [ HTTPS request ]
```
GET /things/thingName/jobs
```
Response:
```
{
"inProgressJobs" : [ JobExecutionSummary ... ],
"queuedJobs" : [ JobExecutionSummary ... ]
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html).
------
#### [ CLI syntax ]
```
aws iot-jobs-data get-pending-job-executions \
--thing-name \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"thingName": "string"
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/get-pending-job-executions.html](https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/get-pending-job-executions.html).
------
## StartNextPendingJobExecution
Gets and starts the next pending job execution for a thing (with a status of `IN_PROGRESS` or `QUEUED`).
+ Any job executions with status `IN_PROGRESS` are returned first.
+ Job executions are returned in the order in which they were created.
+ If the next pending job execution is `QUEUED`, its status changes to `IN_PROGRESS` and the job execution's status details are set as specified.
+ If the next pending job execution is already `IN_PROGRESS`, its status details don't change.
+ If no job executions are pending, the response doesn't include the `execution` field.
+ Optionally, you can create a step timer by setting a value for the `stepTimeoutInMinutes` property. If you don't update the value of this property by running `UpdateJobExecution`, the job execution times out when the step timer expires.
------
#### [ HTTPS request ]
The following example shows the request syntax:
```
PUT /things/thingName/jobs/$next
{
"statusDetails": {
"string": "string"
...
},
"stepTimeoutInMinutes": long
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_StartNextPendingJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_StartNextPendingJobExecution.html).
------
#### [ CLI syntax ]
**Synopsis:**
```
aws iot-jobs-data start-next-pending-job-execution \
--thing-name \
{--step-timeout-in-minutes ] \
[--status-details ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"thingName": "string",
"statusDetails": {
"string": "string"
},
"stepTimeoutInMinutes": long
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/start-next-pending-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot-jobs-data/start-next-pending-job-execution.html).
------
## DescribeJobExecution
Gets detailed information about a job execution.
You can set the `jobId` to `$next` to return the next pending job execution for a thing. The job's execution status must be `QUEUED` or `IN_PROGRESS`.
------
#### [ HTTPS request ]
Request:
```
GET /things/thingName/jobs/jobId?executionNumber=executionNumber&includeJobDocument=includeJobDocument
```
Response:
```
{
"execution" : JobExecution,
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html).
------
#### [ CLI syntax ]
**Synopsis:**
```
aws iot-jobs-data describe-job-execution \
--job-id \
--thing-name \
[--include-job-document | --no-include-job-document] \
[--execution-number ] \
[--cli-input-json ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"thingName": "string",
"includeJobDocument": boolean,
"executionNumber": long
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot-data/describe-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot-data/describe-job-execution.html).
------
## UpdateJobExecution
Updates the status of a job execution. Optionally, you can create a step timer by setting a value for the `stepTimeoutInMinutes` property. If you don't update the value of this property by running `UpdateJobExecution` again, the job execution times out when the step timer expires.
------
#### [ HTTPS request ]
Request:
```
POST /things/thingName/jobs/jobId
{
"status": "job-execution-state",
"statusDetails": {
"string": "string"
...
},
"expectedVersion": "number",
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"stepTimeoutInMinutes": long,
"executionNumber": long
}
```
For more information, see [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html).
------
#### [ CLI syntax ]
**Synopsis:**
```
aws iot-jobs-data update-job-execution \
--job-id \
--thing-name \
--status \
[--status-details ] \
[--expected-version ] \
[--include-job-execution-state | --no-include-job-execution-state] \
[--include-job-document | --no-include-job-document] \
[--execution-number ] \
[--cli-input-json ] \
[--step-timeout-in-minutes ] \
[--generate-cli-skeleton]
```
`cli-input-json` format:
```
{
"jobId": "string",
"thingName": "string",
"status": "string",
"statusDetails": {
"string": "string"
},
"stepTimeoutInMinutes": number,
"expectedVersion": long,
"includeJobExecutionState": boolean,
"includeJobDocument": boolean,
"executionNumber": long
}
```
For more information, see [https://docs.aws.amazon.com/cli/latest/reference/iot-data/update-job-execution.html](https://docs.aws.amazon.com/cli/latest/reference/iot-data/update-job-execution.html).
------
# Securing users and devices with AWS IoT Jobs
Securing users and devices for Jobs
To authorize users to use AWS IoT Jobs with their devices, you must grant them permissions by using IAM policies. The devices must then be authorized by using AWS IoT Core policies to connect securely to AWS IoT, receive job executions, and update the execution status.
## Required policy type for AWS IoT Jobs
The following table shows the different types of policies that you must use for authorization. For more information about the required policy to use, see [Authorization](iot-authorization.md).
**Required policy type**
| Use case | Protocol | Authentication | Control plane/data plane | Identity type | Required policy type |
| --- | --- | --- | --- | --- | --- |
| Authorize an administrator, operator, or Cloud Service to work securely with Jobs | HTTPS | AWS Signature Version 4 authentication (port 443) | Both control plane and data plane | Amazon Cognito Identity, IAM, or federated user | IAM policy |
| Authorize your IoT device to work securely with Jobs | MQTT/HTTPS | TCP or TLS mutual authentication (port 8883 or 443) | Data plane | X.509 certificates | AWS IoT Core policy |
To authorize AWS IoT Jobs operations that can be performed both on the control plane and data plane, you must use IAM policies. The identities must have been authenticated with AWS IoT to perform these operations, which must be [Amazon Cognito identities](cognito-identities.md) or [IAM users, groups, and roles](iam-users-groups-roles.md). For more information about authentication, see [Authentication](authentication.md).
The devices must now be authorized on the data plane by using AWS IoT Core policies to connect securely to the device gateway. The device gateway enables devices to securely communicate with AWS IoT, receive job executions, and update the job execution status. Device communication is secured by using secure [MQTT](mqtt.md) or [HTTPS publish](http.md) communication protocols. These protocols use [X.509 client certificates](x509-client-certs.md) that are provided by AWS IoT to authenticate the device connections.
The following shows how you authorize your users, cloud services, and devices to use AWS IoT Jobs. For information about control plane and data plane API operations, see [AWS IoT jobs API operations](jobs-api.md).
**Topics**
+ [
## Required policy type for AWS IoT Jobs
](#jobs-required-policy)
+ [
# Authorizing users and cloud services to use AWS IoT Jobs
](iam-policy-users-jobs.md)
+ [
# Authorizing your devices to securely use AWS IoT Jobs on the data plane
](iot-data-plane-jobs.md)
# Authorizing users and cloud services to use AWS IoT Jobs
Authorizing Jobs users and cloud services
To authorize your users and cloud services, you must use IAM policies on both the control plane and data plane. The policies must be used with HTTPS protocol and must use AWS Signature Version 4 authentication (port 443) to authenticate users.
**Note**
AWS IoT Core policies must not be used on the control plane. Only IAM policies are used for authorizing users or Cloud Services. For more information about using the required policy type, see [Required policy type for AWS IoT Jobs](iot-jobs-security.md#jobs-required-policy).
IAM policies are JSON documents that contain policy statements. Policy statements use *Effect*, *Action*, and *Resource* elements to specify resources, allowed or denied actions, and conditions under which actions are allowed or denied. For more information, see [IAM JSON Policy Elements Reference](https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_elements.html) in the *IAM user Guide*.
**Warning**
We recommend that you don't use wildcard permissions, such as `"Action": ["iot:*"]` in your IAM policies or AWS IoT Core policies. Using wildcard permissions is not a recommended security best practice. For more information, see [AWS IoT policy overly permissive](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/audit-chk-iot-policy-permissive.html).
## IAM policies on the control plane
On the control plane, IAM policies use the `iot:` prefix with the action to authorize the corresponding jobs API operation. For example, the `iot:CreateJob` policy action grants the user permission to use the [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) API.
### Policy actions
The following table shows a list of IAM policy actions and permissions to use the API actions. For information about resource types, see [Resource types defined by AWS IoT](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiot.html#awsiot-job). For more information about AWS IoT actions, see [Actions defined by AWS IoT](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsiot.html).
**IAM policy actions on control plane**
| Policy action | API operation | Resource types | Description |
| --- | --- | --- | --- |
| iot:AssociateTargetsWithJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_AssociateTargetsWithJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_AssociateTargetsWithJob.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iam-policy-users-jobs.html) | Represents the permission to associate a group with a continuous job. The iot:AssociateTargetsWithJob permission is checked every time a request is made to associate targets. |
| iot:CancelJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJob.html) | job | Represents the permission to cancel a job. The iot:CancelJob permission is checked every time a request is made to cancel a job. |
| iot:CancelJobExecution | [https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CancelJobExecution.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iam-policy-users-jobs.html) | Represents the permission to cancel a job execution. The iot: CancelJobExecution permission is checked every time a request is made to cancel a job execution. |
| iot:CreateJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iam-policy-users-jobs.html) | Represents the permission to create a job. The iot: CreateJob permission is checked every time a request is made to create a job. |
| iot:CreateJobTemplate | [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iam-policy-users-jobs.html) | Represents the permission to create a job template. The iot: CreateJobTemplate permission is checked every time a request is made to create a job template. |
| iot:DeleteJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJob.html) | job | Represents the permission to delete a job. The iot: DeleteJob permission is checked every time a request is made to delete a job. |
| iot:DeleteJobTemplate | [https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJobTemplate.html) | jobtemplate | Represents the permission to delete a job template. The iot: CreateJobTemplate permission is checked every time a request is made to delete a job template. |
| iot:DeleteJobExecution | [https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DeleteJobExecution.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iam-policy-users-jobs.html) | Represents the permission to delete a job execution. The iot: DeleteJobExecution permission is checked every time a request is made to delete a job execution. |
| iot:DescribeJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJob.html) | job | Represents the permission to describe a job. The iot: DescribeJob permission is checked every time a request is made to describe a job. |
| iot:DescribeJobExecution | [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iam-policy-users-jobs.html) | Represents the permission to describe a job execution. The iot: DescribeJobExecution permission is checked every time a request is made to describe a job execution. |
| iot:DescribeJobTemplate | [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobTemplate.html) | jobtemplate | Represents the permission to describe a job template. The iot: DescribeJobTemplate permission is checked every time a request is made to describe a job template. |
| iot:DescribeManagedJobTemplate | [https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeManagedJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeManagedJobTemplate.html) | jobtemplate | Represents the permission to describe a managed job template. The iot: DescribeManagedJobTemplate permission is checked every time a request is made to describe a managed job template. |
| iot:GetJobDocument | [https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html](https://docs.aws.amazon.com/iot/latest/apireference/API_GetJobDocument.html) | job | Represents the permission to get the job document for a job. The iot:GetJobDocument permission is checked every time a request is made to get a job document. |
| iot:ListJobExecutionsForJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForJob.html) | job | Represents the permission to list the job executions for a job. The iot:ListJobExecutionsForJob permission is checked every time a request is made to list the job executions for a job. |
| iot:ListJobExecutionsForThing | [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForThing.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobExecutionsForThing.html) | thing | Represents the permission to list the job executions for a job. The iot:ListJobExecutionsForThing permission is checked every time a request is made to list the job executions for a thing. |
| iot:ListJobs | [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobs.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobs.html) | none | Represents the permission to list the jobs. The iot:ListJobs permission is checked every time a request is made to list the jobs. |
| iot:ListJobTemplates | [https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobTemplates.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListJobTemplates.html) | none | Represents the permission to list the job templates. The iot:ListJobTemplates permission is checked every time a request is made to list the job templates. |
| iot:ListManagedJobTemplates | [https://docs.aws.amazon.com/iot/latest/apireference/API_ListManagedJobTemplates.html](https://docs.aws.amazon.com/iot/latest/apireference/API_ListManagedJobTemplates.html) | none | Represents the permission to list the managed job templates. The iot:ListManagedJobTemplates permission is checked every time a request is made to list the managed job templates. |
| iot:UpdateJob | [https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_UpdateJob.html) | job | Represents the permission to update a job. The iot:UpdateJob permission is checked every time a request is made to update a job. |
| iot:TagResource | [https://docs.aws.amazon.com/iot/latest/apireference/API_TagResource.html](https://docs.aws.amazon.com/iot/latest/apireference/API_TagResource.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iam-policy-users-jobs.html) | Grants permission to tag a specific resource. |
| iot:UntagResource | [https://docs.aws.amazon.com/iot/latest/apireference/API_UntagResource.html](https://docs.aws.amazon.com/iot/latest/apireference/API_UntagResource.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iam-policy-users-jobs.html) | Grants permission to untag a specific resource. |
### Basic IAM policy example
The following example shows an IAM policy that allows the user permission to perform the following actions for your IoT thing and thing group.
In the example, replace:
+ *region* with your AWS Region, such as `us-east-1`.
+ *account-id* with your AWS account number, such as `57EXAMPLE833`.
+ *thing-group-name* with the name of your IoT thing group for which you're targeting jobs, such as `FirmwareUpdateGroup`.
+ *thing-name* with the name of your IoT thing for which you're targeting jobs, such as `MyIoTThing`.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"iot:CreateJobTemplate",
"iot:CreateJob"
],
"Effect": "Allow",
"Resource": "arn:aws:iot:us-east-1:123456789012:thinggroup/thing-group-name"
},
{
"Action": [
"iot:DescribeJob",
"iot:CancelJob",
"iot:DeleteJob"
],
"Effect": "Allow",
"Resource": "arn:aws:iot:us-east-1:123456789012:job/*"
},
{
"Action": [
"iot:DescribeJobExecution",
"iot:CancelJobExecution",
"iot:DeleteJobExecution"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing-123",
"arn:aws:iot:us-east-1:123456789012:job/*"
]
}
]
}
```
### IAM policy example for IP based authorization
You can restrict *principals* from making API calls to your control plane endpoint from specific IP addresses. To specify the IP addresses that can be allowed, in the Condition element of your IAM policy, use the [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceip](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceip) global condition key.
Using this condition key can also deny access to other AWS services from making these API calls on your behalf, such as AWS CloudFormation. To allow access to these services, use the [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-viaawsservice](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-viaawsservice) global condition key with the aws:SourceIp key. This makes sure that the source IP address access restriction applies only to requests that are made directly by a principal. For more information, see [AWS: Denies access to AWS based on the source IP](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_aws_deny-ip.html).
The following example shows how to allow only a specific IP address that can make API calls to the control plane endpoint. The `aws:ViaAWSService` key is set to `true`, which allows other services to make API calls on your behalf.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:CreateJobTemplate",
"iot:CreateJob"
],
"Resource": [
"*"
],
"Condition": {
"IpAddress": {
"aws:SourceIp": "123.45.167.89"
},
"Bool": {
"aws:ViaAWSService": "false"
}
}
}]
}
```
## IAM policies on the data plane
IAM policies on the data plane use the `iotjobsdata:` prefix to authorize jobs API operations that users can perform. On the data plane, you can grant a user permission to use the [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html) API by using the `iotjobsdata:DescribeJobExecution` policy action.
**Warning**
Using IAM policies on the data plane is not recommended when targeting AWS IoT Jobs for your devices. We recommend that you use IAM policies on the control plane for users to create and manage jobs. On the data plane, for authorizing devices to retrieve job executions and update the execution status, use [AWS IoT Core policies for HTTPS protocol](iot-data-plane-jobs.md#iot-jobs-data-http).
### Basic IAM policy example
The API operations that must be authorized are usually performed by you typing CLI commands. The following shows an example of a user performing a `DescribeJobExecution` operation.
In the example, replace:
+ *region* with your AWS Region, such as `us-east-1`.
+ *account-id* with your AWS account number, such as `57EXAMPLE833`.
+ *thing-name* with the name of your IoT thing for which you're targeting jobs, such as `myRegisteredThing`.
+ `job-id` is the unique identifier for the job that's targeted using the API.
```
aws iot-jobs-data describe-job-execution \
--endpoint-url "https://account-id.jobs.iot.region.amazonaws.com" \
--job-id jobID --thing-name thing-name
```
The following shows a sample IAM policy that authorizes this action:
****
```
{
"Version":"2012-10-17",
"Statement": {
"Action": [
"iotjobsdata:DescribeJobExecution"
],
"Effect": "Allow",
"Resource": "arn:aws:iot:us-east-1:123456789012:thing/thing-123"
}
}
```
### IAM policy examples for IP based authorization
You can restrict *principals* from making API calls to your data plane endpoint from specific IP addresses. To specify the IP addresses that can be allowed, in the Condition element of your IAM policy, use the [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceip](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-sourceip) global condition key.
Using this condition key can also deny access to other AWS services from making these API calls on your behalf, such as AWS CloudFormation. To allow access to these services, use the [https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-viaawsservice](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_condition-keys.html#condition-keys-viaawsservice) global condition key with the `aws:SourceIp` condition key. This makes sure that the IP address access restriction only applies to requests that are directly made by the principal. For more information, see [AWS: Denies access to AWS based on the source IP](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_examples_aws_deny-ip.html).
The following example shows how to allow only a specific IP address that can make API calls to the data plane endpoint.
****
```
{
"Version":"2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": [
"iotjobsdata:*"
],
"Resource": [
"*"
],
"Condition": {
"IpAddress": {
"aws:SourceIp": "123.45.167.89"
},
"Bool": {
"aws:ViaAWSService": "false"
}
}
}]
}
```
The following example shows how to restrict specific IP addresses or address ranges from making API calls to the data plane endpoint.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Deny",
"Action": [
"iotjobsdata:*"
],
"Condition": {
"IpAddress": {
"aws:SourceIp": [
"123.45.167.89",
"192.0.2.0/24",
"203.0.113.0/24"
]
}
},
"Resource": [
"*"
]
}
]
}
```
### IAM policy example for both control plane and data plane
If you perform an API operation on both the control plane and data plane, your control plane policy action must use the `iot:` prefix, and your data plane policy action must use the `iotjobsdata:` prefix.
For example, the `DescribeJobExecution` API can be used in both the control plane and data plane. On the control plane, the [DescribeJobExecution](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeJobExecution.html) API is used to describe a job execution. On the data plane, the [ DescribeJobExecution](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html) API is used to get details of a job execution.
The following IAM policy authorizes a user permission to use the `DescribeJobExecution` API on both the control plane and data plane.
In the example, replace:
+ *region* with your AWS Region, such as `us-east-1`.
+ *account-id* with your AWS account number, such as `57EXAMPLE833`.
+ *thing-name* with the name of your IoT thing for which you're targeting jobs, such as `MyIoTThing`.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"iotjobsdata:DescribeJobExecution"
],
"Effect": "Allow",
"Resource": "arn:aws:iot:us-east-1:123456789012:thing/thing-123"
},
{
"Action": [
"iot:DescribeJobExecution",
"iot:CancelJobExecution",
"iot:DeleteJobExecution"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:thing/thing-123",
"arn:aws:iot:us-east-1:123456789012:job/*"
]
}
]
}
```
## Authorize tagging of IoT resources
For better control over jobs and job templates that you can create, modify, or use, you can attach tags to the jobs or job templates. Tags also help you discern ownership and assign and allocate costs by placing them in billing groups and attaching tags to them.
When a user wants to tag their jobs or job templates that they created by using the AWS Management Console or the AWS CLI, your IAM policy must grant the user permissions to tag them. To grant permissions, your IAM policy must use the `iot:TagResource` action.
**Note**
If your IAM policy doesn't include the `iot:TagResource` action, then any [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html) or [https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJobTemplate.html) with a tag will return an `AccessDeniedException` error.
When you want to tag your jobs or job templates that you created by using the AWS Management Console or the AWS CLI, your IAM policy must grant permission to tag them. To grant permissions, your IAM policy must use the `iot:TagResource` action.
For general information about tagging your resources, see [Tagging your AWS IoT resources](tagging-iot.md).
### IAM policy example
Refer to the following IAM policy examples granting tagging permissions:
*Example 1*
A user that runs the following command to create a job and tag it to a specific environment.
In this example, replace:
+ *region* with your AWS Region, such as `us-east-1`.
+ *account-id* with your AWS account number, such as `57EXAMPLE833`.
+ *thing-name* with the name of your IoT thing for which you're targeting jobs, such as `MyIoTThing`.
```
aws iot create-job
--job-id test_job
--targets "arn:aws:iot:region:account-id:thing/thingOne"
--document-source "https://s3.amazonaws.com/amzn-s3-demo-bucket/job-document.json"
--description "test job description"
--tags Key=environment,Value=beta
```
For this example, you must use the following IAM policy:
****
```
{
"Version":"2012-10-17",
"Statement": {
"Action": [
"iot:CreateJob",
"iot:CreateJobTemplate",
"iot:TagResource"
],
"Effect": "Allow",
"Resource": [
"arn:aws:iot:us-east-1:123456789012:job/*",
"arn:aws:iot:us-east-1:123456789012:jobtemplate/*"
]
}
}
```
# Authorizing your devices to securely use AWS IoT Jobs on the data plane
Authorizing devices to use jobs
To authorize your devices to interact securely with AWS IoT Jobs on the data plane, you must use AWS IoT Core policies. AWS IoT Core policies for jobs are JSON documents containing policy statements. These policies also use *Effect*, *Action*, and *Resource* elements, and follow a similar convention to IAM policies. For more information about the elements, see [IAM JSON Policy Elements Reference](https://docs.aws.amazon.com/service-authorization/latest/reference/reference_policies_elements.html) in the *IAM user Guide*.
The policies can be used with both MQTT and HTTPS protocols and must use TCP or TLS mutual authentication to authenticate the devices. The following shows how to use these policies across the different communication protocols.
**Warning**
We recommend that you don't use wildcard permissions, such as `"Action": ["iot:*"]` in your IAM policies or AWS IoT Core policies. Using wildcard permissions is not a recommended security best practice. For more information, see [AWS IoT policy overly permissive](https://docs.aws.amazon.com/iot-device-defender/latest/devguide/audit-chk-iot-policy-permissive.html).
## AWS IoT Core policies for MQTT protocol
AWS IoT Core policies for MQTT protocol grant you permissions to use the jobs device MQTT API actions. The MQTT API operations are used to work with MQTT topics that are reserved for jobs commands. For more information about these API operations, see [Jobs device MQTT API operations](jobs-mqtt-api.md).
MQTT policies use policy actions such as `iot:Connect`, `iot:Publish`, `iot:Subscribe`, and `iot:Receieve` to work with the jobs topics. These policies allow you to connect to the message broker, subscribe to the jobs MQTT topics, and send and receive MQTT messages between your devices and the cloud. For more information about these actions, see [AWS IoT Core policy actions](iot-policy-actions.md).
For information about topics for AWS IoT Jobs, see [Job topics](reserved-topics.md#reserved-topics-job).
### Basic MQTT policy example
The following example shows how you can use `iot:Publish` and `iot:Subscribe` to publish and subscribe to jobs and job executions.
In the example, replace:
+ *region* with your AWS Region, such as `us-east-1`.
+ *account-id* with your AWS account number, such as `57EXAMPLE833`.
+ *thing-name* with the name of your IoT thing for which you're targeting jobs, such as `MyIoTThing`.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"iot:Publish",
"iot:Subscribe"
],
"Resource": [
"arn:aws:iot:us-east-1:123456789012:topic/$aws/events/job/*",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/events/jobExecution/*",
"arn:aws:iot:us-east-1:123456789012:topic/$aws/things/thing-123/jobs/*"
]
}
]
}
```
## AWS IoT Core policies for HTTPS protocol
AWS IoT Core policies on the data plane can also use the HTTPS protocol with the TLS authentication mechanism to authorize your devices. On the data plane, policies use the `iotjobsdata:` prefix to authorize jobs API operations that your devices can perform. For example, the `iotjobsdata:DescribeJobExecution` policy action grants the user permission to use the [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html) API.
**Note**
The data plane policy actions must use the `iotjobsdata:` prefix. On the control plane, the actions must use the `iot:` prefix. For an example IAM policy when both control plane and data plane policy actions are used, see [IAM policy example for both control plane and data plane](iam-policy-users-jobs.md#iam-data-plane-example2).
### Policy actions
The following table shows a list of AWS IoT Core policy actions and permissions for authorizing devices to use the API actions. For a list of API operations that you can perform in the data plane, see [Jobs device HTTP API](jobs-http-device-api.md).
**Note**
These job execution policy actions apply only to the HTTP TLS endpoint. If you use the MQTT endpoint, you must use the MQTT policy actions defined previously.
**AWS IoT Core policy actions on data plane**
| Policy action | API operation | Resource types | Description |
| --- | --- | --- | --- |
| iotjobsdata:DescribeJobExecution | [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_DescribeJobExecution.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/iot-data-plane-jobs.html) | Represents the permission to retrieve a job execution. The iotjobsdata:DescribeJobExecution permission is checked every time a request is made to retrieve a job execution. |
| iotjobsdata:GetPendingJobExecutions | [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html) | thing | Represents the permission to retrieve the list of jobs that are not in a terminal status for a thing. The iotjobsdata:GetPendingJobExecutions permission is checked every time a request is made to retrieve the list. |
| iotjobsdata:StartNextPendingJobExecution | [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html) | thing | Represents the permission to get and start the next pending job execution for a thing. That is, to update a job execution with status QUEUED to IN\$1PROGRESS. The iotjobsdata:StartNextPendingJobExecution permission is checked every time a request is made to start the next pending job execution. |
| iotjobsdata:UpdateJobExecution | [https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_UpdateJobExecution.html) | thing | Represents the permission to update a job execution. The iotjobsdata:UpdateJobExecution permission is checked every time a request is made to update the state of a job execution. |
### Basic policy example
The following shows an example of an AWS IoT Core policy that grants permission to perform the actions on the data plane API operations for any resource. You can scope your policy to a specific resource, such as an IoT thing. In your example, replace:
+ *region* with your AWS Region such as `us-east-1`.
+ *account-id* with your AWS account number, such as `57EXAMPLE833`.
+ *thing-name* with the name of the IoT thing, such as `MyIoTthing`.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"iotjobsdata:GetPendingJobExecutions",
"iotjobsdata:StartNextPendingJobExecution",
"iotjobsdata:DescribeJobExecution",
"iotjobsdata:UpdateJobExecution"
],
"Effect": "Allow",
"Resource": "arn:aws:iot:us-east-1:123456789012:thing/thing-123"
}
]
}
```
An example of when you must use these policies can be when your IoT devices use an AWS IoT Core policy to access one of these API operations, such as the following example of the `DescribeJobExecution` API:
```
GET /things/thingName/jobs/jobId?executionNumber=executionNumber&includeJobDocument=includeJobDocument&namespaceId=namespaceId HTTP/1.1
```
# AWS IoT Jobs limits
AWS IoT Jobs has Service quotas, or limits, that correspond to the maximum number of service resources or operations for your AWS account.
**Topics**
+ [
## Job executions limits
](#job-execution-limits)
+ [
## Active and concurrent job limits
](#job-limits-active-concurrent)
## Job executions limits
This section provides information about the job execution limits for AWS IoT Device Management.
**Note**
These limits are not part of the service quotas that you can find in the [AWS IoT Device Management Service Quotas documentation](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#iot_device_management_quotas).
To get information about the number of pending job executions, you can either use the `GetPendingJobExecutions` API, or subscribe to the MQTT reserved topics for AWS IoT Jobs and receive [Job notification types](jobs-comm-notifications.md#jobs-comm-notifications-types).
The number of pending job executions in your account can vary depending on whether you have the scheduling configuration enabled and use a recurring maintenance window.
**Maximum number of pending job executions**
| API/notification name | Description | Without scheduling configuration | With scheduling configuration |
| --- | --- | --- | --- |
| ListNotification | A ListNotification is published whenever an old job execution enters a terminal status, or when a new job execution is queued or changes to a non-terminal status. It can display up to 15 pending job executions that are either QUEUED or IN\$1PROGRESS. | 10 | 15 (Up to 5 job executions only appears in the ListNotification during a maintenace window). |
| GetPendingJobExecutions | When you invoke the `GetPendingJobExecutions` API, it returns a list of job executions that have not yet started, and can be started after the API call. The API can return up to a maximum of 10 pending job executions. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/job-limits.html) | 10 | 15 |
## Active and concurrent job limits
This section will help you learn more about active and concurrent jobs and the limits that apply to them.
**Active jobs and active job limit**
When you create a job by using the AWS IoT console or the `CreateJob` API, the job status changes to `IN_PROGRESS`. All in-progress jobs are *active jobs* and count towards the active jobs limit. This includes jobs that are either rolling out new job executions, or jobs that are waiting for devices to complete their job executions. This limit applies to both continuous and snapshot jobs.
**Concurrent jobs and job concurrency limit**
In-progress jobs that are either rolling out new job executions, or jobs that are canceling previously created job executions are *concurrent jobs* and count towards the job concurrency limit. AWS IoT Jobs can roll out and cancel job executions swiftly at a rate of 1000 devices per minute. Each job is `concurrent` and counts towards the job concurrency limit only for a short time. After the job executions have been rolled out or canceled, the job is no longer concurrent and does not count towards the job concurrency limit. You can use the job concurrency to create a large number of jobs while waiting for devices to complete the job execution.
**Note**
If a job with the optional scheduling configuration and job document rollout scheduled to take place during a maintenance window reaches the selected `startTime` and you're at your maximum job concurrency limit, then that scheduled job will move to a status state of `CANCELED`.
To determine whether a job is concurrent, you can use the `IsConcurrent` property of a job from the AWS IoT console, or by using the `DescribeJob` or `ListJob` API. This limit applies to both continuous and snapshot jobs.
To view the active jobs and job concurrency limits and other AWS IoT Jobs quotas for your AWS account and to request a limit increase, see [AWS IoT Device Management endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/iot_device_management.html#job-limits) in the AWS General Reference.
The following diagram shows how the job concurrency applies to in-progress jobs and jobs that are being canceled.
![\[Image showing the different states of an AWS IoT job.\]](http://docs.aws.amazon.com/iot/latest/developerguide/images/job-states-concurrency.png)
**Note**
New jobs with the optional `SchedulingConfig` will maintain an initial status state of `SCHEDULED` and update to `IN_PROGRESS` upon reaching the selected `startTime`. After the new job with the optional `SchedulingConfig` reaches the selected `startTime` and updates to `IN_PROGRESS`, it will count towards the active jobs limit and job concurrency limit. Jobs with a status state of `SCHEDULED` will count towards the active jobs limit, but will not count towards the job concurrency limit.
The following table shows the limits that apply to active and concurrent jobs and the concurrent and non-concurrent phases of the job states.
**Active and concurrent job limits**
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/iot/latest/developerguide/job-limits.html)
**Note**
The max duration of a recurring maintenance window is 23 hours, 50 minutes.