Event Filtering

Event subscriptions deliver all matching events to the specified deliveryTarget. In some cases, this may result in too many events that your consumer will need to discard. Event filtering can be used to limit subscription deliveries to more specific events based on the event body.

There are two ways of creating subscriptions with event filtering:

• actions: Specify one or more actions to deliver events with an action matching one in the list.

• filterExpression: Specify a filter expression. Only events with a body matching the JSON Expressions are delivered.

For example, the following ENS request creates a subscription to TES task run updates (as specified in the actions array) and delivers the events to an AWS SNS Topic. The --actions flag is used to apply the actions filter.

$ ica subscriptions create --name aws-sns-example --type tes.runs --actions updated --aws-sns-topic arn:aws:sns:us-east-1:<aws-account-id>:<sns-topic>
actions.0                           updated
deliveryTarget.awsSnsTopic.topicArn arn:aws:sns:us-east-1:<aws-account-id>:<sns-topic>
id                                  sub.EXAMPLE
matchIdentities.0                   cid:EXAMPLE
name                                aws-sns-example
type                                tes.runs
...

This example subscription delivers an event to the AWS SQS Queue whenever a TES task run is updated by TES. The event contains the same data as the response of the TES GET /v1/tasks/runs/{id} API:

TES may update the task run for many reasons that you may not be interested in, producing an event for each update. For example, you may be interested in receiving only the events emitted by TES when the task run is complete. Upon completing the task run, TES updates the status field to Completed.

The following JSON filter expression can be used to match events that include "status": "Completed":

{
   "equal": [{"path": "$.status"}, "Completed"]
}

The following example applies the filter expression to the subscription upon creation. The --filter-expression flag is used to apply the filter expression filter.

$ ica subscriptions create --name aws-sns-example --type tes.runs --actions updated --aws-sns-topic arn:aws:sns:us-east-1:<aws-account-id>:<sns-topic> --filter-expression '{"equal":[{"path":"$.status"},"Completed"]}'
actions.0                           updated
deliveryTarget.awsSnsTopic.topicArn arn:aws:sns:us-east-1:<aws-account-id>:<sns-topic>
filterExpression                    {"equal":[{"path":"$.status"},"Completed"]}
id                                  sub.EXAMPLE
name                                aws-sns-example
type                                tes.runs
...

JSON Expressions are flexible and provide complex filtering on the event data. Refer to JSON Expressions to explore the various types of expressions that may be provided with your subscription.