Integrating IBM MQ Topics and Queues with AMPS

This page covers two common IBM MQ integration shapes: preserving IBM MQ topic naming in AMPS and modeling worker-oriented message queue flows with AMPS queues. In both cases, preserving familiar IBM MQ destination names makes it easier to introduce AMPS for high-performance state, delivery control, and observability while keeping a straightforward path for applications that later publish directly into AMPS.

Where IBM MQ and AMPS Overlap

IBM MQ topic filtering can use character-based wildcards rather than token-delimited topic wildcards. AMPS can preserve those wildcard patterns by using TopicMatchingPolicy set to ibmmq as the instance default or as a local override on the imported IBM MQ namespace. Subscriptions and SOW queries can also use topic_matching_policy=ibmmq, and any TOPIC_MATCH predicate in the same command filter uses IBM MQ wildcard rules.

AMPS also provides queue delivery models that map naturally to worker-oriented IBM MQ flows. AMPS queues support:

• at-least-once and at-most-once delivery semantics
• Lease-based redelivery control with LeasePeriod
• Per-queue and per-subscriber backlog limits with MaxBacklog and MaxPerSubscriptionBacklog
• Distributed, local, and bounded-cluster queue topologies through Queue, LocalQueue, and GroupLocalQueue
• Queryable queue state, views over queues, and conflated queue summaries for operator dashboards

That overlap is useful when a team wants to preserve IBM MQ topic strings such as Sport/Football/Results or Orders/DeskA/Priority while adding:

• Persistent current state through the State of the World (SOW)
• Queues for worker delivery with explicit semantics
• Atomic initial load plus live updates through sow_and_subscribe
• Server-managed rollups with Views and Unions
• UI-friendly refresh rates with ConflatedTopics
• Lower-bandwidth browser updates through sow_and_delta_subscribe

IBM MQ Queue Concerns Mapped to AMPS Queues

For IBM MQ-style worker processing, the closest AMPS building blocks are the queue types documented in the AMPS user guide.

IBM MQ-Oriented Concern	AMPS Queue Capability
One worker should process a message at a time	AMPS queues deliver each message to a single subscriber at a time.
The message should be retried if a worker fails	Use Semantics of at-least-once plus a LeasePeriod so unacknowledged work returns to the queue.
The message should never be redelivered after dispatch	Use Semantics of at-most-once.
Limit how much work is outstanding	Use MaxBacklog and MaxPerSubscriptionBacklog.
Control how long work may remain pending	Use Expiration and ExpirationModel.
Keep work local to one server or one subset of a mesh	Use LocalQueue or GroupLocalQueue.
Build backlog dashboards for operators	Query the queue directly, create a View over the queue, and expose a ConflatedTopic for the UI.

IBM MQ Patterns Compared to Default AMPS PCRE

The default AMPS topic matching policy is pcre, which uses full regular expressions. IBM MQ wildcard syntax is simpler and treats the pattern as a whole string rather than as a tokenized topic hierarchy.

IBM MQ Pattern	Meaning	Representative PCRE Equivalent
Sport/*ware/Results	Match any characters between Sport/ and ware/Results	^Sport/.*ware/Results$
Orders/Desk?/Priority	Match exactly one character in place of ?	^Orders/Desk./Priority$
*	Match every topic string	.*

Under ibmmq, * matches any sequence of characters, ? matches exactly one character, and % escapes *, ?, and % so they are treated literally. Unlike RabbitMQ, MQTT, Solace, TIBCO, or NATS topic matching, the wildcard is not tied to a specific topic-level separator.

Recommended AMPS Design

For most IBM MQ integrations, the cleanest AMPS design looks like this:

1. Preserve the original IBM MQ topic string when the bridge publishes into AMPS.
2. Keep the instance default at pcre unless most of the instance uses IBM MQ semantics. For imported IBM MQ namespaces, add TopicMatchingPolicy set to ibmmq beside each Pattern, UnderlyingTopic, or transaction-log topic filter that should use IBM MQ rules.
3. Capture the relevant topic space into a Pattern topic so AMPS maintains current state per logical IBM MQ topic without a separate SOW topic definition for each topic.
4. Define an AMPS Queue, LocalQueue, or GroupLocalQueue over the relevant IBM MQ-style work stream, and choose Semantics of at-least-once or at-most-once based on the worker requirement.
5. Set queue controls such as LeasePeriod, MaxBacklog, MaxPerSubscriptionBacklog, Expiration, and FairnessModel to match the worker profile.
6. Build a Union whose UnderlyingTopic repeats that same pattern expression when dashboards or downstream services need one consolidated SOW topic.
7. Build Views and ConflatedTopics on top of the queue or union for operator dashboards, UI refresh, and backlog monitoring.

This layout works well for phased coexistence and for direct AMPS adoption later because the topic model presented to applications stays stable while worker delivery becomes explicit and observable in AMPS.

info

A Pattern topic cannot be used directly as the underlying source for a View. Use a Union first, with the same pattern expression in the Union UnderlyingTopic, then place the View or ConflatedTopic on top of the Union.

Sample Configuration

The following configuration keeps the instance default at pcre, preserves an IBM MQ-style order namespace in AMPS with local IBM MQ overrides, creates an at-least-once worker queue for that namespace, and exposes a dashboard-oriented queue summary:

<AMPSConfig>
  <Name>ibmmq-observability</Name>
  <TopicMatchingPolicy>pcre</TopicMatchingPolicy>

  <TransactionLog>
    <JournalDirectory>./journals</JournalDirectory>
    <Topic>
      <Name>ibmmq-order-work</Name>
      <MessageType>json</MessageType>
    </Topic>
    <Topic>
      <Name>Orders/*</Name>
      <TopicMatchingPolicy>ibmmq</TopicMatchingPolicy>
      <MessageType>json</MessageType>
    </Topic>
  </TransactionLog>

  <SOW>
    <Topic>
      <Name>ibmmq-order-space</Name>
      <Pattern>Orders/*</Pattern>
      <TopicMatchingPolicy>ibmmq</TopicMatchingPolicy>
      <MessageType>json</MessageType>
      <Key>/orderId</Key>
      <FileName>./sow/%n.sow</FileName>
    </Topic>

    <Queue>
      <Name>ibmmq-order-work</Name>
      <UnderlyingTopic>Orders/*</UnderlyingTopic>
      <TopicMatchingPolicy>ibmmq</TopicMatchingPolicy>
      <DefaultPublishTarget>Orders/DeskA/Pending</DefaultPublishTarget>
      <MessageType>json</MessageType>
      <Semantics>at-least-once</Semantics>
      <LeasePeriod>30s</LeasePeriod>
      <MaxPerSubscriptionBacklog>10</MaxPerSubscriptionBacklog>
      <FairnessModel>proportional</FairnessModel>
    </Queue>

    <Union>
      <Name>ibmmq-order-union</Name>
      <MessageType>json</MessageType>
      <UnderlyingTopic>Orders/*</UnderlyingTopic>
      <TopicMatchingPolicy>ibmmq</TopicMatchingPolicy>
    </Union>

    <View>
      <Name>ibmmq-queue-backlog-by-desk</Name>
      <MessageType>json</MessageType>
      <UnderlyingTopic>ibmmq-order-work</UnderlyingTopic>
      <Projection>
        <Field>/desk</Field>
        <Field>COUNT(/orderId) AS /queuedCount</Field>
      </Projection>
      <Grouping>
        <Field>/desk</Field>
      </Grouping>
    </View>

    <ConflatedTopic>
      <Name>ibmmq-queue-backlog-by-desk-ui</Name>
      <MessageType>json</MessageType>
      <UnderlyingTopic>ibmmq-queue-backlog-by-desk</UnderlyingTopic>
      <Interval>1s</Interval>
    </ConflatedTopic>
  </SOW>
</AMPSConfig>

If you truly want to capture the entire IBM MQ topic namespace, use * as the Pattern. In practice, most teams use a bounded namespace such as Orders/* or Sport/* so entitlements, monitoring, and disk planning stay predictable. For queue-oriented migrations, start by mapping one workload at a time to an AMPS queue with explicit semantics and backlog controls.

Usage Tips

• Use TOPIC_MATCH when a field stores the original IBM MQ topic string. For example, /topic TOPIC_MATCH 'Sport/*ware/Results' applies IBM MQ wildcard rules to the field value.
• Use % when you need a literal wildcard character, for example /topic TOPIC_MATCH 'orders/%*.json'.
• Migrating clients can keep IBM MQ wildcard syntax on a per-request basis with topic_matching_policy=ibmmq on commands such as subscribe, sow, and sow_and_subscribe.
• Use LIKE only when you intentionally want PCRE behavior regardless of the resolved topic policy.
• Choose the SOW key from the business entity, not from the topic alone, when one IBM MQ topic can carry repeated updates for the same object.
• Use at-least-once when the worker must acknowledge successful processing, and at-most-once when avoiding redelivery is more important than retry.
• Use Queue for fully distributed delivery, LocalQueue for single-instance worker flows, and GroupLocalQueue when only a defined subset of a replicated mesh should host the workload.
• Build queue-focused views and conflated topics for operators, and use the Pattern SOW topic plus a Union over the same pattern expression for whole-namespace state and drill-down analytics.
• Use sow_and_subscribe against the Union or View to hydrate an operator screen atomically, then keep it up to date without a query gap.
• Use sow_and_delta_subscribe or a ConflatedTopic for browser-based dashboards that do not need every intermediate update.