Preparing AWS IoT Jobs

AWS IoT Device Management Software Package Catalog extends AWS IoT Jobs through substitution parameters, and integration with AWS IoT fleet indexing, dynamic thing groups, and the AWS IoT thing’s reserved named shadow.

Substitution parameters for AWS IoT jobs

You can use substitution parameters as a placeholder within your AWS IoT job document. When the job service encounters a substitution parameter, it points the job to a named software version’s attribute for the parameter value. You can use this process to create a single job document and pass the metadata into the job through general-purpose attributes. For example, you might pass an Amazon Simple Storage Service(Amazon S3) URL, a software package Amazon Resource Name (ARN), or a signature into the job document through package version attributes.

The substitution parameters should be formatted in the job document as follows:

In the following example, there is a software package named samplePackage and it has a package version named 2.1.5 that has the following attributes:

For s3URL, the job document parameter is written as follows:

{
"samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:s3URL}"
}

For signature, the job document parameter is written as follows:

{
"samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:signature}"
}

The complete job document is written as follows:

{
  ...
  "Steps": {
    "uninstall": ["samplePackage"],
    "download": [ 
      { 
        "samplePackage": "${aws:iot:package:samplePackage1:version:2.1.5:attributes:s3URL}"
      },
    ],
    "signature": [
      "samplePackage" : "${aws:iot:package:samplePackage1:version:2.1.5:attributes:signature}"
    ]
  }
}

After the substitution is made, the following job document is deployed to the devices:

{
  ...
  "Steps": {
    "uninstall": ["samplePackage"],
    "download": [ 
      { 
        "samplePackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile"
      },
    ],
    "signature": [
      "samplePackage" : "aaaaabbbbbcccccdddddeeeeefffffggggghhhhhiiiiijjjj"
    ]
  }
}

Substitution Parameters (Before and After View)

Substitution parameters streamline the creation of a job document using various flags such as $default for the default package version. This eliminates the need to manually enter specific package version metadata for each job deployment as those flags are autofilled with the referenced metadata in the specific package verison. For more information on package version attributes such as $default for the default package version, see Preparing the job document and package version for deployment.

In the AWS Management Console, toggle the Preview substitution button in the Deployment instruction file editor window during a job deployment for a package version to view the job document with and without the substitution parameters.

Using the "before-substitution" parameter in the DescribeJob and GetJobDocument APIs, you can view the API response before and after the substitution parameters are removed. Refer to the following examples with the DescribeJob and GetJobDocument APIs:

For more information about AWS IoT Jobs, creating job documents, and deploying jobs, see Jobs.

Preparing the job document and package version for deployment

When a package version is created, it’s in a draft state to indicate that it’s being prepared for deployment. To prepare the package version for deployment, you must create a job document, save the document in a location that the job can access (such as Amazon S3), and confirm that the package version has the attribute values that you want the job document to use. (Note: You can update attributes for a package version only while it’s in the draft state.)

When you create an AWS IoT Job or Job template for a single-package deployment, you have the following options to customize your job document:

Deployment instruction file (recipe)

Artifact version attribute

Package Version

When you are satisfied with the package version, publish it either through the software package details page in the AWS IoT console or by issuing the UpdatePackageVersion API operation. You can then reference the package version when you create the job either through the AWS IoT console or by issuing the CreateJob API operation.

Naming the packages and versions when deploying

To deploy a software package version to a device, confirm the software package and package version referenced in the job document match the software package and package version stated in the destinationPackageVersions parameter in the CreateJob API operation. If they don't match, you will receive an error message prompting you to make both references match. For more information on Software Package Catalog error messages, see General Troubleshooting Error Messages.

In addition to the software packages and package versions referenced in the job document, you can include additional software packages and package versions in the destinationPackageVersions parameter in the CreateJob API operation not referenced in the job document. Ensure the necessary installation information is included in the job document for devices to properly install the additional software package versions. For more information on the CreateJob API operation, see CreateJob.

Targeting jobs through AWS IoT dynamic thing groups

Software Package Catalog works with fleet indexing, AWS IoT jobs, and AWS IoT dynamic thing groups to filter and target devices within your fleet to select which package version to deploy to your devices. You can run a fleet indexing query based on your device's current package information and target those things for an AWS IoT job. You can also release software updates, but only to eligible target devices. For example, you can specify that you want to deploy a configuration only to those devices that currently run the iot-device-client 1.5.09. For more information, see Create a dynamic thing group.

Reserved named shadow and package versions

If configured, AWS IoT Jobs can update a thing’s reserved named shadow ($package)when the job successfully completes. If you do so, you don’t need to manually associate a package version to a thing’s reserved named shadow.

You might choose to manually associate or update a package version to the thing’s reserved named shadow in the following situations:

You can add or update a package version to a thing’s reserved named shadow ($package) through the console or the UpdateThingShadow API operation. For more information, see Associating a package version to an AWS IoT thing.

Uninstalling a software package and its package version

$null is a reserved placeholder that prompts the AWS IoT Jobs service to remove the existing software package and package version from the device’s reserved named shadow $package. For more information, see Reserved named shadow.

To use this feature, replace the version name at the end of the destinationPackageVersion Amazon Resource Name (ARN) with $null. Afterward, you must instruct your service to remove the software from the device.

The authorized ARN uses the following format:

arn:aws:iot:<regionCode>:111122223333:package/<packageName>/version/$null

For example,

$ aws iot create-job \
    ... \
    --destinationPackageVersions ["arn:aws:iot:us-east-1:111122223333:package/samplePackage/version/$null"]