Substitution templates - Amazon IoT Core
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Substitution templates

You can use a substitution template to augment the JSON data returned when a rule is triggered and Amazon IoT performs an action. The syntax for a substitution template is ${expression}, where expression can be any expression supported by Amazon IoT in SELECT clauses, WHERE clauses, and Amazon IoT rule actions. This expression can be plugged into an action field on a rule, allowing you to dynamically configure an action. In effect, this feature substitutes a piece of information in an action. This includes functions, operators, and information present in the original message payload.


Because an expression in a substitution template is evaluated separately from the "SELECT ..." statement, you can't reference an alias created using the AS clause. You can only reference information present in the original payload, functions, and operators.

For more information about supported expressions, see Amazon IoT SQL reference.

The following rule actions support substitution templates. Each action supports different fields that can be substituted.

Substitution templates appear in the action parameters within a rule:

{ "sql": "SELECT *, timestamp() AS timestamp FROM 'my/iot/topic'", "ruleDisabled": false, "actions": [{ "republish": { "topic": "${topic()}/republish", "roleArn": "arn:aws:iam::123456789012:role/my-iot-role" } }] }

If this rule is triggered by the following JSON published to my/iot/topic:

{ "deviceid": "iot123", "temp": 54.98, "humidity": 32.43, "coords": { "latitude": 47.615694, "longitude": -122.3359976 } }

Then this rule publishes the following JSON to my/iot/topic/republish, which Amazon IoT substitutes from ${topic()}/republish:

{ "deviceid": "iot123", "temp": 54.98, "humidity": 32.43, "coords": { "latitude": 47.615694, "longitude": -122.3359976 }, "timestamp": 1579637878451 }