Flow tools

1. Drag a switch step onto the canvas.
2. Double-click the step to open the setup screen (or select it 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. 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 webhook step onto the canvas and connect it to your flow.
2. Double-click the step to open the setup screen (or hover 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:

• 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 select it 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. See the guidelines on setting recipients and properties for details.

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

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 types 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 types to target for notification:

Set device types using values from outputs or constants

You can specify a comma-separated list of device types 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 type (you can see a list of the available device types when you select the next option, to pick from a list of device types).

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.

1. Drag a Get Events step onto the canvas.
2. Double-click the step to open the setup screen (or select it 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 select it 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 select it 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 select it 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.