Design a flow

Creating flows with the visual, drag-and-drop Flow Designer is so simple it might disguise how powerful flows can be. With a palette of steps and the ability to add custom ones, you can connect rich, complex processes into a single, automated toolchain.

You could learn by doing, but if you want to learn first then do, this page walks you through the steps of creating a flow, the different trigger types, how to add and connect other steps, how to use the available tools, and how configure steps once they're connected.

Before you get started, remember that flows are tied to a form. Make sure your communication plan has a form that you want to build flows for, and that you have permission to access it. You can create multiple flows for a form, one for each trigger type. For those flows to run, the form needs to be enabled and you need a way to kick things off (both sending a message in the Messaging tab or an inbound integration will work).

As we go through the steps below, we'll build out a major incident management (MIM) flow initiated by a response to an alert from a monitoring tool. Along the way, we'll figure out what steps we need, what information needs to flow through the steps, and if the flow needs to split at some point.

How to get to Flow Designer

Access to Flow Designer is controlled by the communication plan — whoever has permission to access the communication plan can access the flows for forms in that plan.

ClosedAccess from the Communication Plan Builder
  1. Click the Developer tab.
  2. If it's not already selected, click Communication Plans under Communication Plan Builder on the left.
  3. Click Edit beside the plan you want to build a flow for and select Flows.
  4. Click the name of the form you want to create or edit flows for (or Create a flow if the form doesn't have any flows yet).
ClosedAccess from within a communication plan
  1. If you're already in the communication plan, click the Flows tab.
  2. Click the name of the form you want to create or edit flows for (or Create a flow if the form doesn't have any flows yet).

Step 1: Decide what triggers the flow

Triggers are steps that kick off each flow on the canvas based on system activities, such as event status changes, escalations, or event responses.

In our example, we're using a response to an event notification as the trigger — someone gets a notification in their xMatters app that there's an issue and, after reviewing the details, selects the Create Major Incident response to start that flow. For another workflow, you might need a different trigger type; for example, if you want to trigger a different workflow when an event is escalated, you'd use the Escalations trigger.

If you already know what you want to trigger your flow, drag it onto the canvas. Then you can skip ahead, though you might want to disable the flow until you have it laid out.

ClosedTypes of triggers

Triggers are initiated by different system activities. Each one populates different outputs that, along with common event properties, can be used in downstream steps.

Here's an overview of the different triggers (we also do a deep dive into each of the triggers, their outputs, and examples of when you might use each one):

Event Activity
Event Status Updates: An event is started, suspended, resumed, or terminated. Outputs include the status of the event and the user who initiated the event status change. Learn more.
Escalations: An escalation occurs in a group. Outputs include the group containing the shift with the escalation, the reason for the escalation, the user that escalated the event (if applicable), the type of escalation, the recipients the event escalated from, and the recipients the event escalated to. Learn more.
Event Comments: A user adds a comment from the mobile app, xMatters Inbox, email, Tracking Report, or xMatters REST API. Outputs include the user that made the comment and the content of their comment. Learn more.
Responses: A user responds to a message. Outputs include the response choice they selected, the ID of the recipient, and the device they responded on. Learn more.
Targeted Recipient Failures: None of the targeted recipients could be immediately notified for an event. Outputs include the type of failure, the first 100 targeted recipients, and the total number of targeted recipients. Learn more.
Device Delivery Updates: A notification is delivered to a device or notification delivery fails. Outputs include the user and device that the message was sent to and whether the delivery was successful. Learn more.
ClosedAdd a trigger to the canvas

After you decide on the trigger type, drag it from the palette to the canvas. You can use each trigger type once per form so when you drag a trigger onto the canvas, it disappears from the palette. When you delete it from the canvas, it reappears in the palette so it's available for you to use in future. If you've already built an outbound integration with the Integration Builder that uses the trigger, it appears on the canvas.

  1. Drag the trigger from the palette onto the canvas.
  2. Double-click the trigger icon to display information about the trigger and its properties.
  3. Click the Enabled toggle to enable or disable the it. When you disable the trigger, you disable the connected flow, which you might want to do until you've built it out.

For many triggers, that's all you need to do. To use the Responses trigger, you might need a bit more setup.

Responses trigger setup

To use the responses trigger, you need the individual responses that you want to trigger flows. If responses are already configured on the form, they'll appear under the parent trigger when you drop it on the canvas. If there are no responses, you can add them right from within Flow Designer.

  1. Click Add Response (or double-click the Responses parent) to add, remove, or edit response options.

  1. Configure the response options, drag them into the order you want them to appear on the canvas, then click Save. In our MIM scenario, we added "Create major incident" and moved it to the top of the list.

Each response appears as a step on the canvas. You can now connect the steps you want to be triggered when that response is received.

A few things to know about existing integrations:

  • If you have an outbound integration that uses the Notification Responses trigger, it appears on the canvas but doesn't have the response options delineated since any actions based on different responses are handled in the outbound integration script.
  • Some integrations use response options that are determined at runtime. We've updated our built-in integrations but some packaged or custom integrations still use these. For the time being, you'll need to continue to use an outbound integration using the Notification Responses trigger.
ClosedEnable and disable flows

Flows are enabled by default, but you can disable them by disabling the trigger. For example, you might want to disable a flow if you're doing some system testing, diagnosing a runtime issue, or fleshing out a new workflow.

  1. Double-click the trigger to open its dialog box.
  2. Click the Enabled toggle to turn the flow on or off.

Step 2: Decide what information needs to go where

The next step in designing a flow is to figure out what applications need to be included, as well as what information you want to push into those applications and when. This determines what steps you need to add, in what order you need to connect them, and what inputs you need to configure.

In our MIM scenario, the event is initiated by Monitoring Tool X. The form includes properties for summary, details, severity, incident_id, and customer_impacting. We know we need to push incident details into ServiceNow since it's our system of record in this scenario. We also want to post the incident details to a chat channel, but we want to include the ServiceNow incident number in the channel name, so the chat steps come after the ServiceNow Create Incident step. We'll get into the steps that come next when we talk about the switch step.

ClosedAdd a step

Whatever step you're adding, the basics are the same, though the setup required for each step and any prerequisites depend on the particular step. In many cases, you simply need to drag a step onto the canvas, connect it to a previous step, and configure any required inputs to get started. For some steps, you'll need to know the endpoint you want to send requests to (either to post to or get information from).

You also might need to add an app or set up a webhook in the target system to receive the information sent from xMatters.

  1. Locate the step in the palette, either in the Apps panel or the Custom panel.
  2. Drag the step from the palette onto the canvas.
  3. Drag a connector from the output port of the previous step in a flow to the input port of the step you're adding.
    • Connect the step before configuring it to make sure you have access to all the event properties and outputs from previous steps when setting up your inputs.

If the ready-made apps don't meet your needs, you can design custom steps to use in your flows.

ClosedConfigure the inputs

The setup required varies depending on the step you're adding, but how you configure the step is the same. When configuring inputs, you can include text or outputs from previous steps. These outputs appear in the panel on the right side of the screen — simply drag one from the panel to an input field. Some steps have a minimum or maximum number of characters allowed.

We provide instructions on using the ready-made steps in the Apps panel; for information on any custom steps, contact the person in your organization who created them.

  1. Double-click the step to open its configuration screen (or select it and click the pencil icon).
  2. Change the Step Label if it makes sense for your flow. For example, if you have a step to post to a specific channel and the channel name is hard-coded in a step input, you might want to the label to read "Post to antares-team-chat".
  3. Fill in the required inputs and any of the optional inputs you want to use in the flow of information. You do this by adding hard-coded text or by mapping output variables from the event, trigger, or previous steps, which appear on the right. The values of these are determined at runtime.

  1. Click OK to close the setup screen, then click Save at the top of Flow Designer.

Some things to keep in mind:

  • If you add a variable to an input field, Flow Designer has no way to validate the length of the value until runtime. So you won't get a validation error if you map a Detailed Description variable into a Summary input field with a maximum length of 150 characters. However, when the flow is triggered, it throws an error if the value passed is 2000 characters long. If this happens, the errors shows up in the Activity panel.
  • The value of the inputs you configure in this step might become outputs that you can use in steps further along the flow.
ClosedSet up an endpoint (if required)

Some steps require that you set an endpoint (for example, to send event information to a chat channel). You can use an endpoint that's already set up for the communication plan or you can set one up while configuring the step (which you can reuse in other steps).

  1. Click the Endpoint tab.
  2. Select an existing endpoint from the list, or click Create New Endpoint to set up a new endpoint. You'll only see endpoints that match the authentication type that was allowed when the step was created.
  3. If you create a new endpoint, a dialog box appears where you set up your new endpoint. You might not be able to change the authentication type; this is defined when the step is designed, and many specify a particular authentication type.
    • If you create a new endpoint, click Save Changes then Close on the Endpoints dialog box when you're done to return to the step setup.

  1. Click OK to close the step setup screen, then click Save on the canvas.

Step 3: Decide if your flow needs to take a detour

Tools are steps that evaluate the information coming through the flow and use it to decide what action to take next.

Adding a tool step is the same as adding any of the other steps — locate the step in the palette, drag it onto the canvas, and connect it to the preceding step. The configuration varies depending on the type of tool you're adding.

ClosedSwitch paths

Think of a switch step like the switch on a set of railway tracks. It determines what route the train — or flow — will take based on event properties, trigger outputs, constants, or outputs of previous steps in the flow. For example, a flow could be routed based on a severity property ("Critical" goes one way, "High" another, everything else follows a third, default path) or a customer impacting property ("Yes" follows one route, "No" another).

In our MIM scenario, we split the flow based on the customer_impacting event property. A value of Yes creates a Statuspage incident then posts to our NOC dashboard. Any other value just posts to the dashboard.

To configure a switch step:

  1. Double-click the switch step to open the setup screen (or select it and click the pencil icon).
  2. Enter a label for the switch (for example, if the split in your flow is based on event priority, you might label the switch Priority).
  3. Select the property you want to use to decide which path the flow takes. This list is populated with event and trigger properties, outputs from any previous steps, and constants.
  4. Click Done.
  5. Click Add Path and then click the block to set the value you want to flip the switch (for example, if you want the flow to take one path based on "High" priority events and another based on "Medium" priority events, add paths for High and Medium).
    • If any events come through with a value other than those set in the paths, they follow the Default path (for example, if a "Low" priority event comes through, it would follow the Default path).
  6. Set up the flows you want to follow for each path.
  7. Click Save on the canvas.

Step 4: Test your flow

It's always a good idea test your flow before putting it into active use. This lets you check if there are any mismatched output-to-input mappings, issues in the underlying setup of any custom steps, or problems with endpoints.

  1. Inject an event that targets your form, either through the Messaging tab, an inbound integration or the xMatters REST API.
  2. Perform whatever action triggers your flow. For example, select the response (Responses trigger) or add a comment (Event Comments trigger).
  3. Use the Activity panel to track down any issues.