Design a flow

Access it from the Workflow Builder:

1. Click the Workflows tab.
2. If it's not already selected, click Workflows from the menu on the left.
3. Click the name of the workflow that you want to build flows for and click the Flow Designer tab.
4. Click the name of the form you want to create or edit flows for (or Create a flow if the form doesn't have any flows yet).

Access it from within a workflow:

1. If you're already in the workflow, click the Flow Designer tab.
2. Click the name of the form you want to create or edit flows for (or Create a flow if the form doesn't have any flows yet).

After you decide on the trigger type, drag it from the palette to the canvas. You can use HTTP and Email triggers multiple times on a canvas. Each Event Activity trigger can only be used once, so when you drag one of these triggers onto the canvas, it disappears from the palette; when you delete it from the canvas, it reappears in the palette so it's available for you to use in future. If you've already built an outbound integration with the Integration Builder that uses the trigger, it appears on the canvas.

1. Drag the trigger from the palette onto the canvas.
   • For HTTP triggers, you can filter by triggers you own, triggers others have shared with you, or all triggers you have permission to use.
2. Double-click the trigger icon to display information about the trigger and its properties.
3. Click the Enabled toggle to enable or disable the trigger. When you disable a trigger, you disable the connected flow, which you might want to do until you've built it out.

For many triggers, that's all you need to do. To use the Responses trigger in our scenario, you might need a bit more setup.

Flows are enabled by default, but you can disable them by disabling the trigger. For example, you might want to disable a flow if you're doing some system testing, diagnosing a runtime issue, or fleshing out a new workflow.

1. Double-click the trigger to open its dialog box.
2. Click the Enabled toggle to turn the flow on or off.

Whatever step you're adding, the basics are the same, though the setup required and any prerequisites depend on the particular step. In many cases, you simply need to drag a step onto the canvas, connect it to a previous step, and configure any required inputs to get started.

For some steps, you'll need to know the endpoint you want to send requests to (either to post to or get information from).

1. Locate the step in the palette in either in the Apps or Custom tabs.
   • For custom steps, you can filter by steps you own, steps others have shared with you, or all steps you have permission to use.
2. Drag the step from the palette onto the canvas.
   • To use a different version of a step, click the version icon () beside the step on the palette and drag the version you want to use onto the canvas.
3. Drag a connector from the output port of the previous step in a flow to the input port of the step you're adding.
   • Connect the step before configuring it to make sure you have access to all the event properties and outputs from previous steps when setting up your inputs.
   • If you're connecting multiple paths to the input port of a step, only constants and the outputs of individual steps common to all joined flow paths are available as inputs to this step.

If the built-in apps don't meet your needs, you can design custom steps to use in your flows.

The setup required varies depending on the step you're adding, but how you configure the step is the same. When configuring inputs, you can include text, outputs from previous steps, or a combination of both. These outputs appear in the panel on the right side of the step setup screen — simply drag one from the panel to an input field. For longer or more complicated flows with a large number of steps and variables, use the Search field at the top of the panel to quickly find the outputs you need.

We provide instructions on using the built-in steps in the Apps panel; for information on any custom steps, contact the person in your organization who created them.

1. Double-click the step to open its configuration screen (or select it and click the pencil icon).
2. Change the Step Label if it makes sense for your flow. For example, if you have a step to post to a specific channel and the channel name is hard-coded in a step input, you might want to the label to read "Post to antares-team-chat".
3. Fill in the required inputs and any of the optional inputs you want to use in the flow of information. You do this by adding hard-coded text or by mapping output variables from the event, trigger, or previous steps, which appear on the right. You can also copy a variable from one field and paste it in another. The values of these variables are determined at runtime.

4. Click OK to close the setup screen, then click Save at the top of Flow Designer.

Some things to keep in mind:

• If you add an output variable to an input field, Flow Designer doesn't know the value of the variable until runtime. This means it can only evaluate any configured minimums, maximums, or pattern validation at runtime. For example, you won't get a validation error if you map a Detailed Description variable into a Summary input field with a maximum length of 150 characters. However, when the flow is triggered, it throws an error if the value passed is 2000 characters long. If this happens, the errors shows up in the Activity panel.
• If you connected multiple paths to the input port of a step, only constants and the outputs of individual steps common to all joined flow paths are available as inputs to this step. Event properties are available as inputs when the flow uses only Event activity triggers.
• The value of the inputs you configure in this step might become outputs that you can use in steps further along the flow.

Some steps can either run in the cloud or use the xMatters Agent to run behind your corporate firewall. Running on an agent allows a step to update and retrieve information from systems that reside behind the firewall. If a step is configured to allow both locations, you need to select where you want this instance to run and, when it's set to run on an agent, you need to select one or more agents for it to use.

1. Click the Run Location tab. If you don't see this tab, it means the step is only configured to run in the cloud.
2. Select the location where you want this step to run: Cloud or xMatters Agent.
3. If you set it to xMatters Agent, select one or more agents from the list of available agents.
   • To select an agent from the list, you must be a registered user of the agent and it must be version 1.4.1 or later.
   • If you don't have any agents configured, click Add an xMatters Agent to go to the Agents page, which has instructions for installing the agent.

4. Click OK. If you're done configuring the step, close it and click Save on the canvas.

Some steps require that you set an endpoint (for example, to send event information to a chat channel). You can use an endpoint that's already set up for the workflow or you can add one while configuring the step (which you can reuse in other steps).

1. Click the Endpoint tab.
   • If you don't see the Endpoint tab, it means the Include Endpoint option wasn't selected when the custom step was created.
2. Select an existing endpoint from the list, or click Create New Endpoint to set up a new endpoint. You'll only see endpoints that match the authentication type that was allowed when the step was created.
3. If you create a new endpoint, a dialog box appears where you configure your new endpoint. You might not be able to change the authentication type; this is defined when the step is designed, and many specify a particular authentication type.
   • If you create a new endpoint, click Save Changes then Close on the Endpoints dialog box when you're done, which returns you to the step setup.

4. Click OK to close the step setup screen, then click Save on the canvas.

Think of a switch step like the switch on a set of railway tracks. It determines what route the train — or flow — takes based on event properties, trigger outputs, constants, or outputs of previous steps in the flow. For example, a flow could be routed based on a severity property ("Critical" goes one way, "High" another, everything else follows a third, default path) or a customer impacting property ("Yes" follows one route, "No" another).

In our MIM scenario, we split the flow based on the customer_impacting event property. A value of Yes creates a Statuspage incident then posts to our NOC dashboard. Any other value just posts to the dashboard.

To configure a switch step:

1. Double-click the switch step to open the setup screen (or select it and click the pencil icon).
2. 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).
3. Select the property that determines which path the flow takes. This list is populated with event and trigger properties, outputs from any previous steps, and constants.
4. Click Done.
5. 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 the property comes 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).
6. Set up the flows you want to follow for each path, or identify a merge point after which the paths follow the same series of steps.

As you're building out your flow, you might decide you need to create an xMatters event. Maybe you're triggering the flow using email and you want to initiate an event targeting the email recipient. Or maybe you want to kick off a new notification with different recipients depending on the value of that customer impacting switch step. Or you might have an "All Hands On Deck" response that creates a new notification targeting a wider audience. The xMatters Create Event step lets you create a new event and send new notifications at any point in your flow. And you can pass information from any previous steps into the event.

In our MIM scenario, we split the flow based on the customer_impacting event property. Now, not only does a Yes create a Statuspage incident and post to our NOC dashboard, it also creates a new event with all the details about the issue that we send to our "Customer Care" group.

To configure an xMatters Event step:

1. After dragging the step onto the canvas, double-click the xMatters Create Event step to open the setup screen (or select it and click the pencil icon).
2. Select the form you want to create the event for.
   • The setup screen displays the properties in the target form, letting you populate these inputs with outputs from the trigger and any other previous steps.
3. Enter a label for the step (for example, if the event is initiated based on a "Launch Major Incident" response, you might use that as the step label).
4. Specify the recipients using their xMatters target names. You can hard-code a target name or map the output of a previous step into the recipients field. For details on the various ways to set recipients, see Flow tools.
5. Fill in the form properties using text, outputs from previous steps, or a mixture of both. Depending on the type of property and how it was set up, you might need to enter it in a specific way.
6. Click Done.
7. Click Save on the canvas.