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.

  1. Drag a switch step onto the canvas.
  2. Double-click the step to open the setup screen (or move your cursor over the step and click the pencil icon).
  3. Enter a label for the switch (for example, if the split in your flow is based on alert priority, you might label the switch Priority).
  4. Select the property you want to use to decide which path the flow takes. This list is populated with available properties, and you can quickly find properties or outputs with the Search bar. For example, in our priority scenario, you could use the priority output of a trigger as the switch property.
  5. Click Done.
  6. Click Add Path and then click the block to set the value that flips the switch (for example, if you want the flow to take one path based on "High" priority and another based on "Medium" priority, add paths for High and Medium).
    • If any priority property comes through with a value other than those set in the paths, they follow the Default path (for example, if a "Low" priority comes through, it would follow the Default path).
  7. Set up the flows you want each path to follow.
  8. Click Save on the canvas.

Does your flow follow a path you don't expect? What if your flow gets to the switch and simply stops? This can happen if the switch can't match the value passed to it to one of its paths. If you have a step connected to the Default path, it'll flow that way; if you don't, it doesn't know where to send it, so it stops. The most likely culprit is a difference between the value coming in and the values you configured for the paths.

Double-check the value coming into the switch, whether it's coming from a constant, the output of an HTTP trigger, or some other step in the flow. Make sure the spelling and capitalization match the configured paths (for example, the switch reads "omicron" and "Omicron" as different values). While you're at it, check for extra spaces in the property value coming into the switch, too.

^ 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.

  1. From the Utilities section of the Tools tab, drag a merge step onto the canvas and connect the flows you want to combine.
  2. Double-click the step to open the setup screen (or move your cursor over the step and click the pencil icon).
    • Each connected flow has a tab named for the step immediately preceding the merge step — this makes it easier to know which flow you're working with. However, you can use outputs from any of the steps when configuring the merge step.
  3. On the Settings tab, enter a label for the step — this appears on the canvas to help identify the purpose of the step.
  4. For each output you want to make available to steps downstream, click Add Step Output and enter a name for the output.
  5. Click the tab for the first flow and define what the value of the outputs should be when that flow is run.
    • You can use plain text, constants or the outputs from any previous steps in that flow. Use the Search bar to quickly find properties or outputs in the menus.
    • Each output needs a value, otherwise steps further downstream that use the output could fail. If an output isn't applicable for a particular flow, add something like 'not applicable', 'N/A', etc.
  6. Repeat the output definition on the tabs for each of the remaining connected flows.
  7. After you define the outputs for each of the incoming flows, click Save.
  8. Click Save on the canvas.

When the flow is run, the values specified for whichever flow initiates the step are passed into the outputs.

  1. To delete an output, click the x beside the output on the Settings tab.
  2. Click Delete on the confirmation dialog that appears to let you know that this step might impact the flow.
  3. Click Save.

Any steps downstream of the merge step will show validation errors if they were using the output. Make sure you fix those steps to avoid errors at runtime.

In this example, we follow different paths depending on what the severity is in the incoming signal. If it's critical or high, we initiate an incident and notify resolvers, then create and post to a Slack channel. If the severity is anything lower, we simply create a Jira ticket and then create and post to a Slack channel. We use the merge step to decide what information should be available to the Slack steps for each flow — this lets us reduce duplication and maintain consistency, rather than having completely separate flows for different severity levels.

For the High / Critical path, we use a mix of values from the trigger, the Initiate Incident step, and the alert to set the merged values. We made sure to populate the Incident ID field with the Incident ID output from the Initiate incident step — this lets us use it to add Slack as a collaboration channel on the incident:

For the Medium and lower path, we set the Incident ID to the Jira ticket ID and set Alert Priority to N/A, since no alert is created in this flow.

^ 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.

  1. From the Utilities section of the Tools tab, drag a webhook step onto the canvas and connect it to your flow.
  2. Double-click the step to open the setup screen (or move your cursor over the step and click the pencil icon).
  3. Enter a label for the step (for example, if the step sends an update to a webpage informing users of your application's status, you might change the label to "Post Service Status").
  4. Click the Endpoint tab and select the endpoint for the system you want to send the webhook to.
    • If the endpoint you want doesn't appear in the list, click Edit Endpoints to add a new endpoint.
  5. On the Settings tab, enter a URL Suffix if needed.
    • This appends an additional path to the Base URL of the selected endpoint. For example, if the Base URL is https://status-website.com and you want to send the request to https://status-website.com/pages/antares-status, enter /pages/antares-status in the field.
    • This might be something you want to store in a constant so you can drag the constant into the field.
  6. Select the content type to tell the receiving system how to parse the payload (for example, application/json or application/x-www-form-urlencoded).
  7. Add the payload you want to send in Webhook Body. You can drag outputs from previous steps into the body to populate parameters with values coming through the flow.



  1. Click OK.
  2. Click Save on the canvas.
Property Description Example
Response Code The HTTP response code received from the target system. 200

^ 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.

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 the 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, one-touch conferencing, 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.

  1. Drag an xMatters Create Alert step onto the canvas.
  2. Double-click the step to open the setup screen (or hover over the step and click the pencil icon).
  3. Update the step label to reflect the purpose of the alert. For example, if the step follows a "Customer impacting=true" path on a switch step, you might name it "Create Customer Care Alert".
  4. Use the message templates to compose the email, xMatters mobile app, text, and voice notifications to send for the alert.
  5. Fill in the recipients and incident settings using text, outputs from previous steps, trigger properties, constants, or a combination of these. You can quickly find outputs with the Search bar. See the guidelines on setting recipients and incidents settings for details.
    • If this step is notifying resolvers for an incident, make sure to populate the Incident ID field with the "Incident ID" output from the connected Initiate Incident step — this is what associates the resolvers to the incident.
  6. Use the Response Options tab to create the response options to include with your notifications.
  7. Use the Devices tab to set which device types to target for notification (for example, 'Work Phone' and 'Work Email').
  8. Use the Handling & Overrides tab to modify the default notification handling settings, if needed, although the default settings (for notification priority and expiration, voicemail options, and other handling options) should work for most of your alerts. You can also modify the caller ID and display name associated with this alert.
  9. After you've finished configuring the step, click Done.
  10. Click Save on the canvas.

Once you're done setting up the Create Alert step, you can then add activity triggers to your canvas that kick off flows when different lifecycle activities occur for the alert (status updates, device delivery updates, responses, comments, escalations, and targeted recipient failures).

If you want to associate a conference bridge for any of your response options, you can add the Create xMatters Conference step to one or more Responses activity triggers.

The Create Alert step message editors do not currently support multiple languages. If your system has more than one language defined and you want to create message content in multiple languages, use the Create Event step instead.

The Setup tab of the Create Alert step includes a Message Templates section that lists the type of messages you can compose for your alert: Email / App, Text, or Voice. The name of each template is a hyperlink to that tab of the message builder. Flow Designer displays warning and error badges for any messages that are missing content or contain invalid variables.

The following sections describe how to compose messages for each template type:

Email / App

The Email / App tab of the message editor allows you to create content for email and xMatters mobile app notifications. It includes a WYSIWYG editor with inline editing and formatting features that will be familiar to most users.

To compose Email / App messages:
  1. Add content to the Subject field, including message and flow variables. For helpful tips on creating a message subject, see Write a helpful message subject.
  2. Add content to the message body. For more information about including variables in message content, see Include properties in message content.
    • If you make a mistake, use Undo to step back or Redo to step forward.
  3. Add images to the message body. For more information about inserting images into email messages, see Include images in email messages.
  4. Format the message using the available options in the inline editor, or click Code View to format the underlying HTML. For formatting tips, see Best practices for formatting Email / App messages.
  5. Click Save.

Text

Use the Message Content field to build your text (SMS) message by typing in text and using message and flow variables. Due to length limitations of text messages, it's important to keep messages short, as they need to also include the value of variables, carrier information, and responses.

Messages longer than 459 characters, including variable values at runtime, may be truncated to accommodate responses and carrier information. Messages longer than 160 characters are broken into smaller segments that are sent individually and reassembled on the recipient's device. Because SMS messages are subject to these and other inherent limitations, we recommend taking some extra time when building out your messages for text devices to ensure you're creating effective, useful SMS notifications.

For other tips, tricks, and recommendations for using xMatters to send text messages, see Best practices for SMS messages.

Voice

The voice message builder of the Create Alert step does not currently support voice recordings.

You can build voice messages by composing phrases for xMatters to read to recipients using text-to-speech (TTS).

To compose a voice message:
  1. Type text or drag variables to create a phrase.
  2. Select a playback option for the phrase. xMatters can either speak the value as a phrase or spell out the individual letters.
  3. To add additional phrases, click + Add Phrase.
  4. To change the order of the listed phrases, grab the handle icon to the left of the phrase and drag it to a new position in the list.
Setting recipients

Specify recipients using the xMatters target name of the user, group, dynamic team, device, or service you want to target. For example, this can include mmcbride, AntaresDB-Support, Responders-Team, mmcbride|Work Email, or API.

Populate the Recipients field by mapping an output from a previous step, using a constant, by hard-coding the target name, or a combination of these. If using a constant or an output from a previous step, make sure it provides the information as an xMatters target name.

To target multiple recipients, use a comma between the input variables or target names. For example, to notify both the CustomerCare group and email the VP of Customer Support, use CustomerCare, mmcbride|Work Email. There is a 20,000 character limit for recipients, so if you need to notify a large number of recipients consider creating a group or dynamic team.

Target names that contain commas aren't supported, and may result in targeting errors. If there are no recipients at runtime, xMatters only notifies subscribed users.

Setting the Incident ID

If there is an Initiate Incident step preceding the Create Alert step, use the "Incident ID" output from that step in the Incident ID field. This associates the notification with the incident in xMatters and adds the recipients as resolvers in the Incident Console.

Response options allow recipients of the alert to respond by text, mobile app message, email, or phone. Response options are highly flexible and allow you to:

  • Configure actions the system should take for a response (e.g., Unavailable = Escalate).
  • Assign contribution values for reporting (e.g., Accept = Positive).
  • Redirect users to a web address (URL) after they respond.
  • Specify the response number a recipient should press, regardless of the order they're listed.
  • Build automated workflows triggered by a response option. For example, a "Create Major Incident" response could initiate an incident in xMatters, create a conference bridge, post to a chat channel, and create a post to a status website, all as a result of selecting the response in the notification. Adding a new response option automatically creates a corresponding trigger on your canvas.
To configure response options:
  1. On the Responses tab, click Add Response Option.
  2. In the Response Option field, provide the response option to display in text, xMatters mobile app, and email messages.
  3. In the Email Description field, provide an additional description to include in email messages.
  4. In the Voice Prompt field, type a phrase to be read to voice device users using text-to-speech, before prompting the user to press a digit. For example, "To respond with <Voice Prompt>, press <Digit>." Click the number in the voice prompt field to select the number a recipient of a voice notification should press to select this response option.
  5. From the Action drop-down, select the action the system takes when a recipient selects this response option. The actions you assign affect how (and when) xMatters continues to notify other recipients in the escalation path.
Value Action
Record Response Record the user's response and stop notifying them, but continue notifying other recipients. When this response action is selected, xMatters does not delink the user from the event. Users can change their responses by responding to the notification again.
Stop Notifying User Stop notifying the user, but continue notifying other recipients.
Stop Notifying Target Stop notifying the user (and any other members if notified as part of a group or dynamic team), but keep notifying other users and members of other groups.
Escalate Stop notifying the user and immediately escalate the event to the next scheduled recipient.
Assign to User Record the user's response and stop notifying other recipients. The user can respond again or change their response.
End Stop notifying all recipients and immediately terminate the event . This stops notifications whether the responses came from an individually targeted user, a user in a group, or from within a nested group.

The behavior of "Stop Notifying Target" and "Escalate" can be complicated for 'nested' groups (i.e., when groups are members of other groups), and when other recipients are also targeted by the same alert. For examples that outline the behavior of these actions for common situations, see Response action examples.

  1. From the Contribution drop-down, select how to categorize the response for user and group performance reports.
Value Action
None Response is not used when calculating contributions for performance reports, but is still displayed on Events reports. (This value does not have the same meaning as a 'Neutral' contribution value.)
Positive Response used for reporting. For example, you might assign a positive value to a response of "Accept" or "Own".
Neutral Response used for reporting, but has no negative or positive connotation. For example, you might assign a neutral value to a response of "Acknowledge" or "Unavailable". (This value does not have the same meaning as a 'None' contribution value).
Negative Response used for reporting. For example, you might assign a negative value to a response of "Reject" or "Escalate".
  1. To redirect the user to a URL after they respond, in the URL Redirect field, enter a valid URL address. When users select the response option in an email, xMatters Inbox, or mobile app notification, the URL automatically opens in a new browser window.
    • You can include constants or flow variables in the URL address. To access the variables available to you to drag into this field, click the Show flow variables link below the URL Redirect field.
  1. To enable or disable the ability to comment when users respond to notifications in email or the xMatters Inbox, select or clear the Enable comments for this response check box. To control commenting for all response options, select or clear the Enable comments for all response options check box in the left side bar.
  2. To add additional response options, click Add Response Option.
  3. To change the order of the response options, grab the handle icon to the left of a response option and drag it to a new position in the list.

Response number and order

The order response options are listed in the Create Alert step determines the order they're presented to recipients. The digit you assign to a response corresponds to the button the recipient of a voice notification should press to select that response choice.

While text phone devices also present the response options based on the number assigned to them on the number pad, the actual number required for each response may be different. For example, if you create three response choices of ACCEPT, IGNORE, and CLEAR, numbered 1, 2, and 3, all voice notifications will prompt recipients to press 1 to accept, 2 to ignore, and 3 to clear. Each text message will present the response choices in the same order, but may require a different number, due to the way simple SMS responses are processed by xMatters; e.g., "Press 5 to ACCEPT, 6 to IGNORE, or 7 to CLEAR."

The Devices tab lets you set which device names the Create Alert step targets for notification. For example, you can use these settings to specify that this step only notify mobile devices and work phones.

If a recipient doesn't have one of the specified devices, they won't get notified (unless you've configured failsafe devices for your users and groups).

There are two ways you can specify which device names to target for notification:

Set device names using values from outputs or constants

You can specify a comma-separated list of device names to target using the outputs of previous steps, constants, or text - or a combination of these. The value that's provided at run-time must match a valid device name (you can see a list of the available device names when you select the next option, to pick from a list of device names).

Pick from a list of device types

This is the default option that's selected when you add a new Create Alert step. By default, xMatters selects all devices.

The Handling & Overrides tab includes settings to control how the alert behaves and how recipients interact with voice notifications (for example, you can specify the alerts's priority and expiration, as well as several override, password, and voicemail options), and they allow you to override the Caller ID and display name associated with the alert.

When you add a Create Alert step to the canvas, it uses default handling and override values. To edit a setting, select or specify a new value. For some settings, you have the option to Use Output or Constant Value. This allows you to use text, the output of a previous step, or a constant as the value for the setting. The value that's provided at run-time must match one of the valid values listed for that setting.

For example, the value that's passed into the Alert > Priority property as part of your flow must be LOW, MEDIUM, or HIGH when the step is initiated to be a valid input for the Priority alert handling setting.

Property Description Example
alert.id The unique identifier (UUID) of the alert. e930e32d-b863-4c55-a528-1d2829e3690e
alert.alertId ID assigned to this alert by xMatters and used to track its progress through the system. (Also the number used to reference this alert in the Alerts and Tracking reports.) 889003

Activity triggers kick off flows based on different alert lifecycle activities, including status updates, device delivery updates, responses, comments, escalations, and targeted recipient failures. Each of these different triggers includes a common set of properties, and additional properties specific to the type of activity.

For detailed descriptions of activity triggers and their properties, see Alert activity triggers.

To add an activity trigger to a Create Alert step:
  1. Click + Activity Triggers below the Create Alert step.
  2. From the drop-down list that appears, select the type of activity trigger to add.
    • The trigger appears below the Create Alert step on the canvas.
    • Each activity trigger can only be used once, so when you add one of these triggers to a Create Alert step, it disappears from the list; when you delete it from the canvas, it reappears in the list so it's available for future use.
  3. Double-click the trigger on the canvas (or hover over the step and click the pencil icon) to view its outputs, or to enable or disable it.
  4. Connect the flow you want trigger when this type of activity occurs for the alert.

^ 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.

Before using the Create Alert Using a Form step, there are a few things to keep in mind:

  • To use this step, you require a messaging form. The step does not appear in the palette unless the workflow contains at least one messaging form.
  • The user initiating the flow must have sender permissions for the targeted form.
  • The target form defines the notifications that are sent and the responses available. If you're targeting a different form, you can also create a whole new set of flows associated with that form that are triggered by the new alert.

How to set up a Create Alert Using a Form step:

  1. Drag a Create Alert Using a Form step onto the canvas.
  2. Double-click the step to open the setup screen (or move your cursor over the step and click the pencil icon).
  3. Select the form to use for the alert (the form description, if it exists, appears below the name) and click Apply.
    • You can't switch the form used by the step after you click Apply. If you decide you want to target a different form, delete this instance of the step from the canvas and add a new Create Alert Using a Form step.
  4. Update the Step Label to reflect the purpose of the alert. For example, if the step follows a "Customer impacting=true" path on a switch step, you might name it "Create Customer Care Alert".
  5. Fill in the recipients and alert properties using text, outputs from previous steps, trigger properties, constants, or a combination or all three. You can quickly find properties or outputs with the Search bar. See the guidelines on setting recipients and properties for details.
    • If this Create Alert Using a Form step is notifying resolvers for an incident, make sure to populate the Incident ID field with the "Incident ID" output from the connected Initiate Incident step — this is what associates the resolvers to the incident.



  1. Use the Devices tab to set which device types to target for notification (for example, 'Work Phone' and 'Work Email').
  2. Use the Handling & Overrides tab to modify the form's default notification handling settings, if needed, although the form's default settings (for notification priority and expiration, voicemail options, and other handling options) should work for most of your alerts. You can also modify the caller ID and display name associated with this alert.
  3. After you've finished configuring the step, click Done.
  4. Click Save on the canvas.
Setting the Incident ID

If there is an Initiate Incident step preceding the Create Alert step, use the "Incident ID" output from that step in the Incident ID field. This associates the notification with the incident in xMatters and adds the recipients as resolvers in the Incident Console.

Setting recipients

Specify recipients using the xMatters target name of the user, group, dynamic team, device, or service you want to target. For example, this can include mmcbride, AntaresDB-Support, Responders-Team, mmcbride|Work Email, or API.

If the form specifies default recipients, they appear in the Recipients field; delete a default recipient if you don't want to include them in the alert notifications. Populate the Recipients field by mapping an output from a previous step, using a constant, or by hard-coding the target name (or a combination). If you're using a constant or an output from a previous step, make sure it provides the information as an xMatters target name.

To target multiple recipients, use a comma between the input variables or target names. For example, to notify both the CustomerCare group and email the VP of Customer Support, use CustomerCare, mmcbride|Work Email. There is a 20,000 character limit for recipients, so if you need to notify a large number of recipients consider creating a group or dynamic team.

Target names that contain commas aren't supported, and may result in targeting errors. If there are no recipients at runtime, xMatters only notifies subscribed users.

In case the previous step can't provide the target device, you can set the devices to target in the Devices section of the form associated with the Create Alert Using a Form step.

Setting properties
  • Use text, constants, outputs from previous steps, or a combination to populate the alert properties.
  • The properties you can fill out are based on the properties of the targeted form — if you want to include different properties, you need to add them to the form. Any defaults set for properties other than lists appear on the configuration screen, and any required properties must be filled in.
  • If you configured validation on a form property, that validation is done at runtime. If the value is not valid, the flow fails. For example, if a Date property requires the date to be in ISO 8601 format, and a date in a different format comes through at runtime, the flow will fail.
  • To enter a hierarchy property, use an angle bracket (">") between the levels of the hierarchy. Here's an example of a "Location" hierarchy::

  • To enter multiple values for a list property, use a comma between the two values. Here's an example of a "Systems" list:

The Devices tab lets you set which device names the step targets for notification. For example, you can use these settings to specify that this step only notify mobile devices and work phones.

When you add a Create Alert Using a Form step to the canvas, it uses the device settings that exist for the selected form by default. When you change which devices the step targets in Flow Designer, it'll override the settings configured on the form layout when your flow initiates the step.

If a recipient doesn't have one of the specified devices, they won't get notified (unless you've configured failsafe devices for your users and groups).

There are two ways you can specify which device names to target for notification:

Set device names using values from outputs or constants

You can specify a comma-separated list of device names to target using the outputs of previous steps, constants, or text - or a combination of these. The value that's provided at run-time must match a valid device name (you can see a list of the available device names when you select the next option, to pick from a list of device names).

Pick from a list of device types

This is the default option that's selected when you add a new Create Alert Using a Form step. It gives you access to the devices settings configured for the form associated with the step. If you select this option, but the Devices section isn't included on the associated form, xMatters adds the section and selects all devices by default.

The Handing & Overrides tab gives you access to the handling and sender overrides settings for the form associated with the step. These settings allow you to control how the alert behaves and how recipients interact with voice notifications (for example, you can specify the alert's priority and expiration, as well as several override, password, and voicemail options), and they allow you to override the Caller ID and display name associated with the alert.

When you add a Create Alert Using a Form step to the canvas, it uses the handling and override values that exist for the selected form. You can change the value of any of these settings on the Handling & Overrides tab in Flow Designer, and they'll override the settings configured for the form when your flow initiates the step.

To edit a setting, select or specify a new value. For some settings, you have the option to Use Output or Constant Value. This allows you to use text, the output of a previous step, or a constant as the value for the setting. The value that's provided at run-time must match one of the valid values listed for that setting.

For example, the value that's passed into the Alert > Priority property as part of your flow must be LOW, MEDIUM, or HIGH when the step is initiates to be a valid input for the Priority alert handling setting:

Property Description Example
event.id The unique identifier (UUID) of the alert. e930e32d-b863-4c55-a528-1d2829e3690e
event.eventId ID assigned to this alert by xMatters and used to track its progress through the system. (Also the number used to reference this alert in the Alerts and Tracking reports.) 889003
event.status The current status of the alert. ACTIVE
event.created Date and time the alert was created in xMatters in ISO-8601 format. 2019-01-15T18:03:16.580Z
event.priority The priority assigned to the notification in xMatters: LOW, MEDIUM, or HIGH. HIGH
event.recipients The recipients targeted for notification. mmcbride|Work Email, AntaresDB-Support
event.initiator The target name of the user who initiated the alert. integrationUser
conference.bridgeNumber The ID number of the conference associated with the alert. This is only available if there is a conference bridge associated with the form.

74778487

^ 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.

  1. Drag a Get Alerts step onto the canvas.
  2. Double-click the step to open the setup screen (or move your cursor over the step and click the pencil icon).
  3. Edit the Step Label to give the step a unique label for the particular flow.
  4. Fill in the search criteria to find the alerts whose IDs you want to return and pass along the flow. You must include at least one of Status, Priority, or Property Name.
    • Status: Search for alerts by their status (active, suspended, or terminated). You can include multiple, comma-separated values to find alerts matching any of the statuses.
    • Priority: Search for alert by their priority (low, medium, or high). You can include multiple, comma-separated values to find alerts matching any of the priorities.
    • Property Name, Property Value, and Exact Property Value Match: Use these fields together to find alerts with a specific value for the specified property name. You can only include one value per field. Exact Property Value Match sets whether the property value needs to be an exact match (true) or can be a partial match (false); this defaults to true if left blank. If Property Name is blank, the other two fields are ignored; if Property Name is set but the other two fields are blank, all alerts with a matching property name are returned.
    • Plan Name: Search for alerts created by forms in a specified plan. You can include multiple, comma-separated values to find alerts created by any of the listed plans.
    • Form Name: Search for alerts created by the specified form. You can include multiple, comma-separated values to find alerts created by any of the listed forms.
  5. Click OK.
  6. Click Save on the canvas.

Here's an example search that would return all active alerts that were high or medium priority where the value of the project_name property was either "Betelgeuse App" or "Betelgeuse 2.0" (because Exact Property Value Match is false):

Output Description Example
Alert IDs A comma-separated list of alert IDs for up to 50 alerts that match the search criteria. These IDs are the same as the IDs that identify the alert in the web user interface (for example, in the Tracking report). 18960003, 18964000, 18964002
Number of Alerts IDs Returned The number of matching alert IDs returned in the Alert IDs output. 50
Total Alert Count The total number of alerts found that match the search criteria. 57

^ Back to top

 

Terminate Alerts

Use the Terminate Alerts step to terminate up to 50 alerts, using their event 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.

  1. Drag a Terminate Alerts step onto the canvas and connect it to a previous step that provides the IDs of the alerts you want to terminate in an output (for example, a Get Alerts step).

  1. Double-click the step to open the setup screen (or move your cursor over the step and click the pencil icon).
  2. Edit the Step Label to give the step a unique label for the particular flow.
  3. Drag the output that provides the IDs of the alerts you want terminate into the Alert IDs input.

  1. Click OK.
  2. Click Save on the canvas.

^ 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.

  1. In the Tools tab, under xMatters, drag the Map Alert Priority step onto the canvas and connect it to your flow.
  2. Double-click the step to open the setup screen (or move your cursor over the step and click the pencil icon).
  3. Enter a step label to identify it in your flow.
  4. Identify the Input Parameter from the external system whose values you'd like to map to xMatters priority levels.
  5. Select the Default Priority level to use if the runtime value of the input parameter does not match one of the values mapped for each xMatters priority level.
  6. Specify which values of the input parameter map to each xMatters priority level (High, Medium, and Low).
    • You can map multiple levels to a priority level by entering each value on a new line.
  7. Under Priority Mapping Rules, select if you'd like either, or both, rules to apply:
    • Allow Partial Matches: If selected, the values mapped to each xMatters priority level can be contained in the runtime value of the input parameter. For example, in the screenshot below, if the runtime value of the input parameter is "1-Maximum", then a "High" priority level is assigned as the output of the step (because "Maximum" is defined as one of the values that maps to the High priority level, and it is contained in the input parameter value).
    • Case Sensitive: If selected, priority mappings consider letter case. In the example below, a runtime value of "level1" for the input parameter would not map to the High priority level (because "level1" and "LEVEL1" are not considered a match) and the default priority level "Medium" would be assigned as the output of the step.

  1. Once you're happy with the settings, click Done.
  2. Click Save on the canvas.
Property Description
Priority The mapped priority level.

^ Back to top

 

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.

  1. Drag a Find User step onto the canvas.
  2. Double-click the step to open the setup screen (or move your cursor over the step and click the pencil icon).
  3. Edit the Step Label to give the step a unique label for the particular flow.
  4. Select a property to use for the user lookup:
    • Select Email and enter an email address.
    • Select Target Name and enter a target name.
    • Select Web Login and enter a web login ID.
    • Select Custom and enter a custom user property (using plain text or a constant) that you want to find a value for into the Custom Property Name field, and a value (using plain text or an output from the previous step) that you want to find a match for into the Custom Property Value field.
  5. Click Done.
  6. Click Save on the canvas.

The Find User step uses the xMatters endpoint, which authenticates using the credentials of the user who triggered the flow.

Output Description Example
User ID UUID of the first xMatters user matching the search criteria. 25dce2c3-defe-4610-8c55-4c6edbf50496
User Target Name Target name of the first xMatters user matching the search criteria. asamara
Total User Count

The total number of users found that match the search criteria.

You could connect a custom step that checks if the value of this output is greater than 1, then connect a switch step to take a different path if that is true.

2

^ 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.

  1. Drag the step onto the canvas.
  2. Double-click the step to open the setup screen (or move your cursor over the step and click the pencil icon).
  3. Edit the Step Label to give the step a unique label for the particular flow (for example, "Find ServiceDesk ID").
  4. Enter the target name or ID of the xMatters user you want to find the value for in the User ID input.
  5. Enter the name of the custom user property you want to find the value for into the Property Name field.
    • If you're repeatedly looking up the value of the same property, you can store the name of the field in a constant, then drag the constant into the input. This helps prevent the flow from tripping over a typo. Otherwise, you can enter plain text or use an existing output from another step in the input field.
  6. Click OK.
  7. Click Save on the canvas.

The Find User Property Value step uses the xMatters endpoint, which authenticates using the credentials of the user who triggered the flow.

Output Description Example
Property Value Value of the specified custom field or attribute for the specified xMatters user. marymc3

^ Back to top

 

Create xMatters Conference step

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

  1. In the Tools tab, under , drag the Create Conference step onto the canvas and connect it to your flow.
  2. Double-click the step to open the setup screen (or move your cursor over the step and click the pencil icon).
  3. Enter a label for the step to identify it in your flow.
  4. Enter the conference bridge name to identify the conference bridge to participants and in xMatters.
  5. Add an optional description.
  6. The incident ID associates the step to an incident as one of the collaboration channels. If you have the Initiate Incident step in your flow, you can add the Incident ID variable. To do this, click the Initiate Incident tab and drag the Incident ID variable under the Incident ID section.
  7. Once you're happy with the settings, click Done.
  8. Click Save on the canvas.

Property Description
Toll-Free Number The HTTP response code received from the target system.
Toll Number The toll number that can be used to dial in to the conference.
Bridge ID The conference bridge's unique identifier, or bridge number. Participants are prompted for this number when they dial in to the conference.

For more detailed information about monitoring xMatters conference bridges, see Conferences report.

^ Back to top

 

Initiate Incident step

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

  1. In the Tools tab, under xMatters, drag the Initiate Incident step onto the canvas and connect it to your flow.
  2. Double-click the step to open the setup screen (or move your cursor over the step and click the pencil icon).
  3. Enter a step label to identify it in your flow.
  4. In the Summary field, provide the most important information for responders (this also becomes the summary in the Incidents list).
  5. Add a description, including any additional details about the incident.
  6. For the incident's initial severity, enter one of MINIMAL, LOW, MEDIUM, HIGH, or CRITICAL.
  7. Add any impacted services by typing text or dragging variables into the Impacted Services field.
  8. Add an Incident ID to use when referencing, or linking other steps to the incident.

    9. If you enter an Incident ID that already exists in xMatters, no new incident will be created. If you don't enter an Incident ID, one will be automatically assigned by xMatters (for example, INC-123).

  9. Add the Incident Commander. If this field is left black, the user that initiates the flow becomes the Incident Commander by default.
  10. Once you're happy with the settings, click Done.
  11. Click Save on the canvas.

Property Description
Incident ID The ID of the incident.
Incident Commander The person assigned as the Incident Commander.
Start time The time the incident was initiated.
Status Status of the incident.
Initiated By The person who initiated the incident in xMatters.
Is New True if the incident is new; false if an incident with a matching Incident ID already exists.

^ 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.

  1. In the Tools tab, under xMatters, drag the Add Note to Incident step onto the canvas and connect it to your flow.
  2. Double-click the step to open the setup screen (or move your cursor over the step and click the pencil icon).
  3. Enter a step label to identify it in your flow.
  4. The Incident ID field identifies the incident that you want to add the note to. If you have the Initiate Incident step in your flow, you can add the Incident ID variable. To do this, click the Initiate Incident tab in the sidebar and drag the Incident ID variable under the Incident ID section.
  5. Add the content of the note by typing text or dragging variables into the Note field. Notes exceeding 1000 characters at runtime, including the values of any variables, will be truncated in the timeline.
  6. Once you're happy with the settings, click Done.
  7. Click Save on the canvas.

Property Description
Note The content of the note that was added to the incident's 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.

  1. In the Tools tab, under xMatters, drag the Add Collaboration Channel to Incident step onto the canvas and connect it to your flow.
  2. Double-click the step to open the setup screen (or move your cursor over the step and click the pencil icon).
  3. Enter a step label to identify it in your flow.
  4. The Incident ID field identifies the incident that you want to add the collaboration channel to. If you have the Initiate Incident step in your flow, you can add the Incident ID variable. To do this, click the Initiate Incident tab in the sidebar and drag the Incident ID variable under the Incident ID section.
  5. Add the Channel Name, Channel URL, and Collaboration Description by typing text or dragging variables into the fields. (This is what is displayed in the xMatters Incident Console.)
  6. Once you're happy with the settings, click Done.
  7. Click Save on the canvas.

^ 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.

  1. In the Tools tab, under xMatters, drag the Map Incident Severity step onto the canvas and connect it to your flow.
  2. Double-click the step to open the setup screen (or move your cursor over the step and click the pencil icon).
  3. Enter a step label to identify it in your flow.
  4. Identify the Input Parameter from the external system whose values you'd like to map to xMatters severity levels.
  5. Select the Default Severity level to use if the runtime value of the input parameter does not match one of the values mapped for each xMatters severity level.
  6. Specify which values of the input parameter map to each xMatters severity level (Critical, High, Medium, Low, and Minimal).
    • You can map multiple levels to a severity level by entering each value on a new line.
  7. Under Severity Mapping Rules, select if you'd like either, or both, rules to apply:
    • Allow Partial Matches: If selected, the values mapped to each xMatters severity level can be contained in the runtime value of the input parameter. For example, in the screenshot below, if the runtime value of the input parameter is "1-Maximum", then a "Critical" severity level is assigned as the output of the step (because "Maximum" is defined as one of the values that maps to the Critical severity level, and it is contained in the input parameter value).
    • Case Sensitive: If selected, severity mappings consider letter case. In the example below, a runtime value of "p1" for the input parameter would not map to the Critical severity level (because "p1" and "P1" are not considered a match) and the default severity level "Medium" would be assigned as the output of the step.

  1. Once you're happy with the settings, click Done.
  2. Click Save on the canvas.
Property Description
Severity The mapped severity level.

^ 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.

  1. In the Tools tab, go to the xMatters section and drag the Add Change Record step onto the canvas and connect it to your flow.
  2. Double-click the step to open the setup screen (or move your cursor over the step and click the pencil icon).
  3. Enter a step label to identify it in your flow.
  4. On the Setup tab, fill in the following required fields:
    • Change Type: The change type that best fits the change that occurred in the external system. The available options are:
      • SOURCE_CODE_COMMIT
      • DEPLOY
      • ORCHESTRATION
      • FEATURE_TOGGLE
      • MANUAL
      • OTHER
    • Source: The name of the external source application where the change took place. This is usually an automation tool or version control system.
    • Summary: A short summary describing the change.
  5. You can also fill in the following optional fields:
    • Associated Service: An xMatters service that is impacted by the change. If you leave this field blank, the change record applies globally.
    • External Change ID: A unique identifier or name for the change in the source (e.g., revision ID or feature toggle label).
    • Timestamp: The date and time the change occurred in the source in UTC format. If you leave this field blank, the timestamp will be filled with the date and time xMatters received the change record.
    • Changed By: The name of the user that made the change in the external source application.
    • Details: Additional information about the change that can be written in any format (e.g., JSON, plain text).
  6. Click Done.
  7. Click Save on the canvas.

Property Description
Change UUID Unique ID of the change in xMatters.

^ 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.

  1. Drag the callable flow step from the palette onto the canvas (available from Tools > Callable Flows) and connect it to your flow.
  2. Double-click the step to open its configuration screen (or select it and click the pencil icon).
  3. On the Setup tab, fill in the step inputs using text, outputs from previous steps, trigger properties, or a combination of these.
    • This information is available as outputs of the callable trigger that can be used by steps in the flow connected to the trigger.

Typically, a callable flow step is initially configured when its associated callable trigger is added to the canvas.

If you want to edit its configuration, you can click Open Step Configuration in the associated trigger, or click Edit from the callable flow step's settings menu (the gear icon) on the Tools tab of the palette.

As the owner of a callable flow step, you can specify who the step is shared with and what permission levels they have.

  1. Click Edit from the callable flow step's settings menu (the gear icon) on the Tools tab of the palette.
  2. Click Usage Permissions.

For more information, see Share steps and libraries.

  1. Click Edit from the callable flow step's settings menu (the gear icon) on the Tools tab of the palette.
  2. Click the Usage tab to view a list of locations (Canvas > Trigger Name) where the callable flow step is used.
    • The Usage tab only appears on a callable flow step's configuration screen when the step is used on one or more canvas in the workflow.

You can also view a Usage list on the Settings tab of the callable flow step's associated trigger. Click the info ('i') icon for the callable flow step on the Tools tab of the palette to view the Canvas > Trigger Name of its related flow.

Property Description
Request ID The unique identifier (UUID) of the request that initiated the trigger.

Callable flow steps do not currently return any information from the flow they call, apart from the ID of the request that initiated the callable flow trigger.

^ Back to top