Flow tools

Tools are steps that use information coming through a flow to decide what action to take next or to gather additional information from xMatters to use in the flow. They help you create richer, more refined flows adapted to your use cases.

Utility steps

The Utilities steps let you do things such as modify your flow based on information coming from previous steps or send information coming through the flow to other systems.

Switch step

A switch step functions like the switch on a set of railway tracks. It determines which route the train — or flow — needs to take next. You can base this decision point on the value of almost any property in the flow such as trigger outputs, constants, or outputs of previous steps.

Here are a few examples of how you can use a switch step:

  • The value of a "Severity" property: "Critical" goes one way, "High" another, everything else follows a third, default path.
  • A success response from a Create Ticket step: "201" continues the flow, while "400" sends a notification that something went wrong.
  • The value of a "Team" property: "Alpha" follows one path that includes a "Post to Alpha Chat" step and "Beta" follows another path that posts to the Beta Chat channel.

^ Back to top

 

Condition step

While a switch step lets you choose a path based on a specific property value, a condition step allows for more intricate logic to determine which pathways are selected in your flows by using 'AND/OR' logic and a range of conditional operators to compare both string and numerical values.

Here are a few examples of how you could use a condition step:

  • An incident's severity is either High or Critical and alert priority is less than 3.
  • Earthquake magnitude is greater than 5 or the epicenter distance is less than 100 miles.
  • The name of a customer who reported an incident matches a specified value.

As another example, here's how a single condition step can replace two switch steps in our ServiceNow integration's 'Engage with xMatters' workflow.

Instead of using one switch step to identify what type of conference bridge is required and then another switch step to determine whether a new bridge needs to be created, the condition step checks for bridge type and determines if there's an existing bridge in a single pass.

The combination of multiple forms of logic, pathways, and conditions in one step allows your designers to easily create and modify workflows to whatever complexity is required for your use cases.

^ Back to top

 

Merge step

The merge step lets you combine up to 10 flows into one path, giving you the ability to create new outputs and populate them with information for each of the flows. When a particular flow runs, the values specified for that flow are passed into the Merge step outputs.

^ Back to top

 

Webhook step

The webhook steps lets you send information from the flow to any system capable of receiving an HTTP POST request.

^ Back to top

 

xMatters steps

The xMatters steps let you do things in your xMatters instance, like create an alert, find a user, add an xMatters conference bridge, initiate an incident, map incident severity, and more. We've grouped the steps into sections so it's easy to find the information you're looking for for.

Alert Steps

Create Alert

The Create Alert step is the latest version of the Create Alert Using a Form step (formerly known as the Create Event step). It lets you create an alert at any point in your flow in response to previous steps, using information from those steps to populate alert details and targeted recipients. Unlike the Create Alert Using a Form step, which requires a messaging form and properties to create the alert, the Create Alert has its own message and response builders built directly into its configuration screens in Flow Designer. You can use any upstream flow variables to configure your messages and responses, without having to map them to properties of your workflow.

Over time we'll update the Create Alert step with the full functionality of messaging forms. Currently, if you want to configure messages in different languages, use recordings in voice messages, count responses, and support features like subscriptions, scenarios, or attachments, use the Create Alert Using a Form step and a messaging form instead.

For example, you might want to use the Create Alert step to:

  • Quickly and easily build automated alerts into your flows (without having to configure a messaging form).
  • Send automated messages after an App, Custom HTTP, or Email trigger, or based on responses to a notification.
  • Send an update during your flow that iterates on an existing message.
  • Configure alerts with alternative messages and response options for the different paths of your flows.

^ Back to top

 

Create Alert Using a Form

The Create Alert Using a Form step (formerly known as the Create Event step) lets you use a messaging form to create a new alert at any point in the flow in response to previous steps, using information from those steps to populate alert details and targeted recipients. You can use any messaging form in the workflow to create the alert.

For example, you might want to create a new alert: 

  • In response to an email trigger, with the addressees in the email becoming the recipients of the alert notification.
  • Based on an "Emergency alert - Location" switch step, creating alerts targeting different groups with different instructions if the location is Los Angeles versus London.
  • After an HTTP trigger, populating the alert details using the values of properties in the request, including setting the recipients from an "Assignment Group" output on the trigger.
  • Create an alert using a different form that targets your customer support team after a "Customer Impacting" switch step.

^ Back to top

 

Get Alerts

Use the Get Alerts step to get the alerts IDs of the 50 most recent alerts in xMatters that match search criteria such as status, priority, or the value of an alert property. You can combine search criteria to narrow your results or add multiple status or priority values to broaden the search.

^ Back to top

 

Terminate Alerts

Use the Terminate Alerts step to terminate up to 50 alerts, using their alert IDs. You can use the Get Alerts step earlier in the flow to retrieve the IDs for the alerts you want to terminate. When you terminate alerts in xMatters, it stops all processing, including canceling any active notifications, and cannot be resumed.

The Terminate Alerts step has no outputs.

^ Back to top

 

Map Alert Priority

The Map Alert Priority step lets you map the priority levels from an external system to xMatters alert priority levels. You can use the output of this step to set the priority when configuring a connected step, like the Create Alert Using a Form step.

^ Back to top

User steps

Find User

Use the Find User step to look up the ID and target name of an xMatters user based on specific values of a selected property (such as the user's email address, target name, web login, or the value of a custom user property). For example, you could use this step to look up a user who has the value "Rigel" in a Team Lead field, and then use the output from this step to set that person as the recipient of a connected Create Alert Using a Form step.

If there is more than one matching user, only the first user is returned. The outputs provide the unique identifier (UUID) and target name of the first user that matches the search criteria.

^ Back to top

 

Find User Property Value

Use the Find User Property Value step to look up the value of a custom user property based on the ID and target name of an xMatters user. For example, you could look up what value the "Jira SD ID" field holds for user mmcbride and pass that value to a step further downstream so it can set the assignee in Jira.

The output provides the value of the specified custom field or attribute.

^ Back to top

 

Create xMatters Conference step

The Create xMatters Conference step allows you to initiate an xMatters hosted conference bridge in your flow.

^ Back to top

 

Incident steps

Initiate Incident step

The Initiate Incident step allows you to create an incident. Use this step to define the basic details of the incident (type, summary, description, severity, and impacted services), the values for any incident properties, and to connect incident Status Change, Severity Change, and Notify to Engage flow triggers.

^ Back to top

 

Add Note to Incident step

You can use the Add Note to Incident step to add a note to the incident timeline at any point in your flow. This is useful for providing information to resolvers about flow activities and to make this information available for the Post-Incident Report. The user who authenticates the flow is recorded as the creator of the note in the timeline.

^ Back to top

 

Add Collaboration Channel to Incident step

You can use the Add Collaboration Channel to Incident step to automatically link any type of collaboration channel to an incident in xMatters. By adding a collaboration channel to the Incident Console, you can include information (such as a name, description, and URL link) so teams can easily find the right place to communicate about issues. The user who authenticates the flow is recorded as the creator of the collaboration channel in the incident timeline.

^ Back to top

 

Add Stakeholders to Incident step

You can use the Add Stakeholders to Incident step to add stakeholders to an incident in xMatters. Stakeholders receive status updates about the incident, but they are not resolvers and are not actively engaged in the incident.

^ Back to top

 

Add Task to incident

The Add Task to Incident step lets you add a task to an incident at various points in your flow.

^ Back to top

 

Add Task List to incident

The Add Task List to Incident step lets you add one or more task lists in your system to an incident.

^ Back to top

 

Map Incident Severity step

The Map Incident Severity step lets you map the severity levels from an external system to xMatters severity levels. You can use the output of this step to set the severity when configuring a connected step, like the Initiate Incident step.

^ Back to top

 

Add Change Record step

The Add Change Record step lets you add a change record using the xMatters API. Recording a change can help incident resolvers understand if it contributed to the root cause of an incident. Inputs include information such as the type of change, its external source, and a summary that describes the change. If the change impacts an xMatters service, you can associate the service with the change. You can use the output of this step to reference the change record within xMatters during your team's incident resolution process.

^ Back to top

Get Incident

The Get Incident step lets you get current incident information, such as severity, status, impacted services, and the current incident commander and pass it on to other steps in your flow. You can also retrieve the value for specified incident properties and add them as outputs. This lets you use that information to perform specific incident management or resolution tasks for that incident. For example, you could send incident information to external systems like Statuspage to keep stakeholders and customers informed, or change incident details using the Update Incident step to reflect actions performed by resolvers.

^ Back to top

Update Incident

The Update Incident step lets you update details for an existing incident when information changes. This not only keeps the Incident Console as up-to-date as possible for users as they work to resolve an incident, but also helps ensure that changes from other systems or actions taken by resolvers that impact the incident are reflected immediately. and can be communicated to resolvers and stakeholders. All updates are logged in the incident's Timeline.

You can also specify any incident properties you want to update. If the incident or incident type does not have a corresponding property, the property is ignored.

Get Incident Collaboration Channels

The Get Incident Collaboration Channels step lets you get information about collaboration channels for specific incidents, such as the names, URLs, details, and total number of collaboration channels associated with an incident. This allows you to see how incident resolvers are communicating and send channel information to external systems or additional teams to engage them in the conversation.

^ Back to top

Get Incident Attachments

The Get Incident Attachments step lets you retrieve information about attachments in specific incidents, such as the names, URLs, and total number of files attached to an incident. This allows you to access files that resolvers have attached to an incident and provides you additional information about the issue.

^ Back to top

Callable flows

A callable flow step lets you 'call' another flow in your workflow to run. A callable flow step works in tandem with a callable trigger. You use the callable trigger to build the sequence of steps you want to run and to define what information to pass from the calling flow to the steps connected to the callable trigger. When you add a callable flow step to any of the flows in the same workflow, when the step runs it'll call its associated trigger to initiate the sequence of steps.

For example, if you need the option to initiate a major incident process in more than one of your flows, instead of including the same sequence of steps in each flow (such as posting to a status page, creating or updating chat channels, opening a help desk ticket, sending notifications, etc.), you could build the sequence once — as a separate, reusable flow — and then include a step in your other flows to call that flow to run. If you ever need to change the steps in your process or modify their configuration, you only need to do it in one place.

^ Back to top