Topic Strings

Topic strings are the vocabulary of IBM MQ pub/sub. Every publication carries one; every subscription references one or a wildcard pattern. Unlike queue names that are flat identifiers, topic strings form a tree: each slash-separated segment is a level, parent paths encompass children for matching and authority, and wildcards let you subscribe to families of events without listing every leaf. Misunderstanding + versus # is the most common reason a new subscription “never receives anything”—the publish string retail/uk/store/order/created does not match retail/+/created because two levels sit where + allows only one. This tutorial explains hierarchy design, wildcard rules with worked examples, comparison of exact versus pattern subscriptions, naming standards for enterprises, interaction with TOPSTR on topic objects, and debugging DISPLAY SUB versus the publish string in logs.

Hierarchy and Segments

Each segment between slashes is one level. Root-to-leaf depth can vary by branch—retail/uk/order/created is four levels; health/patient/admit is three. Deep hierarchies improve security granularity (grant SUB on health/patient/#) but increase operational complexity. Shallow trees simplify matching but cram too much meaning into one level. A common pattern is domain/entity/action or domain/region/entity/event. Document whether empty segments or trailing slashes are forbidden—double slashes create ambiguous levels teams did not intend.

Worked Examples: Plus Versus Hash

Published string: logistics/shipment/uk/dispatched. Subscription logistics/+/dispatched fails—uk is one level but shipment/uk is two levels between logistics and dispatched. Subscription logistics/shipment/+/dispatched succeeds—+ absorbs uk. Subscription logistics/# succeeds—# absorbs shipment/uk/dispatched. Subscription logistics/shipment/# also succeeds. Subscription logistics/+/+/dispatched succeeds with first + = shipment, second + = uk. Draw the tree on paper when designing patterns.

1
2
3
4
5
6
DEFINE SUB('SUB.UK.DISPATCHED') TOPICSTR('logistics/shipment/+/dispatched') +
  DEST('LOGISTICS.UK.Q') SUBUSER('logapp')
DEFINE SUB('SUB.ALL.LOGISTICS') TOPICSTR('logistics/#') +
  DEST('LOGISTICS.ALL.Q')
* Publish test: topic string logistics/shipment/uk/dispatched
* First sub receives; second sub also receives

Exact Strings Versus Patterns

Subscriptions without wildcards must match the published string exactly (subject to case rules). Use exact subs when a service consumes one event type only—inventory/stock/adjustment. Use + when one level varies (country, tenant). Use # for monitoring or audit platforms that need wide coverage—treat # subscriptions as privileged because they see everything under a branch. Never grant SUB on # to general application IDs.

Naming Standards

• Use lowercase consistently if your platform matching is case-sensitive.
• Prefer nouns for entities (order, payment) and verbs for actions (placed, refunded).
• Separate environments: dev/retail/... versus prod/retail/... or use separate queue managers.
• Version in payload or in a dedicated level—avoid mixing strategies.
• Reserve system prefixes (sys/, $SYS if used) from business namespaces.

Topic Objects and TOPSTR

DEFINE TOPIC('FIN.PAYMENT') TOPSTR('finance/payment') anchors the branch. Publications may target the object or the string; subscriptions may reference TOPIC('FIN.PAYMENT') with wildcard suffix rules per IBM syntax. Renaming for applications can be done with ALIAS topic objects pointing at a new TOPSTR without republishing code strings—governance advantage over raw strings only.

Authority Follows the Tree

setmqaut -t topic -n 'finance/payment/#' grants on a subtree. Publishing to finance/payment/completed requires PUB authority at or above that node. Planning strings therefore plans security boundaries—do not bury sensitive events under a wide branch with loose PUB grants.

Explainer: Address Lines

A topic string is like country/city/street/event. Wildcard + means “any one city name.” Wildcard # means “everything below this street address line onward.” Wrong wildcard choice sends mail to the wrong district.

Debugging Mismatches

1. Log the exact publish topic string from publisher MD or trace.
2. DISPLAY SUB(*) TOPICSTR for active patterns.
3. Verify subscription is durable and application connected if non-durable.
4. Check SUB and PUB authority on the resolved nodes.
5. Confirm no typo in slash versus dot—finance.payment is not finance/payment.

Explain Like I'm Five: Topic Strings

Topic strings are addresses with slashes between house, street, and town. Plus means “any one town.” Hash means “this town and everything inside it.”

Practice Exercises

Exercise 1

For publish retail/eu/de/order/placed, which matches: retail/+/placed, retail/#, retail/+/order/placed?

Exercise 2

Write a subscription that hears all retail order events in any country but not catalog events.

Exercise 3

Document a naming standard table with three columns: level, meaning, example.

Frequently Asked Questions

Test Your Knowledge