Skip to content
Events Service

Consumer-controlled filtering

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. A single event can contain up to three fields as filterable fields. If the event already has three filterable fields, consumers cannot request additional fields for filtering. Consumer-controlled Filtering is available for all subscribed applications. Integrators can manage their filters—adding or updating them—through the Event Filter Editing API , using the endpoint provided under the version “Events-Consumers-Filter-1.0”.

Polling on a filtered topic

Consumer Controlled Filtering and Publisher Controlled Authorization Filtering both result in the consumer receiving a limited number of event messages from a topic. We internally create a dedicated topic for the consumer and place into that topic only the even messages which satisfy the filter criteria.

Understanding Consumer Controlled Filters

Let’s assume that Trimble Identity triggers events associated with user account operations like creating, updating, and deleting users. The consumer looks over the schema and sees that the field “type” is defined and has 3 possible values: create, updated and delete. By default, the consumer will receive all messages from this topic, but this consumer is only interested in messages of type delete.

Example:

“simpleFilter”:[“data.uuid”, “type”]

During the event subscription, the consumer adds the filterFields and filterCriteria value to the API payload.

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

"filterFields": {
   "data.uuid":"\\D",
   "type":"^delete$"
},
"filterCriteria":"data.uuid || type"

Where

  • filterFields - Filterable fields as specified in the schema. This field accepts values in the Regex pattern.
  • filterCriteria - Used for grouping filterable fields using AND (&&) and OR (||) conditions.

In the above example, the event is polled when the message contains the matching pattern provided in the filterFields.

Filtering also supports data block containing stringified JSON.

Publisher example:

{
    "id": "fed6689f-e68f-490f-a6e5-bc6d6e81bacf",
    "specversion": "1.0",
    "source": "/events/<apiid>",
    "type": 123,
    "time": "time",
    "subject": "/events/UserDelete",
    "dataschema":"localhost:8080/produce2",
    "data": "{\"uuid\":\"121\"}"
}

Consumer example:

[
   {
      "data":"{\"uuid\":\"121\"}",
      "subject":"\/events\/UserDelete",
      "specversion":"1.0",
      "id":"fed6689f-e68f-490f-a6e5-bc6d6e81bacf",
      "source":"\/events\/<apiid>",
      "time":"time",
      "type":123,
      "dataschema":"localhost:8080\/produce2"
   }
]