# Amazon EventBridge input transformation Input transformation You can customize the text from an [event](eb-events.md) before EventBridge passes the information to the [target](eb-targets.md) of a [rule](eb-rules.md). 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](eb-targets.md#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](eb-input-transformer-tutorial.md). **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 (\$1) forward slashes **Topics** + [ ## Predefined variables ](#eb-transform-input-predefined) + [ ## Input transform examples ](#eb-transform-input-examples) + [ ## Transforming input by using the EventBridge API ](#eb-transform-input-api) + [ ## Transforming input by using AWS CloudFormation ](#eb-transform-input-cfn) + [ ## Common Issues with transforming input ](#eb-transform-input-issues) + [ # Configuring an input transformer when creating a rule in EventBridge ](eb-transform-input-rule.md) + [ # Testing a target input transformer using the EventBridge Sandbox ](eb-sandbox-input-trans.md) ## 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 Input path *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, ``, ``, ``, and ``. You can reference these variables as you create your *Input Template*. **Note** Amazon CloudWatch Logs and SSM targets do not support the use of `Input` and `InputPath` in their input transformers. ### Input template 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  is in "
| 
"instance i-0123456789 is in RUNNING"
| | **String with escaped quotes** | 
"instance \"\" is in "
| 
"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" : ,
  "state": 
}
| 
{
  "instance" : "i-0123456789",
  "state": "RUNNING"
}
| | **JSON with strings and variables** | 
{
 "instance" : ,
 "state": "",
 "instanceStatus": "instance \"\" is in "
}
| 
{
 "instance" : "i-0123456789",
 "state": "RUNNING",
 "instanceStatus": "instance \"i-0123456789\" is in RUNNING"
}
| | **JSON with a mix of variables and static information** | 
{
  "instance" : ,
  "state": [ 9, , true ],
  "Transformed" : "Yes"
}
| 
{
  "instance" : "i-0123456789",
  "state": [
    9,
    "RUNNING",
    true
  ],
  "Transformed" : "Yes"
}
| | **Including reserved variables in JSON** | 
{
  "instance" : ,
  "state": ,
  "ruleArn" : ,
  "ruleName" : ,
  "originalEvent" : 
}
| 
{
  "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** | 
" triggered"
| 
"example triggered"
| | **Amazon CloudWatch log group** | 
{
  "timestamp" : ,
  "message": "instance \"\" is in "
}
| 
{
  "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](https://docs.aws.amazon.com/eventbridge/latest/APIReference/API_PutTargets.html#API_PutTargets_Example_2). ## Transforming input by using AWS CloudFormation For information about using AWS CloudFormation to transform input, see [AWS::Events::Rule InputTransformer](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-events-rule-inputtransformer.html). ## 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 `` pointed at `$.detail`, "Detail is " 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": }`. + 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" : , "ruleName" : , "originalEvent" : } ``` 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](https://docs.aws.amazon.com/inspector/latest/user/eventbridge-integration.html#event-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 finding " "Description: <description>" "ARN: \"<arn>\"" "Type: <type>" "AWS Account: <account>" "Region: <region>" "EC2 Instance: <instance>" "Platform: <platform>" "AMI: <ami>" ``` # Configuring an input transformer when creating a rule in EventBridge Configuring an input transformer As part of creating a rule, you can specify an input transformer for EventBridge to use to process matching events prior to sending those event to the specified target. You can configure input transformers for targets that are AWS services or API destinations. **To create a target input transformer as part of a rule** 1. Follow the steps for creating a rule as detailed in [Creating rules in Amazon EventBridge](eb-create-rule-visual.md). 1. In **Step 3 - Select target(s)**, expand **Additional settings**. 1. For **Configure target input**, choose **Input transformer** in the dropdown. Click **Configure input transformer**. EventBridge displays the **Configure input transformer** dialog box. 1. In the **Sample event** section, choose a **Sample event type** against which you want to test your event pattern. You can choose an AWS event, a partner event, or enter your own custom event. ------ #### [ AWS events ] Select from events emitted from supported AWS services. 1. Select **AWS events**. 1. Under **Sample events**, choose the desired AWS event. Events are organized by AWS service. When you select an event, EventBridge populates the sample event. For example, if you choose **S3 Object Created**, EventBridge displays a sample S3 Object Created event. 1. (Optional) You can also select **Copy** to copy the sample event to your device's clipboard. ------ #### [ Partner events ] Select from events emitted from third-party services that support EventBridge, such as Salesforce. 1. Select **EventBridge partner events**. 1. Under **Sample events**, choose the desired partner event. Events are organized by partner. When you select an event, EventBridge populates the sample event. 1. (Optional) You can also select **Copy** to copy the sample event to your device's clipboard. ------ #### [ Enter your own ] Enter your own event in JSON text. 1. Select **Enter your own**. 1. EventBridge populates the sample event with a template of required event attributes. 1. Edit and add to the sample event as desired. The sample event must be valid JSON. 1. (Optional) You can also choose any of the following options: + **Copy** – Copy the sample event to your device's clipboard. + **Prettify** – Makes the JSON text easier to read by adding line breaks, tabs, and spaces. ------ 1. (Optional) Expand the **Example input paths, Templates and Outputs** section to see examples of: + How JSON paths are used to define variables that represent event data + How those variables can be used in an input transformer template + The resulting output that EventBridge sends to the target For more detailed examples of input transformations, see [Input transform examples](eb-transform-target-input.md#eb-transform-input-examples). 1. In the **Target input transformer** section, define any variables you want to use in the input template. Variables use JSON path to reference values in the original event source. You can then reference those variables in the input template in order to include data from the original source event in the transformed event that EventBridge passes to the target. You can define up to 100 variables. The input transformer must be valid JSON. For example, suppose you had chosen AWS event **S3 Object Created** as your sample event for this input transformer. You could then define the following variables for use in your template: ``` { "requester": "$.detail.requester", "key": "$.detail.object.key", "bucket": "$.detail.bucket.name" } ``` (Optional) You can also choose **Copy** to copy the input transformer to your device's clipboard. 1. In the **Template** section, compose the template you want to use to determine what EventBridge passes to the target. You can use JSON, strings, static information, variables you've defined as well as reserved variables. For more detailed examples of input transformations, see [Input transform examples](eb-transform-target-input.md#eb-transform-input-examples). For example, suppose you had defined the variables in the previous example. You could then compose the following template, which references those variables, as well as reserved variables, and static information. ``` { "message": "<requester> has created the object \"<key>\" in the bucket \"<bucket>\"", "RuleName": <aws.events.rule-name>, "ruleArn" : <aws.events.rule-arn>, "Transformed": "Yes" } ``` (Optional) You can also choose **Copy** to copy the template to your device's clipboard. 1. To test your template, select **Generate output**. EventBridge processes the sample event based on the input template, and displays the transformed output generated under **Output**. This is the information that EventBridge will pass to the target in place of the original source event. The generated output for the example input template described above would be the following: ``` { "message": "123456789012 has created the object "example-key" in the bucket "amzn-s3-demo-bucket"", "RuleName": rule-name, "ruleArn" : arn:aws:events:us-east-1:123456789012:rule/rule-name, "Transformed": "Yes" } ``` (Optional) You can also choose **Copy** to copy the generated output to your device's clipboard. 1. Select **Confirm** 1. Follow the rest of the steps for creating a rule as detailed in [Creating rules in Amazon EventBridge](eb-create-rule-visual.md). # Testing a target input transformer using the EventBridge Sandbox Testing an input transformer You can use input transformers to customize the text from an [event](eb-events.md) before EventBridge passes the information to the [target](eb-targets.md) of a [rule](eb-rules.md). Configuring an input transformer is typically part of the larger process of specifying a target while [creating a new rule](eb-create-rule-visual.md) or editing an existing one. Using the Sandbox in EventBridge, however, you can quickly configure an input transformer and use a sample event to confirm you are getting the desired output, without having to create or edit a rule. For more information about input transformations, see [Amazon EventBridge input transformation](eb-transform-target-input.md). **To test a target input transformer** 1. Open the Amazon EventBridge console at [https://console.aws.amazon.com/events/](https://console.aws.amazon.com/events/). 1. Under **Developer resources**, choose **Sandbox**, and on the **Sandbox** page choose the **Target input transformer** tab. 1. In the **Sample event** section, choose a **Sample event type** against which you want to test your event pattern. You can choose an AWS event, a partner event, or enter your own custom event. ------ #### [ AWS events ] Select from events emitted from supported AWS services. 1. Select **AWS events**. 1. Under **Sample events**, choose the desired AWS event. Events are organized by AWS service. When you select an event, EventBridge populates the sample event. For example, if you choose **S3 Object Created**, EventBridge displays a sample S3 Object Created event. 1. (Optional) You can also select **Copy** to copy the sample event to your device's clipboard. ------ #### [ Partner events ] Select from events emitted from third-party services that support EventBridge, such as Salesforce. 1. Select **EventBridge partner events**. 1. Under **Sample events**, choose the desired partner event. Events are organized by partner. When you select an event, EventBridge populates the sample event. 1. (Optional) You can also select **Copy** to copy the sample event to your device's clipboard. ------ #### [ Enter your own ] Enter your own event in JSON text. 1. Select **Enter your own**. 1. EventBridge populates the sample event with a template of required event attributes. 1. Edit and add to the sample event as desired. The sample event must be valid JSON. 1. (Optional) You can also choose any of the following options: + **Copy** – Copy the sample event to your device's clipboard. + **Prettify** – Makes the JSON text easier to read by adding line breaks, tabs, and spaces. ------ 1. (Optional) Expand the **Example input paths, Templates and Outputs** section to see examples of: + How JSON paths are used to define variables that represent event data + How those variables can be used in an input transformer template + The resulting output that EventBridge sends to the target For more detailed examples of input transformations, see [Input transform examples](eb-transform-target-input.md#eb-transform-input-examples). 1. In the **Target input transformer** section, define any variables you want to use in the input template. Variables use JSON path to reference values in the original event source. You can then reference those variables in the input template in order to include data from the original source event in the transformed event that EventBridge passes to the target. You can define up to 100 variables. The input transformer must be valid JSON. For example, suppose you had chosen AWS event **S3 Object Created** as your sample event for this input transformer. You could then define the following variables for use in your template: ``` { "requester": "$.detail.requester", "key": "$.detail.object.key", "bucket": "$.detail.bucket.name" } ``` (Optional) You can also choose **Copy** to copy the input transformer to your device's clipboard. 1. In the **Template** section, compose the template you want to use to determine what EventBridge passes to the target. You can use JSON, strings, static information, variables you've defined as well as reserved variables. For more detailed examples of input transformations, see [Input transform examples](eb-transform-target-input.md#eb-transform-input-examples). For example, suppose you had defined the variables in the previous example. You could then compose the following template, which references those variables, as well as reserved variables, and static information. ``` { "message": "<requester> has created the object \"<key>\" in the bucket \"<bucket>\"", "RuleName": <aws.events.rule-name>, "ruleArn" : <aws.events.rule-arn>, "Transformed": "Yes" } ``` (Optional) You can also choose **Copy** to copy the template to your device's clipboard. 1. To test your template, select **Generate output**. EventBridge processes the sample event based on the input template, and displays the transformed output generated under **Output**. This is the information that EventBridge will pass to the target in place of the original source event. The generated output for the example input template described above would be the following: ``` { "message": "123456789012 has created the object "example-key" in the bucket "amzn-s3-demo-bucket"", "RuleName": rule-name, "ruleArn" : arn:aws:events:us-east-1:123456789012:rule/rule-name, "Transformed": "Yes" } ``` (Optional) You can also choose **Copy** to copy the generated output to your device's clipboard.