# Create and manage jobs by using the AWS CLI Create and manage jobs using the CLI This section describes how to create and manage jobs. ## Create jobs To create an AWS IoT job, use the **CreateJob** command. 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 Amazon Resource Name (ARN) that has permission to download the file and grants permission to the AWS IoT Jobs service to assume the role. For more information on the syntax when entering the date and time using an API command or the AWS CLI, see [Timestamp](https://docs.aws.amazon.com/cli/latest/userguide/cli-usage-parameters-types.html#parameter-type-timestamp). ### Code signing with jobs If you're using code signing for AWS IoT, you must start a code signing job and include the output in your job document. This will replace the code sign signature placeholder in your job document, which is required as a placeholder until it is replaced with the signed code file path using your **Code signing profile**. The code sign signature placeholder will look like the following: ``` ${aws:iot:code-sign-signature:s3://region.bucket/code-file@code-file-version-id} ``` Use the [start-signing-job](https://docs.aws.amazon.com/signer/latest/developerguide/api-startsigningjob.html) command to create a code signing job. `start-signing-job` returns a job ID. To get the Amazon S3 location where the signature is stored, use the **describe-signing-job** command. You can then download the signature from Amazon S3. For more information about code signing jobs, see [Code signing for AWS IoT](https://docs.aws.amazon.com/signer/latest/developerguide/Welcome.html). 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: ``` { "presign": "${aws:iot:s3-presigned-url:https://s3.region.amazonaws.com/bucket/image}", } ``` ### Create 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/amzn-s3-demo-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 run 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 isn't set to another terminal state before the time expires, it's 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, it fails and switches to the terminal `TIMED_OUT` status. AWS IoT also publishes an MQTT notification. For more information about creating configurations for job rollouts and aborts, see [Job Rollout and Abort Configuration](job-rollout-abort.html). **Note** Job documents that are specified as Amazon S3 files are retrieved at the time you create the job. If you change the contents of the Amazon S3 file that you used as the source of your job document after you've created the job document, then what's sent to the job targets doesn't change. ## Update a job To update a job, use the **UpdateJob** command. 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](job-rollout-abort.html). ## Cancel a job To cancel a job, use the **CancelJob** command. 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 keeps 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, but only if you specify the optional `--force` parameter. Job executions in a terminal state aren't canceled. **Warning** Canceling a job that's in the `IN_PROGRESS` state (by setting the `--force` parameter) cancels any job executions that are in progress and causes the device that's running 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's 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 To cancel a job execution on a device, use the **CancelJobExecution** command. It cancels a job execution that's in a `QUEUED` state. If you want to cancel a job execution that's 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's in a `QUEUED` state is canceled. A job execution that's in an `IN_PROGRESS` state is canceled, but only if you specify the optional `--force` parameter. Job executions in a terminal state can't be canceled. **Warning** When you cancel a job execution that's in the `IN_PROGRESS` state, the device can't update the job execution status. Use caution and make sure 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 isn't 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 on various factors. ## Delete a job To delete a job and its job executions, use the **DeleteJob** command. By default, you can only delete a job that's in a terminal state (`SUCCEEDED` or `CANCELED`). Otherwise, an exception occurs. You can delete a job in the `IN_PROGRESS` state, however, only if the `force` parameter is set to `true`. To delete a job, run the following command: ``` aws iot delete-job --job-id 010 --force|--no-force ``` The command displays no output. **Warning** When you delete a job that's in the `IN_PROGRESS` state, the device that's deploying the job can't access job information or update the job execution status. Use caution and make sure that each device deploying a job that's 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 with a status that's 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 To retrieve a job document for a job, use the **GetJobDocument** command. A job document is a description of the remote operations to be performed by the devices. To get a job document, run the following command: ``` 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/amzn-s3-demo-bucket/datafile}\"\n}" } ``` **Note** When you use this command to retrieve a job document, placeholder URLs aren't replaced by presigned Amazon S3 URLs. When a device calls the [GetPendingJobExecutions](https://docs.aws.amazon.com/iot/latest/apireference/API_iot-jobs-data_GetPendingJobExecutions.html) API operation, the placeholder URLs are replaced by presigned Amazon S3 URLs in the job document. ## List jobs To get a list of all jobs in your AWS account, use the **ListJobs** command. Job data and job execution data are retained for a [limited time](https://docs.aws.amazon.com//general/latest/gr/iot_device_management.html#job-limits). 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 To get the status of a job, run the **DescribeJob** command. 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/amzn-s3-demo-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 [https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html](https://docs.aws.amazon.com/iot/latest/apireference/API_JobExecution.html). 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's executing the job can't access job information or update the job execution status. Use caution and make sure that the device can recover to a valid state.