# Use AWS managed templates to deploy common remote operations AWS managed templates are job templates provided by AWS. They're used for frequently performed remote actions such as rebooting, downloading a file, or installing an application on your devices. These templates have a predefined job document for each remote action so you don't have to create your own job document. You can choose from a set of predefined configurations and create jobs using these templates without writing any additional code. Using managed templates, you can view the job document deployed to your fleets. You can create a job using these templates and create a custom job template that you can reuse for your remote operations. ## What do managed templates contain? Each AWS managed template contains: + The environment to run the commands in the job document. + A job document that specifies the name of the operation and its parameters. For example, if you use a **Download file** template, the operation name is *Download file* and the parameters can be: + The URL of the file that you want to download to your device. This can be an internet resource or a public or pre-signed Amazon Simple Storage Service((Amazon S3) URL. + A local file path on the device to store the downloaded file. For more information about the job documents and its parameters, see [Managed template remote actions and job documents](#job-template-manage-actions). ## Prerequisites For your devices to run the remote actions specified by the managed template job document, you must: + **Install the specific software on your device** Use your own device software and job handlers, or the AWS IoT Device Client. Depending on your business case, you can also run them both so that they perform different functions. + **Use your own device software and job handlers** You can write your own code for the devices by using the AWS IoT Device SDK and its library of handlers that support the remote operations. To deploy and run jobs, verify that the device agent libraries have been installed correctly and are running on the devices. You can also choose to use your own handlers that support the remote operations. For more information, see [Sample job handlers](https://github.com/awslabs/aws-iot-device-client/tree/main/sample-job-handlers) in the AWS IoT Device Client GitHub repository. + **Use the AWS IoT Device Client** Or, you can install and run the AWS IoT Device Client on your devices because it supports using all managed templates directly from the console by default. The Device Client is an open-source software written in C\$1\$1 that you can compile and install on your embedded Linux-based IoT devices. The Device Client has a *base client* and discrete *client-side features*. The base client establishes connectivity with AWS IoT over MQTT protocol and can connect with the different client-side features. To perform remote operations on your devices, use the *client-side Jobs feature* of the Device Client. This feature contains a parser to receive the job document and job handlers that implement the remote actions specified in the job document. For more information about the Device Client and its features, see [AWS IoT Device Client](https://github.com/awslabs/aws-iot-device-client#readme). When running on devices, the Device Client receives the job document and has a platform-specific implementation that it uses to run commands in the document. For more information about setting up the Device Client and using the Jobs feature, see [AWS IoT tutorials](https://docs.aws.amazon.com/iot/latest/developerguide/iot-tutorials.html). + **Use a supported environment** For each managed template, you'll find information about the environment that you can use to run the remote actions. We recommend that you use the template with a supported Linux environment as specified in the template. Use the AWS IoT Device Client to run the managed template remote actions because it supports common microprocessors and Linux environments, like Debian and Ubuntu. ## Managed template remote actions and job documents The following section lists the different AWS managed templates for AWS IoT Jobs, and describes the remote actions that can be performed on the devices. The following section has information about the job document and a description of the job document parameters for each remote action. Your device-side software uses the template name and the parameters to perform the remote action. AWS managed templates accept input parameters for which you specify a value when creating a job using the template. All managed templates have two optional input parameters in common: `runAsUser` and `pathToHandler`. Except for the `AWS-Reboot` template, the templates require additional input parameters for which you must specify a value when creating a job using the template. These required input parameters vary depending on the template that you choose. For example, if you choose the `AWS-Download-File` template, you must specify a list of packages to install, and a URL to download files from. Specify a value for the input parameters when using the AWS IoT console or the AWS Command Line Interface (AWS CLI) to create a job that uses a managed template. When using the CLI, provide these values by using the `document-parameters` object. For more information, see [ documentParameters](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html#iot-CreateJob-request-documentParameters). **Note** Use `document-parameters` only when creating jobs from AWS managed templates. This parameter can't be used with custom job templates or to create jobs from them. The following shows a description of the common optional input parameters. You'll see a description of other input parameters that each managed template requires in the next section. `runAsUser` This parameter specifies whether to run the job handler as another user. If it's not specified during job creation, the job handler is run as the same user as the Device Client. When you run the job handler as another user, specify a string value that's not longer than 256 characters. `pathToHandler` The path to the job handler running on the device. If it's not specified during job creation, the Device Client uses the current working directory. The following shows the different remote actions, their job documents, and parameters that they accept. All these templates support the Linux environment for running the remote operation on the device. ### AWS–Download–File **Template name** `AWS–Download–File` **Template description** A managed template provided by AWS for downloading a file. **Input parameters** This template has the following required parameters. You can also specify the optional parameters `runAsUser` and `pathToHandler`. `downloadUrl` The URL to download the file from. This can be an internet resource, an object in Amazon S3 that can be publicly accessed, or an object in Amazon S3 that can only be accessed by your device using a presigned URL. For more information about using presigned URLs and granting permissions, see [Presigned URLs](create-manage-jobs.md#create-manage-jobs-presigned-URLs). `filePath` A local file path that shows the location in the device to store the downloaded file. **Device behavior** The device downloads the file from the specified location, verifies that the download is complete, and stores it locally. **Job document** The following shows the job document and its latest version. The template shows the path to the job handler and the shell script, `download-file.sh`, that the job handler must run to download the file. It also shows the required parameters `downloadUrl` and `filePath`. ``` { "version": "1.0", "steps": [ { "action": { "name": "Download-File", "type": "runHandler", "input": { "handler": "download-file.sh", "args": [ "${aws:iot:parameter:downloadUrl}", "${aws:iot:parameter:filePath}" ], "path": "${aws:iot:parameter:pathToHandler}" }, "runAsUser": "${aws:iot:parameter:runAsUser}" } } ] } ``` ### AWS–Install–Application **Template name** `AWS–Install–Application` **Template description** A managed template provided by AWS for installing one or more applications. **Input parameters** This template has the following required parameter, `packages`. You can also specify the optional parameters `runAsUser` and `pathToHandler`. `packages` A space-separated list of one or more applications to be installed. **Device behavior** The device installs the applications as specified in the job document. **Job document** The following shows the job document and its latest version. The template shows the path to the job handler and the shell script, `install-packages.sh`, that the job handler must run to download the file. It also shows the required parameter `packages`. ``` { "version": "1.0", "steps": [ { "action": { "name": "Install-Application", "type": "runHandler", "input": { "handler": "install-packages.sh", "args": [ "${aws:iot:parameter:packages}" ], "path": "${aws:iot:parameter:pathToHandler}" }, "runAsUser": "${aws:iot:parameter:runAsUser}" } } ] } ``` ### AWS–Reboot **Template name** `AWS–Reboot` **Template description** A managed template provided by AWS for rebooting your device. **Input parameters** This template has no required parameters. You can specify the optional parameters `runAsUser` and `pathToHandler`. **Device behavior** The device reboots successfully. **Job document** The following shows the job document and its latest version. The template shows the path to the job handler and the shell script, `reboot.sh`, that the job handler must run to reboot the device. ``` { "version": "1.0", "steps": [ { "action": { "name": "Reboot", "type": "runHandler", "input": { "handler": "reboot.sh", "path": "${aws:iot:parameter:pathToHandler}" }, "runAsUser": "${aws:iot:parameter:runAsUser}" } } ] } ``` ### AWS–Remove–Application **Template name** `AWS–Remove–Application` **Template description** A managed template provided by AWS for uninstalling one or more applications. **Input parameters** This template has the following required parameter, `packages`. You can also specify the optional parameters `runAsUser` and `pathToHandler`. `packages` A space-separated list of one or more applications to be uninstalled. **Device behavior** The device uninstalls the applications as specified in the job document. **Job document** The following shows the job document and its latest version. The template shows the path to the job handler and the shell script, `remove-packages.sh`, that the job handler must run to download the file. It also shows the required parameter `packages`. ``` { "version": "1.0", "steps": [ { "action": { "name": "Remove-Application", "type": "runHandler", "input": { "handler": "remove-packages.sh", "args": [ "${aws:iot:parameter:packages}" ], "path": "${aws:iot:parameter:pathToHandler}" }, "runAsUser": "${aws:iot:parameter:runAsUser}" } } ] } ``` ### AWS–Restart–Application **Template name** `AWS–Restart–Application` **Template description** A managed template provided by AWS for stopping and restarting one or more services. **Input parameters** This template has the following required parameter, `services`. You can also specify the optional parameters `runAsUser` and `pathToHandler`. **Services** A space-separated list of one or more applications to be restarted. **Device behavior** The specified applications are stopped and then restarted on the device. **Job document** The following shows the job document and its latest version. The template shows the path to the job handler and the shell script, `restart-services.sh`, that the job handler must run to restart the system services. It also shows the required parameter `services`. ``` { "version": "1.0", "steps": [ { "action": { "name": "Restart-Application", "type": "runHandler", "input": { "handler": "restart-services.sh", "args": [ "${aws:iot:parameter:services}" ], "path": "${aws:iot:parameter:pathToHandler}" }, "runAsUser": "${aws:iot:parameter:runAsUser}" } } ] } ``` ### AWS–Start–Application **Template name** `AWS-Start-Application` **Template description** A managed template provided by AWS for starting one or more services. **Input parameters** This template has the following required parameter, `services`. You can also specify the optional parameters `runAsUser` and `pathToHandler`. `services` A space-separated list of one or more applications to be started. **Device behavior** The specified applications start running on the device. **Job document** The following shows the job document and its latest version. The template shows the path to the job handler and the shell script, `start-services.sh`, that the job handler must run to start the system services. It also shows the required parameter `services`. ``` { "version": "1.0", "steps": [ { "action": { "name": "Start-Application", "type": "runHandler", "input": { "handler": "start-services.sh", "args": [ "${aws:iot:parameter:services}" ], "path": "${aws:iot:parameter:pathToHandler}" }, "runAsUser": "${aws:iot:parameter:runAsUser}" } } ] } ``` ### AWS–Stop–Application **Template name** `AWS–Stop–Application` **Template description** A managed template provided by AWS for stopping one or more services. **Input parameters** This template has the following required parameter, `services`. You can also specify the optional parameters `runAsUser` and `pathToHandler`. `services` A space-separated list of one or more applications to be stopped. **Device behavior** The specified applications stop running on the device. **Job document** The following shows the job document and its latest version. The template shows the path to the job handler and the shell script, `stop-services.sh`, that the job handler must run to stop the system services. It also shows the required parameter `services`. ``` { "version": "1.0", "steps": [ { "action": { "name": "Stop-Application", "type": "runHandler", "input": { "handler": "stop-services.sh", "args": [ "${aws:iot:parameter:services}" ], "path": "${aws:iot:parameter:pathToHandler}" }, "runAsUser": "${aws:iot:parameter:runAsUser}" } } ] } ``` ### AWS–Run–Command **Template name** `AWS–Run–Command` **Template description** A managed template provided by AWS for running a shell command. **Input parameters** This template has the following required parameter, `command`. You can also specify the optional parameter `runAsUser`. `command` A comma separated string of command. Any comma contained in the command itself must be escaped. **Device behavior** The device runs the shell command as specified in the job document. **Job document** The following shows the job document and its latest version. The template shows the path to the job command and the command that you provided which the device will run. ``` { "version": "1.0", "steps": [ { "action": { "name": "Run-Command", "type": "runCommand", "input": { "command": "${aws:iot:parameter:command}" }, "runAsUser": "${aws:iot:parameter:runAsUser}" } } ] } ``` **Topics** + [What do managed templates contain?](#job-template-managed-contains) + [Prerequisites](#job-template-managed-prereq) + [Managed template remote actions and job documents](#job-template-manage-actions) + [Create a job from AWS managed templates by using the AWS Management Console](job-template-manage-console-create.md) + [Create a job from AWS managed templates by using the AWS CLI](job-template-manage-cli-create.md) # Create a job from AWS managed templates by using the AWS Management Console Use the AWS Management Console to get information about AWS managed templates and create a job by using these templates. You can then save the job you create as your own custom template. ## Get details about managed templates You can get information about the different managed templates that are available to use from the AWS IoT console. 1. To see your available managed templates, go to the [Job templates hub of the AWS IoT console](https://console.aws.amazon.com/iot/home#/jobtemplatehub) and choose the **Managed templates** tab. 1. To view details, choose a managed template. The details page contains the following information: + Name, description, and Amazon Resource Name (ARN) of the managed template. + The environment on which the remote operations can be performed, such as Linux. + The JSON job document that specifies the path to the job handler and the commands to run on the device. For example, the following shows an example job document for the **AWS-Reboot** template. The template shows the path to the job handler and the shell script, `reboot.sh`, that the job handler must run to reboot the device. ``` { "version": "1.0", "steps": [ { "action": { "name": "Reboot", "type": "runHandler", "input": { "handler": "reboot.sh", "path": "${aws:iot:parameter:pathToHandler}" }, "runAsUser": "${aws:iot:parameter:runAsUser}" } } ] } ``` For more information about the job document and its parameters for various remote actions, see [Managed template remote actions and job documents](job-templates-managed.md#job-template-manage-actions). + The latest version of the job document. ## Create a job using managed templates You can use the AWS Management console to choose an AWS managed template to use to create a job. This section shows you how. You can also start the job creation workflow and then choose the AWS managed template that you want to use while creating the job. For more information about this workflow, see [Create and manage jobs by using the AWS Management Console](manage-job-console.md). 1. **Choose your AWS managed template** Go to the [Job templates hub of the AWS IoT console](https://console.aws.amazon.com/iot/home#/jobtemplatehub), choose the **Managed templates** tab, and then choose your template. 1. **Create a job using your managed template** 1. In the details page of your template, choose **Create job**. The console switches to the **Custom job properties** step of the **Create job** workflow where your template configuration has been added. 1. Enter a unique alphanumeric job name, and optional description and tags, and then choose **Next**. 1. Choose the things or thing groups as job targets that you want to run in this job. 1. In the **Job document** section, your template is displayed with its configuration settings and input parameters. Enter values for the input parameters of your chosen template. For example, if you chose the **AWS-Download-File** template: + For **downloadUrl**, enter the URL of the file to download, for example: `https://example.com/index.html`. + For **filePath**, enter the path on the device to store the downloaded file, for example: `path/to/file`. You can also optionally enter values for the parameters `runAsUser` and `pathToHandler`. For more information about the input parameters of each template, see [Managed template remote actions and job documents](job-templates-managed.md#job-template-manage-actions). 1. On the **Job configuration** page, choose the job type as continuous or a snapshot job. A snapshot job is complete when it finishes its run on the target devices and groups. A continuous job applies to thing groups and runs on any device that you add to a specified target group. 1. Continue to add any additional configurations for your job and then review and create your job. For information about the additional configurations, see: + [Job rollout, scheduling, and abort configurations](jobs-configurations-details.md#job-rollout-abort-scheduling) + [Job execution timeout and retry configurations](jobs-configurations-details.md#job-timeout-retry) ## Create custom job templates from managed templates You can use an AWS managed template and a custom job as a starting point to create your own custom job template. To create a custom job template, first create a job from your AWS managed template as described in the previous section. You can then save the custom job as a template to create your own custom job template. To save as template: 1. Go to the [Job hub of the AWS IoT console](https://console.aws.amazon.com/iot/home#/jobhub) and choose the job containing your managed template. 1. Choose **Save as a job template** and then create your custom job template. For more information about creating a custom job template, see [Create a job template from an existing job](job-templates-console.md#job-templates-console-create-exist-job). # Create a job from AWS managed templates by using the AWS CLI Use the AWS CLI to get information about AWS managed templates and create a job by using these templates. You can then save the job as a template and then create your own custom template. ## List managed templates The [https://docs.aws.amazon.com/cli/latest/reference/iot/list-managed-job-templates.html](https://docs.aws.amazon.com/cli/latest/reference/iot/list-managed-job-templates.html) AWS CLI command lists all of the job templates in your AWS account. ``` aws iot list-managed-job-templates ``` By default, running this command displays all available AWS managed templates and their details. ``` { "managedJobTemplates": [ { "templateArn": "arn:aws:iot:region::jobtemplate/AWS-Reboot:1.0", "templateName": "AWS-Reboot", "description": "A managed job template for rebooting the device.", "environments": [ "LINUX" ], "templateVersion": "1.0" }, { "templateArn": "arn:aws:iot:region::jobtemplate/AWS-Remove-Application:1.0", "templateName": "AWS-Remove-Application", "description": "A managed job template for uninstalling one or more applications.", "environments": [ "LINUX" ], "templateVersion": "1.0" }, { "templateArn": "arn:aws:iot:region::jobtemplate/AWS-Stop-Application:1.0", "templateName": "AWS-Stop-Application", "description": "A managed job template for stopping one or more system services.", "environments": [ "LINUX" ], "templateVersion": "1.0" }, ... { "templateArn": "arn:aws:iot:us-east-1::jobtemplate/AWS-Restart-Application:1.0", "templateName": "AWS-Restart-Application", "description": "A managed job template for restarting one or more system services.", "environments": [ "LINUX" ], "templateVersion": "1.0" } ] } ``` For more information, see [ListManagedJobTemplates](https://docs.aws.amazon.com/iot/latest/apireference/API_ListManagedJobTemplates.html). ## Get details about a managed template The [https://docs.aws.amazon.com/cli/latest/reference/iot/describe-managed-job-template.html](https://docs.aws.amazon.com/cli/latest/reference/iot/describe-managed-job-template.html) AWS CLI command gets details about a specified job template. Specify the job template name and an optional template version. If the template version is not specified, the predefined, default version is returned. The following shows an example of running the command to get details about the `AWS-Download-File` template. ``` aws iot describe-managed-job-template \ --template-name AWS-Download-File ``` The command displays the template details and ARN, its job document, and the `documentParameters` parameter, which is a list of key-value pairs of input parameters of the template. For information about the different templates and input parameters, see [Managed template remote actions and job documents](job-templates-managed.md#job-template-manage-actions). **Note** The `documentParameters` object returned when you use this API must only be used when creating jobs from AWS managed templates. The object must not be used for custom job templates. For an example that shows how to use this parameter, see [Create a job by using managed templates](#job-template-manage-cli-create-job). ``` { "templateName": "AWS-Download-File", "templateArn": "arn:aws:iot:region::jobtemplate/AWS-Download-File:1.0", "description": "A managed job template for downloading a file.", "templateVersion": "1.0", "environments": [ "LINUX" ], "documentParameters": [ { "key": "downloadUrl", "description": "URL of file to download.", "regex": "(.*?)", "example": "http://www.example.com/index.html", "optional": false }, { "key": "filePath", "description": "Path on the device where downloaded file is written.", "regex": "(.*?)", "example": "/path/to/file", "optional": false }, { "key": "runAsUser", "description": "Execute handler as another user. If not specified, then handler is executed as the same user as device client.", "regex": "(.){0,256}", "example": "user1", "optional": true }, { "key": "pathToHandler", "description": "Path to handler on the device. If not specified, then device client will use the current working directory.", "regex": "(.){0,4096}", "example": "/path/to/handler/script", "optional": true } ], "document": "{\"version\":\"1.0\",\"steps\":[{\"action\":{\"name\":\"Download-File\",\"type\":\"runHandler\",\"input\":{\"handler\":\"download-file.sh\",\"args\":[\"${aws:iot:parameter:downloadUrl}\",\"${aws:iot:parameter:filePath}\"],\"path\":\"${aws:iot:parameter:pathToHandler}\"},\"runAsUser\":\"${aws:iot:parameter:runAsUser}\"}}]}" } ``` For more information, see [DescribeManagedJobTemplate](https://docs.aws.amazon.com/iot/latest/apireference/API_DescribeManagedJobTemplate.html). ## Create a job by using managed templates The [https://docs.aws.amazon.com/cli/latest/reference/iot/create-job.html](https://docs.aws.amazon.com/cli/latest/reference/iot/create-job.html) AWS CLI command can be used to create a job from a job template. It targets a device named `thingOne` and specifies the Amazon Resource Name (ARN) of the managed template to use as the basis for the job. You can override advanced configurations, such as timeout and cancel configurations, by passing the associated parameters of the `create-job` command. The example shows how to create a job that uses the `AWS-Download-File` template. It also shows how to specify the input parameters of the template by using the `document-parameters` parameter. **Note** Use the `document-parameters` object only with AWS managed templates. This object must not be used with custom job templates. ``` aws iot create-job \ --targets arn:aws:iot:region:account-id:thing/thingOne \ --job-id "new-managed-template-job" \ --job-template-arn arn:aws:iot:region::jobtemplate/AWS-Download-File:1.0 \ --document-parameters downloadUrl=https://example.com/index.html,filePath=path/to/file ``` where: + *region* is the AWS Region. + *account-id* is the unique AWS account number. + `thingOne` is the name of the IoT thing for which the job is targeted. + *AWS-Download-File:1.0* is the name of the managed template. + `https://example.com/index.html` is the URL to download the file from. + `https://pathto/file/index` is the path on the device to store the downloaded file. Run the following command to create a job for the template, `AWS-Download-File`. ``` { "jobArn": "arn:aws:iot:region:account-id:job/new-managed-template-job", "jobId": "new-managed-template-job", "description": "A managed job template for downloading a file." } ``` ## Create a custom job template from managed templates 1. Create a job using a managed template as described in the previous section. 1. Create a custom job template by using the ARN of the job that you created. For more information, see [Create a job template from an existing job](job-templates-cli.md#job-templates-cli-create-from-job).