# 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`.