Custom workflow guide

The easiest way to integrate xMatters with a third-party application and get started building automated toolchains is to use one of our available workflow templates. Our Workflow Templates collection includes built-in and packaged custom workflows for many applications used in today's IT resolution processes.

Workflow templates have their own specific guides to help you through the set up and configuration process. If you're using a workflow template, you can find its guide at xMatters Integrations.

Can't find a template for the application you're looking for?

No problem! You can easily design your own workflow from scratch - this guide shows you how.

When you design a workflow from scratch, you can completely customize your incident resolution process by building your own forms, properties, messages, and responses. This means you can tailor your communications to suit the situation, recipient, and required action based on any business process, emergency, or technology, and you can use Flow Designer to create orchestrated toolchains and automate incident management.

If you've converted a built-in workflow or imported a custom workflow to use as a starting point, then this guide gives you a good overview of the different things you can customize, such as changing the properties brought into xMatters from the source system, editing the content and appearance of messages, and adapting response choices and their actions.

Get to know custom workflows

Congratulations, you've just created a custom workflow! We're guessing you're looking at the following screen and wondering what you should do next.

Well you've come to the right place. Let's start with a quick overview of the different things you see on this screen:

  • Forms: Define the information that's contained in messages, how a message is presented to a recipient on their devices, and the response options that are available. Forms are used to create alerts in xMatters, and you can't build a flow in Flow Designer until you've created a form. Learn more.
  • Flows: Access Flow Designer, which allows you to build automated toolchains for each of your forms that connect xMatters with your DevOps and IT applications. Learn more.
  • Properties: Create check boxes, option lists, and number selectors to include data into your forms and messages, and which are available to flow steps for forms that include them. Learn more.
  • Integrated Properties: Define special properties that allow you to extract information from an integrated external system and include it in your messages. Learn more.
  • Integration Builder:  Build integrations between xMatters and another application. The Integration Builder is in the process of being replaced by Flow Designer. Learn more.
  • Subscription Forms: Allow users to be notified about alerts even if they're not one of the alert's targeted recipients. Learn more.
  • Workflow Settings: Click the gear icon at the top of the screen to access settings for your workflow.
    • Export: Use your workflow as a template or to import to another xMatters environment. Learn more.
    • Notification Flood Control: Prevent users from being flooded with multiple notifications when they're already working on resolving the issue. Learn more.
    • Edit Permissions: Control which users or groups can edit your workflow. Learn more.
    • Delete: Permanently remove the workflow from your system. Learn more.

Design a custom workflow

We've got comprehensive documentation for all of the different components that make up workflows. This guide isn't intended to replace that documentation - it's designed to walk you through an example workflow to highlight the main tasks you'll need to perform when setting up your own workflow from scratch, and to point you to the resources that can help you along your way.

To do that, let's look at a sample workflow created for the pirate ship "Poseidon's Barnacle".

Step 1: Create a form

One of the first steps in creating any custom workflow is to create a form. Workflows typically include one or more forms based on a business need or unifying theme. For example, a workflow named "IT Incidents" might include forms with names like "Failover Status", "Incident Conference Bridge", and "Initial Incident".

For a pirate ship, a workflow might include the following forms:

Step 2: Create properties

Properties allow users, or applications you're integrating with, to input values into xMatters so they can be used in messages or flows. These can include boolean check boxes, option lists, or number selectors.

Here's a sample of some of the properties included in our Pirate Ship workflow:

Name Type Details
Action Combo Box

Declare Mutiny

Fire Cannons




Details Text Up to 20,000 characters
Part of Ship List


Crow's Nest








Poll Description Text Up to 2,000 characters
Port of Call





  Fort Royal



  St. Mary's Island

  Île Sainte-Marie



  St. Paul's Island


Priority List




Value Number -

Properties are available to any of the forms in your workflow. When you insert a property in a message, its value replaces the property name when the form is initiated. To use properties in a message or flow, they first need to be associated with the form by dragging them onto the form layout. That's what we'll look at in the next section.

Step 3: Design the form layout

The form layout is where you define what's included on your message form, like predefined recipients, the type of devices that are targeted, a conference bridge, attachments, and more. You can drag-and-drop predefined or custom sections onto your form layout. By default, the form layout includes the Recipients section and a Custom section. Beyond that, form elements and layout are very flexible.

To include the properties we created in our messages, we'll add them to a custom section on our form layout. Here's how this would look for the Pirate Poll form layout, where we're dragging the 'Poll Description' property onto our layout:

You may notice that we've added the 'Poseidon's Barnacle - Full Crew' group as default recipients. It's not mandatory to have predefined recipients for your forms, but it's good practice to include them when you typically notify the same people each time, because it can improve the message sender's speed and accuracy.

We've also added the Response Overrides section to our form layout. This allows the message sender to change the response options for the poll, in case they want to edit the existing responses, or add new ones.

Step 4: Define message content

Once you've got your form layout and properties in place, you can start designing the content of the email, text (SMS), and voice notifications that the form will be used to send.

While Mozilla Firefox is a supported browser, the Email / Fax / Push Message and Text (SMS) / Pager / Generic message editors are only supported in Explorer 11 and Google Chrome.

Step 5: Define response options

Response options allow recipients to respond using the mobile app, email, phone, or text, and define the action xMatters takes when each response is selected. These actions may include escalating or terminating the alert, or connecting the recipient to a conference bridge.

Response options are highly flexible. For a full overview of all the different ways you can use responses and how to add them to a form, see Define response options.

Step 6: Deploy forms and set sender permissions

Initially, only the user who creates a form access to it. For your forms to run and be available to message senders, you need to deploy them and grant sender permissions to the users that you want to be able to send them.

Step 7: Enable your workflow and set editor permissions

Before you can start testing your messages, you'll need to check that your workflow is enabled. And, if you'd like to let other users in your company be able to edit your workflow, you'll also need to assign them editor permissions.

Step 8: Test and troubleshoot your forms

As part of the process of building a custom workflow, you'll want to preview your forms, as well as add yourself as a recipient and initiate the form to check whether the message content you've created comes across to the message recipient as you intended.

Step 9: Other options

So far in this guide, we've covered the basics for building the foundation of a workflow. There are some additional options that you may want to take advantage of that can help message senders do their job more efficiently, and keep interested parties informed about events taking place in the organization even if they're not directly involved.


Scenarios allow you to save versions of a form with predefined values for common or anticipated situations, making it easier to send relevant messages quickly when those situations arise. For more information, see Define scenarios.

Subscriptions and Activity Updates

Often, there are people in your organization who would like to be notified about alerts even if they're not directly involved. For example, the captain of the Poseidon's Barnacle is interested in knowing about the treasure acquired by his crew, even if he's not involved in the looting mission.

There's a couple of ways to keep interested parties informed about alerts taking place in xMatters:

  • Subscriptions: Allow users to subscribe to notifications for an alert, even if they were not targeted by the original notification. To allow people to subscribe to alerts, you must create a subscription form for your workflow. A subscription form defines who can subscribe to alerts, which properties they can subscribe to, and whether they can respond to notifications. Learn more.
  • Activity updates: Notify recipients when a form is initiated and when notifications conclude. Learn more.

Step 10: Build Flows

Now that you've defined the underlying framework for your workflow, including its forms, properties, messages, and responses, you can use Flow Designer to build automated flows to facilitate your digital services availability and incident resolution processes.

For example, when our pirate monitoring system detects an incident - such as an imminent threat to the safety of Poseidon's Barnacle or her crew - it can inject that information into xMatters. We can then kick off a series of actions across different tools, transforming and passing information to steps further downstream.

To cast off on the adventure of creating flows to support your workflow, see Flow Designer 101.