Skip to main content

Defining Publish and Subscribe Message Routing

InterSystems IRIS® supports publish and subscribe message delivery. Publish and subscribe refers to the technique of routing a message to one or more subscribers based on the fact that those subscribers have previously registered to be notified about messages on a specific topic.

Publish and Subscribe Overview

Publish and subscribe messaging works based on the runtime interactions between:


A message is a production message. An external system receives a request and directs it into InterSystems IRIS, which converts it to a production message and sends it to a special-purpose business operation for processing.


A topic is a string that characterizes the contents of a message. InterSystems IRIS does not define any topics; users and their applications define the meanings of topics and subtopics.

A topic string has the form A.B.C.D, where A, B, C, and D are subtopic strings delimited by the . (period) character. A topic can contain any number of subtopics; each of these subtopics can be up to 50 characters long. The following are all valid topic strings:


You can specify a range of topics by using * (the asterisk) as a wildcard character. For example:

  • * can replace any complete subtopic in the topic string (books.*.latin works)

  • * does not work as a partial wildcard (*s.fiction does not work; it does not match books.fiction, reviews.fiction, or any similar string)

  • A trailing * character matches any number of additional subtopics to the right of the last . (period) character in the topic string (books.* matches books.fiction and books.fiction.latin)


A subscriber is an entity (a user or an external system) that might be interested in a specific topic or set of topics. A subscriber entry specifies how that entity wishes to be contacted; that is, how InterSystems IRIS should send a message to it.


A subscription associates a subscriber with a topic string.

Suppose you have three subscribers:


And three topics with the convention that A.B.C represents person.location.identifer:


In that case, you could define the following subscriptions:

Subscriber Topic
Abel Doctor.ICU.88494
Abel Doctor.ICU.88495
Baker Doctor.ICU.88495
Baker Patient.LAB.*
Charlie *.*.X3562564

This means:

  • Abel is notified whenever the exact topics Doctor.ICU.88494 or Doctor.ICU.88495 are processed.

  • Baker is notified whenever the exact topic Doctor.ICU.88495 is processed. In addition, Baker is notified whenever any message related to patients in the lab are processed.

  • Charlie is notified whenever anything related to a doctor or patient with an identifier of X3562564 is processed.

Implementing Publish and Subscribe Message Routing

Creating a Publish and Subscribe Operation

To use publish and subscribe features, you must create a production that includes an instance of the EnsLib.PubSub.PubSubOperationOpens in a new tab class.

Configuring Publish and Subscribe

When you configure publish and subscribe features for a production, the basic steps are:

  1. Create domains (optional).

  2. Create a list of subscribers.

  3. Create subscriptions to associate subscribers with topics.

From the Interoperability > Manage > Publish & Subscribe page, you may select Show Domains, Show Subscribers, Show Subscriptions, or Create New Subscription. The pages for domains and subscribers are similar to that for subscriptions, but each provides a different Create command: Create New Subscriber or Create New Domain Name.

Technical Details

Publish and subscribe messaging uses the following classes in the EnsLib.PubSub package:

Class Name Purpose
EnsLib.PubSub.PubSubOperationOpens in a new tab Business operation that provides publish and subscribe message routing.
EnsLib.PubSub.RequestOpens in a new tab Request class that packages requests to the PubSubOperation class. Specifies which topic and DomainName should be used to determine how the message should be routed. Optionally, the Request may also contain the message being routed, but the PubSubOperation does not need this information to return its TargetList.
EnsLib.PubSub.ResponseOpens in a new tab Response class that packages responses from the PubSubOperation class. Contains a collection of Target objects called TargetList, which the calling business process consults before dispatching the message to the required destinations.
EnsLib.PubSub.SubscriberOpens in a new tab Persistent class that represents individual subscribers. These are entities interested in being notified when certain messages arrive. The Subscriber class includes any information needed to contact the actual subscriber.
EnsLib.PubSub.SubscriptionOpens in a new tab Persistent class that stores the association between a given Subscriber and a topic string.
EnsLib.PubSub.DomainNameOpens in a new tab Persistent class that holds the set of PubSub domain names. Domain names are optional; like namespaces, domains provide a way to keep different subscription lists separate.
EnsLib.PubSub.UtilsOpens in a new tab Utility class that provides a programmatic API for creating and deleting domains, subscribers, and subscriptions.
EnsLib.PubSub.TargetOpens in a new tab Persistent class that provides details about how to route a message to a destination outside a production. The Target object has a Target property that identifies a configured business process or business operation within the current production. The Target object has an optional Address property that can specify an external address, for example an email address.

Instead of using the Management Portal, you can manipulate the objects directly using methods in the EnsLib.PubSub.UtilsOpens in a new tab class.

EnsLib.PubSub.PubSubOperationOpens in a new tab does not actually send messages to subscribers; instead, it provides a mechanism to quickly find the set of interested subscribers for a given topic. It is the responsibility of a business process that calls the PubSubOperation to dispatch messages to subscribers.

At runtime, an incoming message is sent to a business process, which examines it for identifying details. Based on this analysis, the business process assigns the message a specific topic string that does not contain any wildcard characters. It then creates an EnsLib.PubSub.RequestOpens in a new tab message that contains this topic string and sends it to the PubSubOperation.

The PubSubOperation uses an extremely fast search algorithm to find and return a list of all subscribers interested in this topic. The PubSubOperation returns an EnsLib.PubSub.ResponseOpens in a new tab message that contains a collection of EnsLib.PubSub.TargetOpens in a new tab objects called TargetList. The business process iterates over this collection to dispatch the message to each EnsLib.PubSub.TargetOpens in a new tab in the collection.

FeedbackOpens in a new tab