Transforming Amazon EventBridge target input - Amazon EventBridge

Transforming Amazon EventBridge target input

You can customize the text from an event before EventBridge passes the event to the target of a rule. Using the input transformer in the console or the API, you define variables that use JSON path to reference values in the original event source. You can define up to 100 variables, assigning each a value from the input. Then you can use those variables in the Input Template as <variable-name>.

For a tutorial on using input transformer, see Tutorial: Use input transformer to customize what EventBridge passes to the event target.

Predefined variables

There are pre-defined variables you can use without defining a JSON path. These variables are reserved, and you can't create variables with these names:

  • aws.events.rule-arn — The Amazon Resource Name (ARN) of the EventBridge rule.

  • aws.events.rule-name — The Name of the EventBridge rule.

  • aws.events.event — A copy of the original event.

  • aws.events.event.ingestion-time — The time at which the event was received by EventBridge. This variable is generated by EventBridge and can't be overwritten.

  • aws.events.event.json — The exact payload of an event as a string.

Input Transform Examples

The following is an example Amazon EC2 event.

{ "version": "0", "id": "7bf73129-1428-4cd3-a780-95db273d1602", "detail-type": "EC2 Instance State-change Notification", "source": "aws.ec2", "account": "123456789012", "time": "2015-11-11T21:29:54Z", "region": "us-east-1", "resources": [ "arn:aws:ec2:us-east-1:123456789012:instance/i-abcd1111" ], "detail": { "instance-id": "i-0123456789", "state": "RUNNING" } }

When defining a rule in the console, select the Input Transformer option under Configure input. This option displays two text boxes: one for the Input Path and one for the Input Template.

Input Path is used to define variables. Use JSON path to reference items in your event and store those values in variables. For instance, you could create an Input Path to reference values in the example event by entering the following in the first text box.

{ "instance" : "$.detail.instance-id", "state" : "$.detail.state" }

This defines two variables, <instance> and <state>. You can reference these variables as you create your Input Template.

The Input Template is a template for the information you want to pass to your target. You can create a template that passes either a string or JSON to the target. Using the previous event and Input Path, the following Input Template examples will transform the event to the example output before routing it to a target.

Description Template Output
Simple string
"instance <instance> is in <state>"
"instance i-0123456789 is in RUNNING"

String with escaped quotes

"instance \"<instance>\" is in <state>"
"instance \"i-0123456789\" is in RUNNING"

Note that this is the behavior in the EventBridge console. The AWS CLI escapes the slash characters and the result is "instance "i-0123456789" is in RUNNING".

Simple JSON

{ "instance" : <instance>, "state": <state> }
{ "instance" : "i-0123456789", "state": "RUNNING" }

JSON with strings and variables

{ "instance" : <instance>, "state": "<state>", "instanceStatus": "instance \"<instance>\" is in <state>" }
{ "instance" : "i-0123456789", "state": "RUNNING", "instanceStatus": "instance \"i-0123456789\" is in RUNNING" }

JSON with a mix of variables and static information

{ "instance" : <instance>, "state": [ 9, <state>, true ], "Transformed" : "Yes" }
{ "instance" : "i-0123456789", "state": [ 9, "RUNNING", true ], "Transformed" : "Yes" }

Including reserved variables in JSON

{ "instance" : <instance>, "state": <state>, "ruleArn" : <aws.events.rule-arn>, "ruleName" : <aws.events.rule-name>, "originalEvent" : <aws.events.event> }
{ "instance" : "i-0123456789", "state": "RUNNING", "ruleArn" : "arn:aws:events:us-east-2:123456789012:rule/example", "ruleName" : "example", "originalEvent" : { ... // commented for brevity } }

Including reserved variables in a string

"<aws.events.rule-name> triggered"
"example triggered"

Transforming input by using the EventBridge API

For information about using the EventBridge API to transform input, see Use Input Transformer to extract data from an event and input that data to the target.

Transforming input by using AWS CloudFormation

For information about using AWS CloudFormation to transform input, see AWS::Events::Rule InputTransformer.

Common Issues with Transforming Input

These are some common issues when transforming input in EventBridge:

  • For Strings, quotes are required.

  • There is no validation when creating JSON path for your template.

  • If you specify a variable to match a JSON path that doesn't exist in the event, that variable isn't created and won't appear in the output.

  • The JSON that is passed to the target is minified and escaped.

  • EventBridge doesn't escape values extracted by Input Path, when populating the Input Template for a target.