Creating and Managing Jobs (CLI)

This section describes how to create and manage jobs.

Create Jobs

You use the CreateJob command to create an AWS IoT job. 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 ARN that has permission to download the file and grants permission to the AWS IoT Jobs service to assume the role.

Code-signing with Jobs

If you are using Code-signing for AWS IoT, you must start a code-signing job and include the output in your job document. Use the start-signing-job command to create a code-signing job. start-signing-job returns a job ID. Use the describe-signing-job command to get the Amazon S3 location where the signature is stored. You can then download the signature from Amazon S3. For more information about code signing jobs, see Code-signing for AWS IoT.

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, enclosed in a codesign element:

{
    "presign": "${aws:iot:s3-presigned-url:https://s3.region.amazonaws.com/bucket/image}",
    "codesign": {
        "rawPayloadSize": <image-file-size>,
        "signature": <signature>,
        "signatureAlgorithm": <signature-algorithm>,
        "payloadLocation": {
            "s3": {
                "bucketName": <my-s3-bucket>,
                "key": <my-code-file>,
                "version": <code-file-version-id>
            }
        }
    }
}

Creating 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/my-s3-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 executed 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 is not set to another terminal state before the time expires, it is 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, the job execution 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.

Note

Job documents that are specified as Amazon S3 files are retrieved at the time you create the job. Changing the contents of the Amazon S3 file you used as the source of your job document after you have created the job does not change what is sent to the targets of the job.

Update a Job

You use the UpdateJob command to update a job. 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.

Cancel a Job

You use the CancelJob command to cancel a job. 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 leaves 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 if you specify the optional --force parameter. Job executions in a terminal state are not canceled.

Warning

Canceling a job that is in the IN_PROGRESS state (by setting the --force parameter) cancels any job executions that are in progress and causes the device that is executing 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 has 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

You use the CancelJobExecution command to cancel a job execution on a device. It cancels a job execution that is in a QUEUED state. If you want to cancel a job execution that is 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 is in a QUEUED state is canceled. A job execution that is in an IN_PROGRESS state is canceled if you specify the optional --force parameter. Job executions in a terminal state cannot be canceled.

Warning

When you cancel a job execution that is in the IN_PROGRESS state, the device cannot update the job execution status. Use caution and ensure 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 is not 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 various factors.

Delete a Job

You use the DeleteJob command to delete a job and its job executions. By default, you can only delete a job that is in a terminal state (SUCCEEDED or CANCELED). Otherwise, an exception occurs. You can delete a job in the IN_PROGRESS state if the force parameter is set to true.

Run the following command to delete a job:

aws iot delete-job --job-id 010 --force|--no-force

The command displays no output.

Warning

When you delete a job that is in the IN_PROGRESS state, the device that is executing the job cannot access job information or update the job execution status. Use caution and make sure that each device executing a job that has 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 whose status is 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

You use the GetJobDocument command to retrieve a job document for a job. A job document is a description of the remote operations to be performed by the devices.

Run the following command to get a job document:

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/job-test-bucket/datafile}\"\n}"
}

Note

When you use this command to retrieve a job document, placeholder URLs are not replaced by presigned Amazon S3 URLs. When a device calls the GetPendingJobExecutions MQTT API, the placeholder URLs are replaced by presigned Amazon S3 URLs in the job document.

List Jobs

You use the ListJobs command to get a list of all jobs in your AWS account. Job data and job execution data are retained for a limited time. 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

Run the DescribeJob command to get the status of a job. 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/job-test-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 JobExecution. 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 is executing the job cannot access job information or update the job execution status. Use caution and make sure that the device can recover to a valid state.