How to use subscriptions

In xMatters, you can use subscriptions to ensure that you are always informed about certain events. Depending on your permissions and the configuration of your deployment, you can set up subscriptions with specific criteria, or be added to event feeds by a supervisor. These subscriptions will send you notifications whenever an event occurs that matches your criteria, even if you are not scheduled to receive a notification for that event; for example:

  • The manager of a network administration team wants to receive an email whenever an outage occurs on a particularly problematic server so she can create a record of these events.
  • The manager of the produce department in a grocery store wants to know every time an issue is reported with a refrigeration unit anywhere in the store, even if the issue is not occurring in her area.
  • The supervisor for the fuel depot at an airport wants everyone on his team to be notified whenever a supply shortage is reported, even if they are not on shift at the time of the shortage.

How subscriptions work

Events are usually injected into xMatters from an external system or application, though some events can also be initiated by xMatters itself. xMatters identifies each source, and differentiates it from other sources, based on the properties contained within the event. xMatters then creates and sends notifications to the appropriate personnel, and processes the responses.

A subscription form, usually created by a workflow designer, acts as a filter on events from a particular source. The subscription form designer can specify:

  • Which form properties are available to use when specifying a subscription's criteria
  • Which users (or roles) can subscribe to the form
  • Whether other users can be assigned to the subscription
  • Which devices can receive the subscription notifications

This means that the information you can use to subscribe to events may be entirely different for each subscription form — even ones based on the same workflow.


Let's say that you work for a major general goods retailer, and you have designed a workflow to handle events that are injected into xMatters by the software on the loading dock. The workflow and its forms use the information in the event to determine the particulars of each incoming delivery and notify the people on shift in each department to let them know that a shipment has arrived. But some of your users want to know about certain deliveries even when they aren't on shift. So you design a subscription system that will send people notifications based on the properties of the event. Here's how that system might work:

In the above illustration, a delivery of seafood arrives at the loading dock, and an event is injected into xMatters. xMatters processes the event, and then creates and sends notifications to the appropriate targeted and on-call recipients.

The workflow has two subscription forms: one for groceries (or perishables), and another for clothing. The delivery contains the grocery property, and xMatters checks for subscriptions based on the groceries form. There is an active subscription based on seafood, so xMatters sends a notification to the subscribers that a seafood delivery has arrived.

How subscription responses work

Subscription notifications can be one-way (FYI) notifications, or they can include the same response options defined on the form for targeted notifications. These response choices have the same effects on the originating event as response actions configured for targeted notifications, meaning that they will still record the response or end the event.

To aid in the design and implementation of some specific integrations that rely on subscriptions as the main notification delivery mechanism, xMatters treats subscription notifications and targeted notifications as separate entities with respect to escalation management. What this means is that a response to a subscription notification will not affect the group escalation process for targeted notifications sent for the same event.

For example, imagine that an event entering the system generates two notifications: a targeted notification sent to the Operations group which has a five minute delay between members, and a responses-enabled subscription notification sent to Mary McBride. The first Operations group member on the schedule does not respond, but Mary responds to her subscription notification with "Assign to User", effectively taking ownership of the event. Because subscription and targeted notifications are separate streams, however, the escalation for the Operations group continues, and the second member is notified five minutes later. The same would also be true if the subscription notification was sent to the Operations group, and Mary responded to a targeted notification. (The exception to the continued escalation behavior is the "End" response action, as this would effectively terminate the event for all recipients.)

To avoid this situation, make sure that everyone who may need to take specific actions on events for a particular form is receiving either targeted or subscription notifications, but not both. In the case where users and groups are all receiving targeted notifications, for example, you may want to configure your subscriptions as one-way, and not enable responses at all.

How duplicate subscription notifications work

To help you avoid unnecessary or distracting clutter in your inbox, xMatters dynamically identifies the best content to send based on your role in the communication process, and automatically suppresses any unnecessary duplicate subscription notifications. This ensures that primary responders and decision makers receive only directly-targeted notifications, and other stakeholders or subscribers get the content most appropriate for their needs. Here's how it works:

  • If you're targeted directly as a recipient for an event, you will receive only the targeted messages; xMatters suppresses (or 'de-duplicates') any notifications that you might have received from your subscriptions.
  • If you're notified about an event via two-way subscription, you'll receive a notification with response options on each of your targeted device types; xMatters suppresses any notifications you might have received via one-way subscriptions.
  • If you have only FYI (one-way) subscriptions, you'll receive a notification about an event on each of your targeted device types; xMatters suppresses any duplicate FYI subscription notifications.
  • If you're targeted by your username for a subscription notification, you'll receive subscription notifications according to your defined device delays. When you acknowledge a subscription notification from one of your devices, xMatters stops notifying your other device types.
  • If you have more than one subscription for the same messaging form, xMatters will use the first one based on an alphabetic sorting of subscription names.

There are also a couple of caveats you should keep in mind:

  • This suppressed behavior does not apply to escalated notifications. If you are part of a group with an escalation delay, and the primary on-call users don't respond, all of your notifications will be delivered once the event escalates to you.
  • This suppression behavior also does not apply to delayed subscriptions. If you are using subscriptions as part of a reporting mechanism or some other process that requires you to receive all subscription notifications, you can add a short delay to your subscription to ensure that all of your messages are still delivered.