Working with EventBridge Rules

Rules match incoming events and routes them to targets for processing. A single rule can route to multiple targets, all of which are processed in parallel. Rules aren’t processed in a particular order. A rule can customize the JSON sent to the target, by passing only certain parts or by overwriting it with a constant. EventBridge supports 20+ AWS service targets!

In this module, you will walk through the steps to create an Orders EventBus rule to match an event with a com.aws.orders source and to send the event to an Amazon Kinesis Firehose delivery stream, OrdersDelivery Stream, storing the events in an Amazon S3 Bucket. Afterwards, you will be challenged to create two additional rules without instruction. See the diagram below:

Simple Event Bus

The EventBus targets (Kinesis Firehose, Step Functions, and SNS Topic) have been provisioned for you. The goal is for you to write EventBus rules to match events and verify delivery to the appropriate target.

Rule Matching Basics

Events in Amazon EventBridge are represented as JSON objects and have the following envelope signature:

{
  "version": "0",
  "id": "6a7e8feb-b491-4cf7-a9f1-bf3703467718",
  "detail-type": "EC2 Instance State-change Notification",
  "source": "aws.ec2",
  "account": "111122223333",
  "time": "2017-12-22T18:43:48Z",
  "region": "us-west-1",
  "resources": [
    "arn:aws:ec2:us-west-1:123456789012:instance/ i-1234567890abcdef0"
  ],
  "detail": {
    "instance-id": "i-1234567890abcdef0",
    "state": "terminated"
  }
}

Rules use event patterns to select events and route them to targets. A pattern either matches an event or it doesn’t. Event patterns are represented as JSON objects with a structure that is similar to that of events. For example, the following event pattern allows you to subscribe to only events from Amazon EC2.

{
  "source": [ "aws.ec2" ]
}

The pattern simply quotes the fields you want to match and provides the values you are looking for.

The sample event above, like most events, has a nested structure. Suppose you want to process all instance-termination events. Create an event pattern like the following.

{
  "source": [ "aws.ec2" ],
  "detail-type": [ "EC2 Instance State-change Notification" ],
  "detail": {
    "state": [ "terminated" ]
  }
}

It is important to remember the following about event pattern matching:

  • For a pattern to match an event, the event must contain all the field names listed in the pattern. The field names must appear in the event with the same nesting structure.

  • Other fields of the event not mentioned in the pattern are ignored; effectively, there is a “*” : “*” wildcard for fields not mentioned.

  • The matching is exact (character-by-character), without case-folding or any other string normalization.

  • The values being matched follow JSON rules: Strings enclosed in quotes, numbers, and the unquoted keywords true, false, and null.

  • Number matching is at the string representation level. For example, 300, 300.0, and 3.0e2 are not considered equal.

For more information on pattern matching, referr to the Events and Event Patterns in EventBridge documentation.


Kinesis Firehose Challenge

Process all events for source com.aws.orders via an Amazon Kinesis Firehose delivery stream, OrdersDeliveryStream. In this use case we are demonstrating how you might create an audit trail of all events from a specified source by persisting them to an Amazon S3 bucket (eg. orders-REGION-ACCOUNT_ID).

Step 1: Implement an EventBridge rule to target Kinesis Firehose

  1. Open the AWS Management Console for EventBridge in a new tab or window, so you can keep this step-by-step guide open.

  2. On the EventBridge homepage, open the left hand navigation.

    EventBridge Console

  3. From the left-hand menu, select Rules.

  4. From the Event bus dropdown, select the Orders event bus.

  5. Click Create rule New rule

  6. On the Create rule page

    • Enter AuditOrdersEventsRule as the Name of the rule
    • Enter Send com.aws.orders source events to Kinesis Firehose for Description
  7. Under Define pattern

    • Choose Event pattern
    • Under Event matching pattern, select Custom pattern, copy/paste the following into the Event pattern
    {
      "source": [
        "com.aws.orders"
      ]
    }
    

    Create Bus

  8. Select Save

    Take a moment and study the event pattern that you pasted. The event pattern allows you to subscribe to only events that has a source from com.aws.orders.

  9. Ensure that you have selected Orders from the Select event bus panel

    Select event bus panel

  10. Select your rule target:

    • From the Target dropdown, select Firehose delivery stream
    • Select OrdersDeliveryStream as the Stream
    • Keep the default selection Create a new role for this specific resource

    Firehose delivery stream

  11. Leave the Tags blank.

    Create Bus

  12. Click Create.

Step 2: Send test Orders event

Below is sample data to test your rule with a link to open the sample data in the Event Generator. If you don’t remember how to use Event Generator to send an event, please refer to the previous section.

SampleDetail
lab-supplies
(us-east)

Test event >>
          {
  "category" : "lab-supplies",
  "location" : "us-east",
  "value" : 415
}

Step 3: Verify Kinesis Firehose

If the event sent to the Orders event bus matches the pattern in your rule, then the event will be sent to Kinesis Firehose, which will write the data to an S3 bucket (eg. orders-REGION-ACCOUNT_ID).

  1. Open the AWS Management Console for S3 in a new tab or window, so you can keep this step-by-step guide open.

  2. Enter orders in the Search of buckets box.

  3. Select the orders-REGION-ACCOUNT_ID bucket (where REGION and ACCOUNT_ID match your AWS region and account ID).

  4. Drill down into the prefix, firehose/YYYY/MM/DD, and select the object that begins with OrdersDeliveryStream.

    Kinesis Firehose delivery streams buffer data for a minumum of 60 seconds. If you follow the steps below and do not see your event, refresh your S3 bucket listing. If you do not see the event after 60 seconds, use CloudWatch Logs to verify the event data and compare to your event pattern. If you still have troubles verifying the event, please notify the workshop staff.

  5. Select the Select from tab, JSON File format, JSON document JSON type, and click Show file preview to verify your test event was delivered.

    Firehose delivery verify

CONGRATULATIONS! You have successfully created your first custom event. We will now present additional challenges for you to complete. A description of the goal, sample data, and verification steps have been provided, but it is up to you to write the correct event pattern. Remember, use CloudWatch Logs to troubleshoot your rule implementation, if you are not able to verify your rule.


Step Functions Challenge

Process only orders from locations in the EU (eu-west or eu-east) using a AWS Step Functions target (OrderProcessing). In this use case, we are demonstrating how a Step Function execution can be triggered to process orders as they are published by the Orders bus.

Step 1: Implement an EventBridge rule to target Step Functions

Use the EventBridge Console to:

  1. Add a rule to the Orders event bus with the name EUOrdersRule
  2. With an event pattern to match events with a detail location in eu-west or eu-east and
  3. Target the OrderProcessing Step Functions state machine

Here is a sample event to reference when writing the event pattern:

{
    "id": "6e6b1f6d-48f8-5dff-c2d2-a6f22c2e0086",
    "source": "com.aws.orders",
    "detail-type": "Order Notification",
    "version": "0",
    "time": "2020-02-23T15:35:41Z",
    "account": "529761441557",
    "region": "us-east-1",
    "resources": [],
    "detail": {
        "category": "office-supplies",
        "value": 300,
        "location": "eu-west"
    }
}

Step 2: Send test EU Orders events

Below is sample data to test your rule with a link to open the sample data in the Event Generator. If you don’t remember how to use Event Generator to send an event, please refer to the previous section.

SampleDetail
office-supplies
(eu-west)

Test event >>
          {
  "category" : "office-supplies",
  "location" : "eu-west",
  "value" : 300
}
tech-supplies
(eu-east)

Test event >>
          {
  "category" : "tech-supplies",
  "location" : "eu-east",
  "value" : 3000
}

Step 3: Verify Step Functions workflow execution

If the event sent to the Orders event bus matches the pattern in your rule, then the event will be sent to the OrderProcessing Step Functions state machine for execution.

  1. Open the AWS Management Console for Step Functions in a new tab or window, so you can keep this step-by-step guide open.

  2. On the Step Functions homepage, open the left hand navigation and select State machines.

  3. Enter OrderProcessing in the Search for state machines box and verify the state machine execution has succeeded.

The Step Functions state machine will publish a message to the Inventory SNS topic, which will be used later in the workshop. If you would like to see more detail on the workflow execution, select OrderProcessing from the list of state machines, and then select the workflow execution from the list.

CONGRATULATIONS! You have successfully completed the Step Functions Challenge.

Extra Credit Implement an event pattern using Prefix Matching that matches events with a location the begins with eu-. Do not modify the Step Function target and verify backwards compatability by reusing the sample data above. Modify the test data to use a location, eu-south, to verify that additional EU locations trigger execution of the Step Functions state machine.

Extra Credit Implement an event pattern using Prefix Matching and Numeric Matching that matches events with a location the begins with eu- AND an Order value greater than 1000. Do not modify the Step Function target and verify backwards compatability by reusing the sample data above.


SNS Challenge

Process only orders from US locations (us-west or us-east) that are lab-supplies using a Amazon SNS target (Orders). Similar to the previous use case, but using SNS.

Step 1: Implement an EventBridge rule to target SNS

Use the EventBridge Console to:

  1. Add a rule to the Orders event bus with the name USLabSupplyOrdersRule
  2. With an event pattern to match events with a detail location in us-west or us-east, and a detail category with lab-supplies.
  3. Target the Orders SNS topic

Here is a sample event to reference:

{
    "version": "0",
    "id": "6e6b1f6d-48f8-5dff-c2d2-a6f22c2e0086",
    "detail-type": "Order Notification",
    "source": "com.aws.orders",
    "account": "529761441557",
    "time": "2020-02-23T15:35:41Z",
    "region": "us-east-1",
    "resources": [],
    "detail": {
        "category": "lab-supplies",
        "value": 300,
        "location": "us-east"
    }
}

Step 2: Send test US Orders events

One of the following events should match the event rule pattern and one should not. Use CloudWatch Logs to verify events that were successfully sent to EventBridge but were not delivered to the target.

SampleDetail
lab-supplies
(us-east)

Test event >>
          {
  "category" : "lab-supplies",
  "location" : "us-east",
  "value" : 415
}
office-supplies
(us-west)

Test event >>
          {
  "category" : "office-supplies",
  "location" : "us-west",
  "value" : 1050,
  "signature": [ "John Doe" ]
}

Step 3: Verify SNS topic

If the event sent to the Orders event bus matches the pattern in your rule, then the event will be sent to the Orders SQS Queue (via Orders SNS Topic).

  1. Open the AWS Management Console for SQS in a new tab or window, so you can keep this step-by-step guide open.

  2. On the SQS homepage, select the Orders queue.

  3. Select Send and receive messages.

SQS receive messages

  1. In the Receive messages section, select Poll for messages and verify the message was delivered.

SQS poll messages

  1. To clean up, select the event and click Delete.

SQS delete message

  1. Click Delete on the Delete Messages confirmation dialog.

SQS delete message confirmation

CONGRATULATIONS! You have successfully completed the SNS Challenge.

Extra Credit Implement an event pattern using Exists Matching that matches events which do NOT require a signature (ie. signature does not exists). Do not modify the SNS target and verify backwards compatability by reusing the sample data above.

Extra Credit Implement an event pattern using Prefix Matching and Anything-but Matching that matches events with a location the begins with us- but NOT a location that is us-east. Do not modify the SNS target and verify backwards compatability by reusing the sample data above.

Next Steps

OK, now that you have explored Event Bridge Rule patterns, let’s look at how we can generate events on a scheduled basis.