Flow tools

Tools are steps that evaluate the information coming through the flow and use it to decide what action to take next.

Tools help you create richer, more refined flows adapted to your use cases. Switch steps split a flow onto different paths (for example, use path A if the event is customer impacting but use path B if it's not). The xMatters Create Event step creates a new event in the middle of a flow, using information from the previous steps to populate the notification details and targeted recipients. You can even combine them to only create an xMatters event when a property has a certain value.

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.

ClosedConfigure a switch step
  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.

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

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

ClosedSet up an xMatters Create Event step

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

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.

  1. After you're finished setting up your event properties, click Done.
  2. Click Save on the canvas.
ClosedGuidelines for recipient and property fields
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.

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:

ClosedxMatters Create Event step output details
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