Filters

By default, subscribed applications poll for all event messages on a topic despite the relevance of each individual message to that particular subscriber. Filters provide efficiency when polling for events by making available only a subset of those events to each consumer based on filter parameters.

Consumer Controlled Filtering

Consumer Controlled Filtering result in the consumer receiving a limited number of event messages which satisfies the filter criteria.

Filters can be viewed and applied by following the below steps:

1. Go to Trimble Cloud Console.
2. From the left menu click Home > Products.
3. Search for the Events API Product.
4. In the Version tab, select “Events-Consumers-Filter-1.0”. Filter Editing API endpoint will be displayed.
5. Once you subscribed to the Product, you can use the API to (GET / PUT) retrieve or update filters by providing the token of the subscribed application.

Understanding consumer-controlled filters

A consumer-controlled filter uses regular expression (Regex) to match patterns in events. During the onboarding process, consumers can review the existing schema to determine the fields they wish to filter by. Filtering events by the regex filter option is open to all subscribed applications.

NOTE

When a filter is applied to an invalid field (i.e., a field not found in the publisher’s payload), all events will be filtered out, and you will receive no events.

Let’s assume that Trimble Identity triggers events associated with user account operations like creating, updating, and deleting users. Consumers poll or receive messages only when a particular user account is deleted from TID. At the time of event creation, the payload must contain the filterable fields.

During the event subscription, consumer adds the filter.fields and filter.criteria value to the API payload.

The Event subscription API payload must contain the filter by fields and criteria.

Example:

  {
       "filter": {
       "criteria": "data.uuid || data.auth",
       "fields": [
               {
                 "key": "data.uuid",
                 "value": "^0f3242dd139"
               },
               {
                 "key": "data.auth",
                 "value": "^0f3242dd1322"
               }
           ]
         }
  }

Where:

• criteria - Used for grouping filterable fields using AND (&&) and OR (||) conditions.
• key - Key is the field in event message that you want to apply filter to.
• value - Value is regular expression that must match in the event message.

In the above example, the event is delivered when the message contains the matching pattern provided in the filter.fields.