Amazon EventBridge input transformation - Amazon EventBridge

Amazon EventBridge input transformation

You can customize the text from an event before EventBridge passes the information 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. The transformed event is sent to a target instead of the original event. However, dynamic path parameters must reference the original event, not the transformed event. 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 transformers to transform events in EventBridge.

Note

EventBridge does not support all JSON Path syntax and evaluate it at runtime. Supported syntax includes:

  • dot notation (for example,$.detail)

  • dashes

  • underscores

  • alphanumeric characters

  • array indices

  • wildcards (*)

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.ingestion-time — The time at which the event was received by EventBridge. This is an ISO 8601 timestamp. This variable is generated by EventBridge and can't be overwritten.

  • aws.events.event — The original event payload as JSON (without the detail field). Can only be used as a value for a JSON field, as it's contents are not escaped.

  • aws.events.event.json — The full original event payload as JSON. (with the detail field). Can only be used as a value for a JSON field, as it's contents are not escaped.

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. You can also use brackets and indices to get items from arrays.

Note

EventBridge replaces input transformers at runtime to ensure a valid JSON output. Because of this, put quotes around variables that refer to JSON path parameters, but do not put quotes around variables that refer to JSON objects or arrays.

{ "timestamp" : "$.time", "instance" : "$.detail.instance-id", "state" : "$.detail.state", "resource" : "$.resources[0]" }

This defines four variables, <timestamp>, <instance>, <state>, and <resource>. 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.json> }
{ "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"

Amazon CloudWatch log group

{ "timestamp" : <timestamp>, "message": "instance \"<instance>\" is in <state>" }
{ "timestamp" : 2015-11-11T21:29:54Z, "message": "instance "i-0123456789" is in RUNNING }

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.

  • JSON properties like aws.events.event.json can only be used as the value of a JSON field, not inline in other strings.

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

  • If a JSON path references a JSON object or array, but the variable is referenced in a string, EventBridge removes any internal quotes to ensure a valid string. For example, for a variable <detail> pointed at $.detail, "Detail is <detail>" would result in EventBridge removing quotes from the object.

    Therefore, if you want to output a JSON object based on a single JSON path variable, you must place it as a key. In this example, {"detail": <detail>}.

  • Quotes are not required for variables that represent strings. They are permitted, but EventBridge automatically adds quotes to string variable values during transformation, to ensure the transformation output is valid JSON. EventBridge does not add quotes to variables that represent JSON objects or arrays. Do not add quotes for variables that represent JSON objects or arrays.

    For example, the following input template includes variables that represent both strings and JSON objects:

    { "ruleArn" : <aws.events.rule-arn>, "ruleName" : <aws.events.rule-name>, "originalEvent" : <aws.events.event.json> }

    Resulting in valid JSON with proper quotation:

    { "ruleArn" : "arn:aws:events:us-east-2:123456789012:rule/example", "ruleName" : "example", "originalEvent" : { ... // commented for brevity } }
  • For (non-JSON) text output as multi-line strings, wrap each separate line in your input template in double quotes.

    For example, if you were matching Amazon Inspector Finding events against the following event pattern:

    { "detail": { "severity": ["HIGH"], "status": ["ACTIVE"] }, "detail-type": ["Inspector2 Finding"], "source": ["inspector2"] }

    And using the following input path:

    { "account": "$.detail.awsAccountId", "ami": "$.detail.resources[0].details.awsEc2Instance.imageId", "arn": "$.detail.findingArn", "description": "$.detail.description", "instance": "$.detail.resources[0].id", "platform": "$.detail.resources[0].details.awsEc2Instance.platform", "region": "$.detail.resources[0].region", "severity": "$.detail.severity", "time": "$.time", "title": "$.detail.title", "type": "$.detail.type" }

    You could use the input template below to generate multi-line string output:

    "<severity> severity finding <title>" "Description: <description>" "ARN: \"<arn>\"" "Type: <type>" "AWS Account: <account>" "Region: <region>" "EC2 Instance: <instance>" "Platform: <platform>" "AMI: <ami>"