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.

Understanding publisher-controlled authorization

Producers can also authorize events by application or targeted subscriber. In addition to increased consumer efficiency (not bogging them down with irrelevant messages), this type of filtering can also alleviate the authorization concerns of publishers who may not want any application to see all of their event messages.

Events Service – Publisher Controlled Filtering

The Events Service now supports publisher-controlled filtering using Trimble Access Management.
This ensures that event delivery is authorized based on TAM-managed policies.

Note: When using Publisher Controlled Authorization, consumers must subscribe with the correct environment-specific application ID (preprd apps for preprd events, prod apps for prod events).

Publisher Policy Definition

Publishers are responsible for creating TAM policies that define which applications are authorized to consume specific events.

• Policy Input: List of events.
• Policy Output: List of application IDs eligible to consume those events.

Both the policy and the test file with 100% coverage must be provided by the publisher to enable publisher-controlled authorization.

For more information on how to define policies, refer to the official TAM documentation:
How to Write Policies – Trimble Access Management

Policy Package Format

The Events Service validates policies through TAM (Trimble Access Management). Publishers must use the exact package name provided by the Events Service in the format:

com.trimble.events.{environment}.{tam_policy_name}

Where {environment} is prd or preprd, and {tam_policy_name} is the TAM policy name for the event.

Example: com.trimble.events.prd.tconnecttestproduction1

Policy Input Structure

The Events Service sends the following input structure to TAM for policy evaluation. The input is wrapped in an input object containing an events array:

{
    "input": {
        "events": [
            {
                "id": "21492d57-dc30-4dbd-9fe3-b8f281ac8c11",
                "source": "82db0121-54ec-4396-8821-317e6edba000",
                "specversion": "1.0",
                "type": "test",
                "time": "2023-03-29T11:15:00.00",
                "subject": "test",
                "datacontenttype": "application/json",
                "dataschema": "https://cloud.api.trimblecloud.com/events/registry/1.0/schematype/data/namespaces/com.trimble.tcp.testing/events/gourmet.coffee/v1.0",
                "data": {
                    "groupId": "4fc37620-4cc3-4deb-9f5b-6b5dac46aff0"
                }
            }
        ]
    }
}

Each event contains standard CloudEvents fields. Access event data in policies using event.data.{field_name} (e.g., event.data.groupId).

Policy Output Format

The policy must output a set or array of application IDs that are authorized to consume the events. In Rego, the output should be defined using the result variable.

result contains app_id if {
    // policy logic
}

The Events Service uses the result set to determine which applications are authorized to receive events.

Sample Policy

Example Rego policy using Rego v1 syntax:

package com.trimble.events.prd.tconnecttestproduction1

import rego.v1

result contains app_id if {
    group_apps := data["com.trimble.events.prd.tconnecttestproduction1"].rego.group_applications
    some event in input.events
    event_group_id := event.data.groupId
    some apps_for_group in [group_apps[event_group_id]]
    some app_id in apps_for_group
}

This policy iterates over input.events, accesses event.data.groupId, and references TAM data using data["package_name"].rego.{data_path} to determine authorized applications.