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.](/images/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 API, or CreateJobTemplate API, you can select the optional scheduling configuration in the AWS IoT console or the
SchedulingConfig
in the CreateJob API or CreateJobTemplate API. When you start a scheduled job containing a specificstartTime
,endTime
, andendBehavoir
, the job status updates toSCHEDULED
. When the job reaches your selectedstartTime
or thestartTime
of the next maintenance window (if you selected job rollout during a maintenance window), the status will update fromSCHEDULED
toIN_PROGRESS
and begin rollout of the job document to all devices in the target group. -
IN_PROGRESS
When you create a job using the AWS IoT console or the CreateJob 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 Job limits.
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 toSCHEDULED
until thestartTime
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 reachCOMPLETED
status whenendTime
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 asSUCCEEDED
,FAILED
,TIMED_OUT
,REMOVED
, orCANCELED
. -
-
CANCELED
When you cancel a job using the AWS IoT console, the CancelJob API, or the Job abort configuration, 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 Job limits.
-
DELETION_IN_PROGRESS
When you delete a job using the AWS IoT console or the DeleteJob 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_PROGRESS |
Yes | No | No | Not applicable | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
SUCCEEDED |
Yes | No | Yes | Not applicable | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
FAILED |
Yes | No | Yes | Yes | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
TIMED_OUT |
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 theQUEUED
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
.
-
-
IN_PROGRESS
If your IoT device subscribes to the reserved Job topics
$notify
and$notify-next
, and your device invokes either theStartNextPendingJobExecution
API or theUpdateJobExecution
API with a status ofIN_PROGRESS
, AWS IoT Jobs will set the job execution status toIN_PROGRESS
.The
UpdateJobExecution
API can be invoked multiple times with a status ofIN_PROGRESS
. You can specify additional details about the execution steps using thestatusDetails
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 ofSUCCEEDED
to indicate that the job execution succeeded. AWS IoT Jobs then updates and returns the job execution status asSUCCEEDED
. -
FAILED
When your device fails to complete the remote operation, the device must invoke the
UpdateJobExecution
API with a status ofFailed
to indicate that the job execution failed. AWS IoT Jobs then updates and returns the job execution status asFailed
. You can retry this job execution for the device using the Job execution retry configuration. -
TIMED_OUT
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 toTIMED_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 theinProgressTimeoutInMinutes
property of the Job execution timeout configuration. You can retry this job execution for the device using the Job execution retry configuration. -
REJECTED
When your device receives an invalid or incompatible request, the device must invoke the
UpdateJobExecution
API with a status ofREJECTED
. AWS IoT Jobs then updates and returns the job execution status asREJECTED
. -
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
orCancelJobExecution
API, or when the abort criteria specified using the Job abort configuration is met, AWS IoT Jobs cancels the job and sets the job execution status toCANCELED
.