The information in this article is the intellectual property of xMatters and is intended only for use with xMatters products by xMatters customers and their employees. Further, this intellectual property is proprietary and must not be reused or resold.

You don’t need to be a developer to integrate other tools with xMatters and build automated toolchains. xMatters makes building and managing incident management workflows accessible to everyone, whether you think ‘code’ is a four-letter word or you dream in functions and methods.

It's all about workflows

An xMatters workflow lets you tailor your communications and automated actions based on any business process, emergency response, or technology, helping you respond more quickly, accurately, safely, profitably, and reliably.

The workflow holds all the bits and pieces that get information into xMatters, perform automated actions and send notifications based on that information, and enrich and pass that information on other systems. This includes automated flows in Flow Designer, available properties that hold information, message templates for notifications, possible response options, and triggers that determine what happens when something changes.

You can use one of our pre-made workflows, customize one of those workflows, or go completely custom, building a workflow from scratch.

So how do I get started?

With so many options, you might be wondering where to begin: Workflow templates are a good place to start.

These are templates we created for many common applications. They let you quickly set up an integration to the tools you use every day and come configured with common properties from the source application, message layouts notifications, and defined responses.

If you don’t need to customize any of that, all you need to do is install and configure an integration from the template.

Use the Workflow Templates screen to access a directory of pre-built templates you can install to quickly integrate with other systems. Templates for different products have different installation methods: some are built right into xMatters and have a streamlined configuration process, while others are available from our website as downloadable packages that you can import.

The first thing you see when you click on a workflow template is the Create Workflow screen – it helps guide you through the installation process, with instructions specific to the product you select and helpful links to where you can get more detailed information to help you get set up:

For even quicker access to workflow templates, you can add the widget to your Communication Center dashboard:

All the workflows

The xMatters website also has a comprehensive list of applications xMatters integrates with, including ServiceNow and Jira.

If your application isn’t on the list, be sure to check out the experimental integrations over at xM Labs on GitHub.

Tips & Tricks

• Use an existing workflow in your system as a base to build on by exporting it and then importing it into the target system.
• Add the Workflows Templates widget to your dashboard for even quicker access.
• Control who can make changes to the workflow by setting the Editor Permissions – you can add users, groups, or roles.

Additional resources

• Explore all the integrations on our website.
• Get hands-on setting up one of the Workflow Templates integrations in our Intros to Integrations workshops.
• Watch how to use workflow templates - or, better yet, check out the entire Integrations and Workflows playlist.
• Get instructions on installing and managing workflows.

Tl;dr…I just want to send notifications

We've designed a workflow just for you: Send Alerts.

This pre-built workflow template helps you start notifying users and groups with minimal setup. It lets you create an alert and send notifications simply by sending an email or HTTP request to xMatters.

Use it to quickly send test messages, learn how workflows work, as a way of integrating systems with rudimentary integration options, and as a starting point for creating your own workflows. To get up to speed quickly, see our Send Alerts workflow guide.

But you can add email integration to any workflow.

Send an email, trigger an automated workflow

Do you want to send an email to notify your executive stakeholders? Or use an email from a 3rd party system to notify your on-call resolvers about errors coming from a monitoring tool?

The email trigger lets you do that – and more. Combined with the flexibility of Flow Designer, you can use an email to kick off automated flows as well as send notifications. By using email-initiated flows, you can automate the process to notify your teams, as well as invite them to a channel in a collaboration tool like Slack or Microsoft Teams.

To add the email trigger, open the workflow with the form you want to use to send notifications based on the email, or that relates to the automated actions you want the email to trigger. For example, if you want an email from an Incident Commander to update stakeholders and create a status page, you might add that trigger to an incident response flow.

We walk through the 3 steps of setting up an email integration to notify the email recipients in Example: Use an email to trigger a flow, but the basic steps are:

1. Drop an email trigger on the related canvas and set the method:
   • Send from any email: Any email from any source can trigger the flow. You must specify the user whose credentials are used to process the flow.
   • Send from an xMatters device: Only an email address associated with the email device of an xMatters user can trigger the flow. This is more secure since it checks that the email belongs to a valid device of a valid user.

2. Connect a Create Event step to the trigger and use the email.recipients output from the Email trigger to populate the Recipients input.
   • Of course, with the flexibility of Flow Designer, you don’t have to create an event – you could trigger automated steps without notifying anyone.
3. Test it. Okay, this optional, but it’s always a good idea to check things are working before they’re not.

Tips & Tricks

• Make sure you connect a step to the flow before you configure it – this gives you access to all the outputs of all the previous steps to use in your inputs.
• The format of the email address is <name>@<triggerID>.<hostname>. The trigger ID is unique to each email trigger, but you can replace the name with the user ID or name of a group or dynamic team. If you want to add multiple recipients, simply add the address to the email multiple times, replacing the name portion with the users or groups you want to target.

Additional info

• Check out our Easy as Pie Advanced Email Initiation walkthrough.
• Learn more about the Email trigger, HTTP trigger, and Create Event steps.
• Walk through how to make info in the email available to other steps in the flow using a custom email parsing step.

I want to turn my integrations into an automation machine!

The great power of xMatters is its ability to chain your tools together into a seamless, automated incident management engine.

To drive incident resolution and reach the pinnacle of digital service availability, you need to consider what happens next: after the monitoring system sends a ping or someone raises the alarm?

That’s where Flow Designer comes in. Flow Designer offers:

• Codeless design with built-in steps for the most requested apps to minimize the learning curve for integrated toolchains. Simply drag & drop built-in steps.
• A visual designer for at-a-glance analysis of workflows that lets you focus on incident response orchestration.
• Enhancement of your existing communication plans to extend your current process.
• A toolkit for building custom steps to support any business process.

With Flow Designer, simply drag-and-drop the steps you need to create a toolchain, connect them together, and let it rip!

Take a tour

The main areas of the Flow Designer interface are:

1. The canvas: a large central area to build your flows.
2. The palette: a sidebar that holds steps you can use in your flows.
3. The Activity panel: a panel you can expand to check on the runtime state and logs of your flows.

(Looking for more animation in your overview? Take a video tour.)

Building toolchains with Flow Designer: easy as 1-2-3…4

1. Drag the trigger you want to start your flow onto the canvas – this can be event activity such as an event status change, or it can be an HTTP or email – and then drag the steps for applications you want to include in the flow from the palette to the canvas:
   
2. Connect the steps in the order you want information to flow. For example, if you want to include a ServiceNow incident ID in your Slack channel, put the ServiceNow Create Incident step before the Create Channel step.
   
3. Configure the steps so each one has the information it needs, and point to an endpoint if needed. Keep in mind, you don't have to set each and every input: any information from previous steps in the flow is available to all of the downstream steps. Don't need the detailed event summary when creating the chat channel? No problem – just grab it when you're ready to post it to the ticket. Want to name your chat channel with the new incident ticket you just created? Take the incident ID from your "Create Incident" step and feed it into your "Create Channel" step.
   
4. Finally, test your flow! With Flow Designer's visual representation of your toolchain and the Activity panel, it's fast and easy to identify where and how to fix any configuration issues:
   

Watch how we build a basic flow: Building your first flow.

Tips & tricks

• Make sure you connect a step to the flow before you configure it – this gives you access to all the outputs of all the previous steps to use in your inputs.
• Run steps in the cloud or use the xMatters Agent to access applications behind your corporate firewall.
• Monitor the progress of your flow in the Activity panel.

Additional resources

• Join a Flow Designer workshop to learn more tips and tricks.
• Watch an example of a software rollback flow being built.
• Read details on how to use Flow Designer.

That’s nice but I eat, sleep, and breathe code

Flow Designer provides a drag-and-drop way to create automated incident resolutions toolchains. However, if you like to get your hands dirty, xMatters also provide a robust toolkit for developers.

Go custom

If you find the off-the-shelf workflows and steps don’t quite meet your application or use case, you can create a custom workflow or tailor an existing one.

You can edit the:

• Properties available to use in flows and notifications. Learn how.
• Content and appearance of notifications (for example, putting things in a table or matching your company's branding). Learn how.
• Response choices available in notifications and how they impact the event. Learn how.

And you can tweak the connected flows in Flow Designer.

xMatters REST API

If you’re a developer just itching to set up an advanced integration, this is the resource for you. The API lets you get and create information, as well as alerts. You can use the REST API to integrate with any application that can make HTTP requests.

For a comprehensive reference, check out the REST API documentation: https://help.xmatters.com/xmapi/index.html

xM Labs

xM Labs over on GitHub is a repository of experimental integrations, add-ons, custom steps, and just useful resources created by our own developers.

Tips & tricks

• Questions, contributions, or just looking for someone else who speaks the lingo? Join the discussion in the Integrations & Toolchains community forum.
• Did you know you can be notified automatically if one of your integrations experiences a problem? Just subscribe to integrations alerts — works for Flow Designer flow, too!

Additional resources

• Walk through creating a custom pirate workflow. Yes, those pirates...yarr.
• Don’t see the step you need? Create your own custom steps so you can get all the tools working together.
• Bring the entire collection of xMatters REST API endpoints into Postman so you can play with them – find the files and instructions over at xM Labs.
• Sign up for one of our developer workshops to learn more.

That’s great – but my application is secured behind a firewall

There’s a tool for that too: the xMatters Agent.

With a design focused on simple installation and ease-of-use, the xMatters Agent provides a secure means for you to integrate applications secured behind a corporate firewall into your incident management workflows.

Benefits of the xMatters Agent include:

• Easy installation – one simple command installs and connects the agent, and then you're ready to go.
• Integrations are installed using the xMatters web application, so there's no need to copy files to separate servers
• The Integration logic is created and maintained in the web interface, either in Flow Designer (for flow steps) or in the inbound or outbound integrations (for legacy integrations).
• Activity is logged in the Activity panel (for flow steps) or the Activity Stream (for legacy integrations), letting you quickly validate how the integration or step is working without having to SSH to numerous remote servers

Tips & tricks

• You can configure your custom steps to run in the cloud, on the agent, or both.
• The icon on a step gives you a quick peek into the state of the agent it’s configured to run on.

Additional resources

• Get help on using the xMatters Agent.