Appearance
Subscriptions and filters
Each consumer connection has one subscription to your workspace's messages, with a filter on the message's message_type and, optionally, its topic and its source. You choose them when you create the connection and can change them at any time. Only messages that match reach its queue.
A message reaches the queue when it matches all of the filter's parts: one of its message types, its topic prefix (if set) and one of its sources (if set).
To see every connection's filters against who publishes what in your workspace, open the Routing map.
By message type
List up to 20 of these, in any mix:
| You ask for | You receive | Example |
|---|---|---|
| An exact type | That type only | story.context |
A family, ending in .* | Every type that starts with it | telling.* receives telling.started, telling.ended, telling.exposed |
* | Everything |
The filter matches the envelope's message_type, the one thing SOM says selects a payload. It includes message types that have no SOM 1.0 schema, such as many skill triggers, when they match: a consumer must ignore the types it doesn't handle, rather than fail on them.
Topic prefix
Optionally, the subscription also matches on the start of the envelope's topic. With som.story.context.acme-, only messages whose topic starts with that reach you.
Every topic starts with som., so a prefix must too: the portal refuses one that doesn't, such as story.context, because it would match no message. Leave the prefix empty to receive every topic of the message types you chose. A connection created before this check keeps its prefix; change it before you edit the connection's other filters.
topic is free text after som., so a prefix only works for traffic whose producer puts something recognisable in it. A publisher house's workspace carries other organisations' traffic too. To receive only your own tests there, publish with topics that carry your prefix, such as som.story.context.acme-hurricane-1, and ask for that prefix, or filter by source (below).
By source Available now
Optionally, receive only what some producers send: "the web CMS takes story.context only from the newsroom system". Name a source in either of two ways, in any mix, up to 10 in all:
| You name | You receive messages | Matched on |
|---|---|---|
| A producer connection of your workspace, shown in the portal as its app and organisation | Published with that connection's credentials | The producer_id message attribute |
| A system_id | Whose envelope's originating_system.system_id is that value | The system_id message attribute |
With several sources, a message from any of them matches. With none, every source matches.
- A source must belong to your workspace: an active producer connection in it, or a system_id one of them publishes as. That includes connections of other organisations' apps connected to your workspace.
- Choose by connection to follow one set of credentials. If the producer's connection is revoked and the app connects again, the new connection has a new id that your filter doesn't name: edit the filter. The portal warns about this before anyone revokes a producer connection that a filter names.
- Choose by system_id to follow the system, whichever credentials it publishes with. A system_id belongs to one app across the bus, so it keeps matching when that app connects again.
- Message types × sources can be at most 150 in one filter (for example 15 message types and 10 sources). Use a family (
telling.*) or*to name fewer types.
Change a filter in place Available now
In the portal, open Consumer connections and press Edit filters on the connection. You need the developer role or above. You can change the message types, the topic prefix and the sources.
- The queue stays. Its messages, its dead-letter queue and its client secret are kept. The new filter applies to messages published after it takes effect, within a minute.
- Messages already in the queue stay, even if the new filter wouldn't have let them in.
- A revoked connection keeps the new filter and uses it once you restore it.
- Every change is recorded in your workspace's audit log, with the filter before and after, who changed it and when.
What a filter doesn't do
- It doesn't change the message. From the queue with AWS credentials you receive the producer's exact bytes; over the pull API, the same envelope, parsed.
- It doesn't order anything differently: order is per
correlation_id, whatever the filter. - Messages that don't match aren't kept for you. A new connection, or a wider filter, receives only what is published after it's in place; to get earlier messages, ask for a replay.
- It doesn't decide who may publish. Which producers may send which message types is set on their connections; a source filter only chooses what your queue receives.