Subscribing to events

To listen to events, you register a subscription with the central event server. You do this by publishing special meta events:

{
    'topic': 'ftrack.meta.subscribe',
    'data': {
        'subscription': 'the-subscription-expression',
        'subscriber': {
            # Optional metadata about subscriber.
        }
    }
}

Likewise, to unsubscribe:

{
  "topic": "ftrack.meta.unsubscribe",
  "data": {
    "subscriber": {
      "id": "subscriber-id"
    }
  }
}

The subscription uses the expression syntax and is used to filter against each published event to determine if the registered client should receive that event. If the subscription matches, the registered client will receive the event and would typically call a registered function, passing the event as the sole argument.

Subscriber information

When subscribing, you can also specify additional information about your subscriber under the data/subscriber key. This contextual information can be useful when routing events, particularly when targeting events. By default, most clients will automatically set basic information about the subscriber context though you are free to add your own.

Expressions

An expression is used to filter against a data structure, returning whether the structure fulfills the expression requirements. Expressions are currently used for subscriptions when subscribing to events and for targets when publishing targeted events.

The form of the expression is loosely groupings of key=value with conjunctions to join them.

For example, a common expression for subscriptions is to filter against an event topic:

'topic=ftrack.location.component-added'

However, you can also perform more complex filtering, including accessing nested parameters:

'topic=ftrack.location.component-added and data.locationId=london'

note

If the structure being tested does not have any value for the specified key reference, then it is treated as not matching.

You can also use a single wildcard ‘*’ at the end of any value for matching multiple values. For example, the following would match all events that have a topic starting with ‘ftrack.’:

'topic=ftrack.*'