Flow tools

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 event 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 event and trigger properties, outputs from any previous steps, and constants. 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 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).
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 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.

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

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.

8. Click OK.
9. Click Save on the canvas.

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

• To use this step, you require a messaging form. The Create Event 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 event.

How to set up a Create Event step:

1. Drag an xMatters Create Event 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 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.
4. 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".
5. Fill in the recipients and event 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 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.

6. Use the Devices tab to set which device types to target for notification (for example, 'Work Phone' and 'Work Email').
7. 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.
8. After you've finished configuring the step, click Done.
9. 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 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 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:

1. Drag a Get Events 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 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.
5. Click OK.
6. 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):

1. 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).

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. Drag the output that provides the IDs of the events you want terminate into the Event IDs input.

5. Click OK.
6. Click Save on the canvas.

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. 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.
5. 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.
6. Click OK.
7. 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.

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

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.

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

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.

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.

    

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.

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.

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.

8. Once you're happy with the settings, click Done.
9. Click Save on the canvas.