jobs

Creates, updates, deletes, gets or lists a jobs resource.

Overview

Name	jobs
Type	Resource
Id	aws.iot.jobs

Fields

The following fields are returned by SELECT queries:

describe_job

Name	Datatype	Description
document_source	string	An S3 link to the job document.
job	object	Information about the job.

list_jobs

Name	Datatype	Description
completed_at	string (date-time)	The time, in seconds since the epoch, when the job completed.
created_at	string (date-time)	The time, in seconds since the epoch, when the job was created.
is_concurrent	boolean	Indicates whether a job is concurrent. Will be true when a job is rolling out new job executions or canceling previously created executions, otherwise false.
job_arn	string	The job ARN.
job_id	string	The unique identifier you assigned to this job when it was created. (pattern: <code>[a-zA-Z0-9_-]+</code>)
last_updated_at	string (date-time)	The time, in seconds since the epoch, when the job was last updated.
status	string	The job summary status. (IN_PROGRESS, CANCELED, COMPLETED, DELETION_IN_PROGRESS, SCHEDULED)
target_selection	string	Specifies whether the job will continue to run (CONTINUOUS), or will be complete after all those things specified as targets have completed the job (SNAPSHOT). If continuous, the job may also be run on a thing when a change is detected in a target. For example, a job will run on a thing when the thing is added to a target group, even after the job was completed by all things originally in the group. We recommend that you use continuous jobs instead of snapshot jobs for dynamic thing group targets. By using continuous jobs, devices that join the group receive the job execution even after the job has been created. (CONTINUOUS, SNAPSHOT)
thing_group_id	string	The ID of the thing group. (pattern: <code>[a-zA-Z0-9-]+</code>)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_job	select	job_id, region	beforeSubstitution	Describes a job. Requires permission to access the DescribeJob action.
list_jobs	select	region	status, targetSelection, maxResults, nextToken, thingGroupName, thingGroupId, namespaceId	Lists jobs. Requires permission to access the ListJobs action.
create_job	insert	job_id, region, targets		Creates a job. Requires permission to access the CreateJob action.
associate_targets_with_job	update	job_id, region, targets	namespaceId	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. Requires permission to access the AssociateTargetsWithJob action.
update_job	update	job_id, region	namespaceId	Updates supported fields of the specified job. Requires permission to access the UpdateJob action.
delete_job	delete	job_id, region	force, namespaceId	Deletes a job and its related job executions. Deleting a job may 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 will be shown as "DELETION_IN_PROGRESS". Attempting to delete or cancel a job whose status is already "DELETION_IN_PROGRESS" will result in an error. Only 10 jobs may have status "DELETION_IN_PROGRESS" at the same time, or a LimitExceededException will occur. Requires permission to access the DeleteJob action.
cancel_job	exec	job_id, region	force	Cancels a job. Requires permission to access the CancelJob action.
cancel_job_execution	exec	job_id, thing_name, region	force	Cancels the execution of a job for a given thing. Requires permission to access the CancelJobExecution action.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
job_id	string	The ID of the job to be canceled.
region	string	AWS region (default: us-east-1)
thing_name	string	The name of the thing whose execution of the job will be canceled.
beforeSubstitution	boolean	Provides a view of the job document before and after the substitution parameters have been resolved with their exact values.
force	boolean	(Optional) If true the job execution will be canceled if it has status IN_PROGRESS or QUEUED, otherwise the job execution will be canceled only if it has status QUEUED. If you attempt to cancel a job execution that is IN_PROGRESS, and you do not set force to true, then an InvalidStateTransitionException will be thrown. The default is false. Canceling a job execution which is "IN_PROGRESS", will cause the device to be unable to update the job execution status. Use caution and ensure that the device is able to recover to a valid state.
maxResults	integer	The maximum number of results to return per request.
namespaceId	string	The namespace used to indicate that a job is a customer-managed job. When you specify a value for this parameter, Amazon Web Services IoT Core sends jobs notifications to MQTT topics that contain the value in the following format. $aws/things/THING_NAME/jobs/JOB_ID/notify-namespace-NAMESPACE_ID/ The namespaceId feature is only supported by IoT Greengrass at this time. For more information, see Setting up IoT Greengrass core devices.
nextToken	string	The token to retrieve the next set of results.
status	string	An optional filter that lets you search for jobs that have the specified status.
targetSelection	string	Specifies whether the job will continue to run (CONTINUOUS), or will be complete after all those things specified as targets have completed the job (SNAPSHOT). If continuous, the job may also be run on a thing when a change is detected in a target. For example, a job will run on a thing when the thing is added to a target group, even after the job was completed by all things originally in the group. We recommend that you use continuous jobs instead of snapshot jobs for dynamic thing group targets. By using continuous jobs, devices that join the group receive the job execution even after the job has been created.
thingGroupId	string	A filter that limits the returned jobs to those for the specified group.
thingGroupName	string	A filter that limits the returned jobs to those for the specified group.

SELECT examples

describe_job

Describes a job. Requires permission to access the DescribeJob action.

SELECT
document_source,
job
FROM aws.iot.jobs
WHERE job_id = '{{ job_id }}' -- required
AND region = '{{ region }}' -- required
AND beforeSubstitution = '{{ beforeSubstitution }}'
;

list_jobs

Lists jobs. Requires permission to access the ListJobs action.

SELECT
completed_at,
created_at,
is_concurrent,
job_arn,
job_id,
last_updated_at,
status,
target_selection,
thing_group_id
FROM aws.iot.jobs
WHERE region = '{{ region }}' -- required
AND status = '{{ status }}'
AND targetSelection = '{{ targetSelection }}'
AND maxResults = '{{ maxResults }}'
AND nextToken = '{{ nextToken }}'
AND thingGroupName = '{{ thingGroupName }}'
AND thingGroupId = '{{ thingGroupId }}'
AND namespaceId = '{{ namespaceId }}'
;

INSERT examples

create_job

Creates a job. Requires permission to access the CreateJob action.

INSERT INTO aws.iot.jobs (
targets,
documentSource,
document,
description,
presignedUrlConfig,
targetSelection,
jobExecutionsRolloutConfig,
abortConfig,
timeoutConfig,
tags,
namespaceId,
jobTemplateArn,
jobExecutionsRetryConfig,
documentParameters,
schedulingConfig,
destinationPackageVersions,
job_id,
region
)
SELECT 
'{{ targets }}' /* required */,
'{{ documentSource }}',
'{{ document }}',
'{{ description }}',
'{{ presignedUrlConfig }}',
'{{ targetSelection }}',
'{{ jobExecutionsRolloutConfig }}',
'{{ abortConfig }}',
'{{ timeoutConfig }}',
'{{ tags }}',
'{{ namespaceId }}',
'{{ jobTemplateArn }}',
'{{ jobExecutionsRetryConfig }}',
'{{ documentParameters }}',
'{{ schedulingConfig }}',
'{{ destinationPackageVersions }}',
'{{ job_id }}',
'{{ region }}'
RETURNING
description,
job_arn,
job_id
;

Manifest

# Description fields are for documentation purposes
- name: jobs
props:
  - name: job_id
    value: "{{ job_id }}"
    description: Required parameter for the jobs resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the jobs resource.
  - name: targets
    value:
      - "{{ targets }}"
  - name: documentSource
    value: "{{ documentSource }}"
  - name: document
    value: "{{ document }}"
  - name: description
    value: "{{ description }}"
  - name: presignedUrlConfig
    description: |
      Configuration for pre-signed S3 URLs.
    value:
      roleArn: "{{ roleArn }}"
      expiresInSec: {{ expiresInSec }}
  - name: targetSelection
    value: "{{ targetSelection }}"
    valid_values: ['CONTINUOUS', 'SNAPSHOT']
  - name: jobExecutionsRolloutConfig
    description: |
      Allows you to create a staged rollout of a job.
    value:
      maximumPerMinute: {{ maximumPerMinute }}
      exponentialRate:
        baseRatePerMinute: {{ baseRatePerMinute }}
        incrementFactor: {{ incrementFactor }}
        rateIncreaseCriteria:
          numberOfNotifiedThings: {{ numberOfNotifiedThings }}
          numberOfSucceededThings: {{ numberOfSucceededThings }}
  - name: abortConfig
    description: |
      The criteria that determine when and how a job abort takes place.
    value:
      criteriaList:
        - failureType: "{{ failureType }}"
          action: "{{ action }}"
          thresholdPercentage: {{ thresholdPercentage }}
          minNumberOfExecutedThings: {{ minNumberOfExecutedThings }}
  - name: timeoutConfig
    description: |
      Specifies the amount of time each device has to finish its execution of the job. A timer is started when the job execution status is set to IN_PROGRESS. If the job execution status is not set to another terminal state before the timer expires, it will be automatically set to TIMED_OUT.
    value:
      inProgressTimeoutInMinutes: {{ inProgressTimeoutInMinutes }}
  - name: tags
    value:
      - Key: "{{ Key }}"
        Value: "{{ Value }}"
  - name: namespaceId
    value: "{{ namespaceId }}"
  - name: jobTemplateArn
    value: "{{ jobTemplateArn }}"
  - name: jobExecutionsRetryConfig
    description: |
      The configuration that determines how many retries are allowed for each failure type for a job.
    value:
      criteriaList:
        - failureType: "{{ failureType }}"
          numberOfRetries: {{ numberOfRetries }}
  - name: documentParameters
    value: "{{ documentParameters }}"
  - name: schedulingConfig
    description: |
      Specifies the date and time that a job will begin the rollout of the job document to all devices in the target group. Additionally, you can specify the end behavior for each job execution when it reaches the scheduled end time.
    value:
      startTime: "{{ startTime }}"
      endTime: "{{ endTime }}"
      endBehavior: "{{ endBehavior }}"
      maintenanceWindows:
        - startTime: "{{ startTime }}"
          durationInMinutes: {{ durationInMinutes }}
  - name: destinationPackageVersions
    value:
      - "{{ destinationPackageVersions }}"

UPDATE examples

associate_targets_with_job

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. Requires permission to access the AssociateTargetsWithJob action.

UPDATE aws.iot.jobs
SET 
targets = '{{ targets }}',
comment = '{{ comment }}'
WHERE 
job_id = '{{ job_id }}' --required
AND region = '{{ region }}' --required
AND targets = '{{ targets }}' --required
AND namespaceId = '{{ namespaceId}}'
RETURNING
description,
job_arn,
job_id;

update_job

Updates supported fields of the specified job. Requires permission to access the UpdateJob action.

UPDATE aws.iot.jobs
SET 
description = '{{ description }}',
presignedUrlConfig = '{{ presignedUrlConfig }}',
jobExecutionsRolloutConfig = '{{ jobExecutionsRolloutConfig }}',
abortConfig = '{{ abortConfig }}',
timeoutConfig = '{{ timeoutConfig }}',
jobExecutionsRetryConfig = '{{ jobExecutionsRetryConfig }}'
WHERE 
job_id = '{{ job_id }}' --required
AND region = '{{ region }}' --required
AND namespaceId = '{{ namespaceId}}';

DELETE examples

delete_job

Deletes a job and its related job executions. Deleting a job may 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 will be shown as "DELETION_IN_PROGRESS". Attempting to delete or cancel a job whose status is already "DELETION_IN_PROGRESS" will result in an error. Only 10 jobs may have status "DELETION_IN_PROGRESS" at the same time, or a LimitExceededException will occur. Requires permission to access the DeleteJob action.

DELETE FROM aws.iot.jobs
WHERE job_id = '{{ job_id }}' --required
AND region = '{{ region }}' --required
AND force = '{{ force }}'
AND namespaceId = '{{ namespaceId }}'
;

Lifecycle Methods

cancel_job

Cancels a job. Requires permission to access the CancelJob action.

EXEC aws.iot.jobs.cancel_job 
@job_id='{{ job_id }}' --required, 
@region='{{ region }}' --required, 
@force={{ force }} 
@@json=
'{
"reasonCode": "{{ reasonCode }}", 
"comment": "{{ comment }}"
}'
;

cancel_job_execution

Cancels the execution of a job for a given thing. Requires permission to access the CancelJobExecution action.

EXEC aws.iot.jobs.cancel_job_execution 
@job_id='{{ job_id }}' --required, 
@thing_name='{{ thing_name }}' --required, 
@region='{{ region }}' --required, 
@force={{ force }} 
@@json=
'{
"expectedVersion": {{ expectedVersion }}, 
"statusDetails": "{{ statusDetails }}"
}'
;