Filtering Events with the Event Hub Service

Last updated a month ago

Filtering events with the Event Hub Service.

Table of Contents

Introduction
Specifying a filter
Filter evaluation and error handling
Filter examples
Filter test
Filter limits
Event Delivery

Introduction

Not all events provided by the Event Hub Service are relevant for a specific application. For example, an application might only be interested in events for a certain subset of content types or events of a specific type. The Event Hub Service provides a filtering mechanism that allows event subscriptions to specify which events the registered endpoint is interested in.

Specifying a filter

Event filters are a configuration option when creating or updating an event subscription. The filters are a JSON object that specifies the criteria that an event must meet in order to be delivered to the endpoint. The filters are specified in the filterSets attribute of the subscription configuration. The filter object is a map with the following structure (see Configuration API):

{
    "<STREAM_1>": {
        "discardOnError": true,
        "expressions": [
            "<EXPRESSION>"
        ]
    },
    "<STREAM_2>": {
        "discardOnError": false,
        "expressions": [
            "<EXPRESSION>",
            "<EXPRESSION>"
        ]
    }
}

Valid streams are CONTENT, NOTIFICATION and WORKFLOW. The stream must be subscribed to in the subscriptionTypes attribute of the configuration otherwise an error will be returned.

The flag discardOnError is described in section Filter evaluation and error handling.

The expressions attribute is a set of filter expressions defined as a JMESPath Filter Expression. Multiple expressions are combined with a logical OR: if an event matches any expression, it will be delivered to the endpoint.

Example configuration:

{
    "description": "Example filter configuration",
    "namespace": "PUBLIC",
    "subscriptionTypes": [
        "CONTENT"
    ],
    "filterSets": {
        "CONTENT": {
            "discardOnError": true,
            "expressions": [
               "[?eventType=='CONTENT_CREATED']"
            ]
        }
    },
    "enabled": true,
    "endpoint": {
    "endpointType": "WEBHOOK",
    "method": "POST",
    "url": "https://example.com/eventHubHook"
    }
}

Filter evaluation and error handling

Filter expressions are evaluated as follows:

For each single event all expressions of the filter set are evaluated.
If there is no error and any of the expressions matches, the event is delivered to the endpoint.
If there is no error and none of the expressions matches, the event is discarded.
If there is an error when evaluating any expression, the behavior depends on the value of the discardOnError flag:
- If discardOnError is true:
  - If any expression was executed successfully and matched, the event is delivered to the endpoint, otherwise the event is discarded.
  - The filterErrors flag in the processingDetails object will be set to true (see Event Delivery).
- If discardOnError is false:
  - The event is delivered to the endpoint.
  - The filterErrors flag in the processingDetails object will be set to true and the filterErrorsIndices array will contain the index of the event (see Event Delivery).

Filter examples

The following examples are for the CONTENT event stream:

[?contentType=='CMChannel' || contentType=='CMArticle']

Return only events for items with content type CMChannel or CMArticle.
[?eventClass=='CONTENT']

Return only events of the CONTENT event class, that is events like CONTENT_CREATED, CONTENT_RENAMED, CONTENT_DELETED, etc.
[?eventType=='CONTENT_CREATED']

Return only events of the CONTENT_CREATED event type.
[?performerUuid=='fff12a29-ddfe-4399-83b4-dde6911bf560']

Return only events where the performer has the given UUID.

Check the Delivery API for defined events and their attributes.

Filter test

Filter expressions may be tested before being put into production on the Filter Test Page.

Filter limits

The following limits apply to filters:

The maximum number of filter expressions per filter set is 8.
The maximum length of a filter expression is 256 characters.

Event Delivery

When a filter was applied, the event delivered to the configured endpoint contains additional attributes:

processingStates

A set containing the constant FILTERED to indicate that filtering was applied to the event.
processingDetails

Additional flags describing the result of the filter operations:
- filterErrors: true if there was an error when applying a filter expression.
- filterErrorIndices: An array of event indices. Events referenced here had an evaluation error when applying a filter expression. Only present if discardOnError is set to false.

Example of an event that caused an error when applying a filter expression (discardOnError is set to false):

{
    "tenantId": "tds76wkj",
    "sourceId": "preview",
    "eventType": "NOTIFICATION",
    "event": {
        "eventType": "NOTIFICATION_CREATED",
        "eventTimestamp": {
            "time": 1664214826403
        },
        "notificationId": "6331e72a9d1a060510cecbd7",
        "recipientId": "coremedia:///cap/user/24",
        "recipientUuid": "2c9d2e6c-e436-11ed-b5ea-0242ac120002",
        "recipientEmail": "mike@chefcorp.com",
        "recipientName": "Mike Howard",
        "type": "editorialComments",
        "key": "new_comment_for_content",
        "parameters": [
            "Chef Corp. USA Home Page",
            "Teresa",
            "Please update title and teaser",
            12482,
            "title",
            "1"
        ]
    },
    "processingStates": [
        "FILTERED"
    ],
    "processingDetails": {
        "filterErrors": true,
        "filterErrorIndices": [
            0
        ]
    }
}

For events that are delivered as singletons (NOTIFICATION and WORKFLOW), the error index is always 0. For events that are delivered as batch (CONTENT), the error index is the index of the event in the batch array.

Is this page useful?