Jobs key concepts

A job is a remote operation that is sent to and run on one or more devices connected to Amazon 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.

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.

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 or both. The Amazon IoT Jobs service sends a message to each target to inform it that a job is available.

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.

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 Amazon IoT. An execution number is a unique identifier of a job execution on a specific target. The Amazon 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.

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.

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.

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.

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.

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.

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.

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.