Create and manage workflows
The Workflows tab allows you to create and manage workflows, including enabling and deleting workflows, setting editor permissions, creating flows in Flow Designer, designing forms and messages, and setting up properties, responses, and scenarios.
Click the Editable filter to view the workflows you have access to. Click All to display a list of all the workflows in your company, and to change the order their messages are displayed in on the Messaging tab. If you're a Company Supervisor, click Editable to see the workflows you have specific editor permissions for (either set in Editor Permissions or because you created or imported it); click All to see and edit all workflows.
Different types of workflows are represented with different icons on the Workflows tab. There are three main types of icons that distinguish these different kinds of workflows:
|The xMatters icon represents custom workflows created or imported into xMatters, including packaged custom workflows installed from a workflow template.|
|Application-specific icons represent built-in workflows, including those that have been converted to custom workflows.|
|Workflows built using the generic webhook built-in workflow, which allows you to integrate with any application or tool capable of sending an HTTP post to xMatters.|
Ready to get started? If you're looking to integrate with a specific third-party tool, check the available workflow templates for built-in or packaged workflows that you can install into your xMatters deployment.
If you don't see what you're looking for, you can design a workflow from scratch to customize your incident resolution process by building your own flows, forms, properties, messages, and responses.
- Click Create.
- From the drop-down menu, select Explore templates.
For more information about installing built-in or packaged custom workflows, see Workflow Templates.
- Click Create.
- Select Create Custom Workflow.
- In the Create Workflow dialog window, specify a Name and optional Description.
- Click Create.
Congratulations, you've taken the first step in creating a custom workflow! But what do you do next? See the Custom workflow guide.
You can export core workflow data for reuse in another xMatters instance, saving time and improving accuracy. For example, you might export a workflow from a test environment to a production environment. You can even share your workflows with people in other organizations or post them to the xMatters Community.
If you downloaded a template for a pre-configured custom workflow, you'll need to import it into your xMatters environment.
- Click Import.
- Click the Browse to select your workflow link and select your workflow zip file. Alternatively, you can drop your file on the Import Workflow dialog box.
- The Import Workflow dialog box displays the file to import. You can click the 'X' next to the workflow to remove the file.
- Click Import.
- If you import a workflow with a name that is already in use, xMatters requires that you give the workflow a new name before continuing.
- Any messages about the import process appear on the Import Logs tab (for example, if you have languages in your instance that aren't configured in the workflow).
- Click Close.
Some things to keep in mind after you import a workflow:
- Imported workflows and their related forms have the same deployment status as when they were exported.
- You are the only one with editor permissions, regardless of what permissions the workflow had when it was exported.
- Any steps used on a flow canvas are imported. If the version of a step used on the canvas is not the base version (v1), both the used version and the base version are imported as separate steps in the palette.
- HTTP triggers and custom steps are imported in an In Development state. They are owned by you and not shared with any other users. If a step of the same name already exists in your instance, you'll end up with two steps with that name. You might want to look at the Usage tab for the steps and rename them to something unique.
- The trigger ID used in the email address of an email trigger is set to a unique value for the imported flow. Update the trigger ID, if needed, and make sure you use the new email address to target the new email trigger.
- Any libraries you import are owned by you. If you already own a library with the same name, the name of imported library is appended with a number (-1, -2, etc.). The reference to the library in any scripts still work because the script calls the library by the reference name set in the step. However, you might want to rename the library to something unique.
- If the workflow has existing integrations created using the Integration Builder, these appear on the flow canvas for the associated form (except for inbound Run a Script integrations, which appear on their own canvas). You can leave them as-is and they'll continue to function. If you need to edit them, you can use either the Integration Builder or Flow Designer. We recommend reviewing your integrations and to see if you want to convert them into more flexible, observable flows — refer to our guides for converting inbound and outbound integrations.
The export option is available only for custom workflows.
To export a workflow:
- Do one of the following:
- On the Workflows tab, click the gear icon for the custom workflow you want to export, then select Export.
- When viewing a custom workflow, click the gear icon at the top and select Export.
- Note the download location, which is typically your browser's default Downloads folder.
When you export a workflow, it's saved as a zip file with the name of the exported workflow for the filename (spaces and special characters are removed). For example, a workflow named Runway Response would have an export filename of RunwayResponse.zip.
Exports include the following workflow data:
- Layout (position of all sections)
- Properties (all settings)
- Conference bridges (all settings)
- Attachments (section only)
- Handling (all settings)
- Recipients (section only, but retains status of Count Responses flag)
- Device filters (section only)
- Site recipients (section only)
- Response overrides (section only)
- Any triggers, steps, and connections between steps used on the flow canvas
- Flow components, including endpoints, constants, and any libraries used by steps in the flow.
- Integration Builder integrations:
- Inbound integration services
- Outbound integration services
- Shared libraries
Exported workflows do not include subscription forms, scenarios, or sender override settings.
Most of the settings for workflows are accessible from the gear icon on the main Workflows screen. Built-in workflows include a few additional settings.
By default, new workflows are not enabled and do not appear on the Messaging tab until the workflow and at least one of its forms is deployed to the web user interface.
You can enable or disable a workflow by clicking its toggle on the Workflows tab.
Initially, only company supervisors and the user who creates or imports a workflow can edit it. Workflow editor permissions can be granted on a per-workflow basis to all users, individual users, specific groups, or roles.
Users that do not have permission to access a workflow can see it on the Workflows tab, but they are not able to enable or disable the workflow, modify it, access its settings, or delete it.
To configure workflow editor permissions:
- Do one of the following:
- On the Workflows tab, click the gear icon beside the name and select Editor Permissions.
- When viewing a workflow, click the gear icon at the top and select Editor Permissions.
- Search for the name of a user, group, or role and click it when it appears in the drop-down list results.
- Type two spaces to return all possible values.
- If you want to remove a user, group, or role, click its X icon.
- To allow access to all users with permission to edit workflows, select the All Users option.
- Click Save Changes.
Notification flood control is a company-level setting that can be enabled for individual workflows (and inbound integrations). Notification flood control prevents users from being flooded with multiple notifications from a workflow when they've already been notified about an incident and are working on resolving the issue. You can use this feature to control the maximum number of notifications that are delivered to specific device types during a defined period, such as: no more than two messages every ten minutes to SMS and mobile app devices.
By default, notification flood control is disabled for all workflows. You must enable notification flood control for individual workflows.
To enable notification flood control for a workflow:
Do one of the following:
- On the Workflows tab, click the gear icon beside the name and select Notification Flood Control.
- When viewing a workflow, click the gear icon at the top and select Notification Flood Control.
For more information about notification flood control for inbound integrations, see Enable notification flood control for inbound integrations.
To delete a workflow, do one of the following:
- On the Workflows tab, click the gear icon beside the name and select Delete.
- When viewing a workflow, click the gear icon at the top and select Delete.
You can only change the order of workflows from the All workflows view. The order of workflows in this view determines the order they're listed on the Messaging tab.
To change the order of the listed workflows, grab the handle icon next to its name and drag it into a new position in the list.
When you click the gear icon for a workflow, the setting are slightly different for built-in and custom workflows. Built-in workflows include the option to Convert to a Custom Workflow. They also include additional options to enable Logging and Open Activity Stream.
You can convert your built-in workflow to a custom workflow to customize it beyond what is possible with the streamlined, built-in format. Converting to a custom workflow allows you to access the features and functionality of the workflow designer, such as forms and properties, the message and response editors, and enhanced security options.
To convert a built-in workflow to a custom workflow:
- On the Workflows tab, click the gear icon for a built-in workflow and select Convert to Custom Workflow.
- You can also click the name of the built-in workflow, and then click the gear icon on the configuration page and select Convert to Custom Workflow.
- On the warning dialog window that appears, click Convert to Custom Workflow.
Converting a built-in workflow to a custom workflow is permanent. Once converted, your workflow will function exactly as the previous built-in workflow, including the same URLs and notification flood control settings.
Built-in workflows include an Activity Stream that allows you to monitor requests in the system and view the details and history of completed events. (For custom workflows the Activity Stream functions a little differently. To view the activity for a flow, check the Activity panel.)
When you create a new built-in workflow, xMatters temporarily logs the first 25 outbound or inbound requests for the workflow. After that, it only logs failed requests to help in troubleshooting.
To view the Activity Stream for a built-in workflow:
- On the Workflows tab, click the gear icon for a built-in workflow and select Open Activity Stream.
- You can also click the name of the built-in workflow, and then click the gear icon on the configuration page and select Open Activity Stream.
- Select or clear the check boxes to view or hide log entries for the various inbound and outbound integrations, then select an item in the Activity Stream to view its details.
For more information about interpreting the request log in the Activity Stream, see Interpreting a request log.
On the Workflows tab, click the gear icon for a built-in workflow and select or clear Logging.
- You can also click the name of the built-in workflow, and then click the gear icon on the configuration page and select or clear Logging.
xMatters displays a message that logging is now enabled for the workflow and that the next 25 requests will be logged, or that only failed requests will be logged. If new logs arrive while you're viewing a request's details, click the Refresh button to refresh the list of requests.