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 event properties, trigger outputs, constants, or outputs of previous steps in the flow.
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.

- Drag a switch step onto the canvas.
- Double-click the step to open the setup screen (or select it and click the pencil icon).
- 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).
- 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. For example, in our priority scenario, you could use the priority output of a trigger as the switch property.
- Click Done.
- 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 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).
- Set up the flows you want each path to follow.
- 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 an event property or the output of an HTTP trigger or 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.
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 is run, the values specified for that flow are passed into the Merge step outputs.

- From the Utilities section of the Tools tab, drag a merge step onto the canvas and connect the flows you want to combine.
- Double-click the step to open the setup screen (or hover 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.
- On the Settings tab, enter a label for the step — this appears on the canvas to help identify the purpose of the step.
- For each output you want to make available to steps downstream, click Add Step Output and enter a name for the output.
- 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.
- 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.
- Repeat the output definition on the tabs for each of the remaining connected flows.
- After you define the outputs for each of the incoming flows, click Save.
- Click Save on the canvas.
When the flow is run, the values specified for whichever flow initiates the step are passed into the outputs.

- To delete an output, click the x beside the output on the Settings tab.
- Click Delete on the confirmation dialog that appears to let you know that this step might impact the flow.
- 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 event 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 Event Priority to N/A, since no event is created in this flow.
Webhook step
The webhook steps lets you send information from the flow to any system capable of receiving an HTTP POST request.

- From the Utilities section of the Tools tab, drag a webhook step onto the canvas and connect it to your flow.
- Double-click the step to open the setup screen (or hover and click the pencil icon).
- 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").
- 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.
- 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.
- Select the content type to tell the receiving system how to parse the payload (for example, application/json or application/x-www-form-urlencoded).
- 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.
- Click OK.
- Click Save on the canvas.

Property | Description | Example |
Response Code | The HTTP response code received from the target system. | 200 |
xMatters steps
The xMatters steps let you do things in your xMatters instance, like create an event, find a user, or add an xMatters conference bridge.
xMatters Create Event
The xMatters Create Event step lets you create a new event at any point in the flow in response to previous steps, using information from those steps to populate event details and targeted recipients. You can target either the form the flow belongs to or another form in the workflow.
For example, you might want to create a new event:
- In response to an email trigger, with the addressees in the email becoming the recipients of the event notification.
- Based on an "Emergency alert - Location" switch step, creating events targeting different groups with different instructions if the location is Los Angeles versus London.
- After an HTTP trigger, populating the event details using the values of properties in the request, including setting the recipients from an "Assignment Group" output on the trigger.
- Create an event using a different form that targets your customer support team after a "Customer Impacting" switch step.

Before using the Create Event step, there are a few things to keep in mind:
- 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 event.
How to set up a Create Event step:
- Drag an xMatters Create Event step onto the canvas.
- Double-click the step to open the setup screen (or select it and click the pencil icon).
- Select the form to use for the event (the form description, if it exists, appears below the name) and click Apply.
- You can't switch the form used by the Create Event 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 Event step.
- Update the Step Label to reflect the purpose of the event. For example, if the step follows a "Customer impacting=true" path on a switch step, you might name it "Create Customer Care Event".
- Fill in the recipients and event properties using text, outputs from previous steps, trigger properties, constants, or a combination. See the guidelines on setting recipients and properties for details.
- If this create event 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.
- Use the Devices tab to set which device types to target for notification (for example, 'Work Phone' and 'Work Email').
- 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 events. You can also modify the caller ID and display name associated with this event.
- After you've finished configuring the step, click Done.
- Click Save on the canvas.

Setting the Incident ID
If there is an Initiate Incident step preceding the Create Event step, use the "Incident ID" output from that step in the Incident ID field. This associates the notification and the notified resolvers with the incident in the Incident Console.
Setting recipients
Specify recipients using the xMatters target name of the user, group, or device you want to target. For example, this can include mmcbride, AntaresDB-Support, or mmcbride|Work Email.
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 event 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 event step.
Setting properties
- Use text, constants, outputs from previous steps, or a combination to populate the event 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 Create Event 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 Create Event 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 Event 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 Create Event 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 that 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 Event step. It gives you access to the devices settings configured for the form associated with the Create Event 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 Create Event step. These settings allow you to control how the event behaves and how recipients interact with voice notifications (for example, you can specify the event'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 event.
When you add a Create Event 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 Create Event 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 Event > 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 event handling setting:

Property | Description | Example |
event.id | The unique identifier (UUID) of the event. | e930e32d-b863-4c55-a528-1d2829e3690e |
event.eventId | ID assigned to this event by xMatters and used to track its progress through the system. (Also the number used to reference this event in the Events and Tracking reports.) | 889003 |
event.status | The current status of the event. | ACTIVE |
event.created | Date and time the event 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 event. | integrationUser |
conference.bridgeNumber | The ID number of the conference associated with the event. This is only available if there is a conference bridge associated with the form. |
74778487 |
Get Events
Use the Get Events step to get the events IDs of the 50 most recent events in xMatters that match search criteria such as status, priority, or the value of an event property. You can combine search criteria to narrow your results or add multiple status or priority values to broaden the search.

- Drag a Get Events step onto the canvas.
- Double-click the step to open the setup screen (or select it and click the pencil icon).
- Edit the Step Label to give the step a unique label for the particular flow.
- Fill in the search criteria to find the events 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 events by their status (active, suspended, or terminated). You can include multiple, comma-separated values to find events matching any of the statuses.
- Priority: Search for event by their priority (low, medium, or high). You can include multiple, comma-separated values to find events matching any of the priorities.
- Property Name, Property Value, and Exact Property Value Match: Use these fields together to find events 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 events with a matching property name are returned.
- Plan Name: Search for events created by forms in a specified plan. You can include multiple, comma-separated values to find events created by any of the listed plans.
- Form Name: Search for events created by the specified form. You can include multiple, comma-separated values to find events created by any of the listed forms.
- Click OK.
- Click Save on the canvas.
Here's an example search that would return all active events 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 |
Event IDs | A comma-separated list of event IDs for up to 50 events that match the search criteria. These IDs are the same as the IDs that identify the event in the web user interface (for example, in the Tracking report). | 18960003, 18964000, 18964002 |
Number of Event IDs Returned | The number of matching event IDs returned in the Event IDs output. | 50 |
Total Event Count | The total number of events found that match the search criteria. | 57 |
Terminate Events
Use the Terminate Events step to terminate up to 50 events, using their event IDs. You can use the Get Events step earlier in the flow to retrieve the IDs for the events you want to terminate. When you terminate events in xMatters, it stops all processing, including canceling any active notifications, and cannot be resumed.
The Terminate Events step has no outputs.

- Drag a Terminate Events step onto the canvas and connect it to a previous step that provides the IDs of the events you want to terminate in an output (for example, a Get Events step).
- Double-click the step to open the setup screen (or select it and click the pencil icon).
- Edit the Step Label to give the step a unique label for the particular flow.
- Drag the output that provides the IDs of the events you want terminate into the Event IDs input.
- Click OK.
- Click Save on the canvas.
Find User
Use the Find User step to look up the ID and target name of an xMatters user based on the value of a custom field or attribute. 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 Event step.
The outputs provide the unique identifier (UUID) and target name of the first user that matches the search criteria.

- Drag a Find User step onto the canvas.
- Double-click the step to open the setup screen (or select it and click the pencil icon).
- Edit the Step Label to give the step a unique label for the particular flow.
- Enter the name of the custom field or attribute you want to find the value for into the Property Name field.
- You can enter plain text in the input field, but you could also use a constant to store the name of the field you want to look for to help prevent the flow from tripping over a typo.
- Enter the value you want to find a match for in the Property Value field.
- You can use plain text in the input field or use an output from a previous step in the flow. For example, you could set up a "user property value" output on an HTTP trigger that maps to a property in the HTTP request.
- Click OK.
- 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 |
Find User Property Value
Use the Find User Property Value step to look up the value of a custom field or attribute 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.

- Drag the step onto the canvas.
- Double-click the step to open the setup screen (or select it and click the pencil icon).
- Edit the Step Label to give the step a unique label for the particular flow (for example, "Find ServiceDesk ID").
- Enter the target name or ID of the xMatters user you want to find the value for in the User ID input.
- Enter the name of the custom field or attribute 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.
- Click OK.
- 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 |
Create xMatters Conference step
The Create xMatters Conference step allows you to initiate an xMatters hosted conference bridge in your flow.
This is part of the adaptive incident management toolset and is not yet available in all instances.

- In the Tools tab, under , drag the Create Conference step onto the canvas and connect it to your flow.
- Double-click the step to open the setup screen (or hover and click the pencil icon).
- Enter a label for the step to identify it in your flow.
- Enter the conference bridge name to identify the conference bridge to participants and in xMatters.
- Add an optional description.
- 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.
- Once you're happy with the settings, click Done.
- 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.
Initiate Incident step
This is part of the adaptive incident management toolset and is not yet available in all instances.
The Initiate Incident step allows you to create an incident. Use this step to define the basic details of the incident (for example, summary and severity).

- In the Tools tab, under xMatters, drag the Initiate Incident step onto the canvas and connect it to your flow.
- Double-click the step to open the setup screen (or hover and click the pencil icon).
- Enter a step label to identify it in your flow.
- Enter a subject to summarize the most important information for responders, this also becomes the summary in the Incidents list.
- Add a description, including any additional details about the incident.
- Enter either LOW, MEDIUM, or HIGH for the incident's severity.
- Add an Incident ID to use when referencing, or linking other steps to the incident.
- Add the incident owner. If an owner isn't assigned, the user that initiates the flow becomes the owner by default.
- Once you're happy with the settings, click Done.
- Click Save on the canvas.
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).