Slack is a popular team communication tool that helps enable real-time collaboration. This integration adds an xMatters bot to your Slack workspace that lets you:
- Look up xMatters groups, see who's on call, and instantly invite on-call members to a Slack channel using an xMatters notification to their preferred devices. Learn more
- Use slash commands to initiate incidents in xMatters right from Slack. Learn more
Do more with this integration
Incorporate this integration into your orchestrated incident resolution workflows with Flow Designer. After you create a configuration, the Flow Designer tab appears. From there, you can build your flows — add new response options, connect to other apps, or even create new xMatters alerts based on activities in the flow — enriching the information injected by this integration along the way.
Are you looking to integrate Slack into your automated toolchain using steps in Flow Designer? Check out these instructions instead.
Are you interested in a live walkthrough of the Slack integration? Take a live, online workshop led by one of our xPerts.
Get started with Slack
How you set up the integration can vary, depending on what you want to do with it. If you want to do all the things (for example, look up who's on call, invite on-call members of a group to a channel, and initiate incidents), you need xMatters bot installed in Slack and a Slack workflow in xMatters. The easiest way to get this is to install the workflow and add the bot from there. However, if you just want to get started using /slash commands to initiate incidents, you can install the app from the Slack App Directory (you can always install the workflow later and connect it to an existing bot if you want to start using the other features).
- Go to Workflow Templates on the Workflows tab and start typing "Slack" to filter the list.
- Once you find it, click its tile then click Next to get to the configuration screen.
- Give your integration a name and description.
- Enter a name to use when sending alerts. This name is used when xMatters lets someone know that they've been invited to a channel in Slack (for example, by sending them an email or pinging them in the xMatters mobile app).
- Save your workflow. After you save, the Add to Slack button appears.
- Click this button to open a Slack authorization window, where you can pick the Slack instance you want to connect to and view what permissions xMatters needs in your Slack environment.
- Click Authorize to approve. You should see a success message saying you've successfully connected to Slack. The bot is automatically added to your Slack workspace.
You can only connect one workflow to a Slack workspace. If you try to connect to a workspace that already has the xMatters bot installed, a dialog appears asking you to confirm that you want to overwrite the existing integration. It's a good idea to check in your organization to make sure no one else is already connected to the workspace. Also, if you want to use the xMatters bot in multiple Slack workspaces, you need to set up a separate workflow for each one.
Once you get the message that you're successfully connected, you can close the window and return to xMatters, which shows your configuration is now connected. The xMatters bot shows up in your list of apps in your Slack workspace and you can invite it to public channels (our bot doesn't get involved in direct messages or private channels just yet).
Installing the bot without a workflow lets you quickly start using /slash commands to initiate incidents in xMatters from Slack. If, at a later date, you want to use the @ commands, you'll need to install a workflow.
- Open the Slack App Directory and search for xMatters.
- Click Add to open the app page.
- Click Add to Slack. You're requested to allow xMatters to access your Slack workspace.
- Click Allow.
After you complete the authentication, you're ready to initiate incidents from Slack.
Connecting an existing bot to a workflow
If you want to connect the bot to a workflow down the line so you can make use of the @ commands, simply go back and add the workflow in xMatters. When you click Add to Slack, it connects the workflow to your existing app. If you get a warning that you're going to overwrite someone's configuration, another person in your Slack workspace might already have done this — ask around to make sure you don't muck up your colleague's work.
The bot's @ commands let you look up groups, see who's on call and quickly invite the on-call members of that group to a discussion in Slack.
The first thing you need to do is invite the xMatters bot to your channel. Simply type @xMatters hello and hit Enter, and our bot will drop in and say hello.
You can enter @xmatters help to see what our bot can do — but here's the list anyway:
- @xmatters hello: Say hello to our bot!
- @xmatters find + a keyword: Find groups that match the keyword (or partial keyword — typing 'adm' finds 'System Admins' and 'Database Admins'). Pick your group from the list (if there's more than one). After you find your group, you can choose to see who's on call or send the on-call members an invite to the channel if it's public (we can't invite people to a private channel because it's, well, private). By the way, our bot also understands @xmatters lookup.
- @xmatters on-call + a group name: Look up who's on call in a particular group and see the escalation path (if someone is absent, their replacement is shown or, if there's no replacement, it shows the next person in the escalation). Again, you can type a partial group name and our bot will try to find it. When our bot shows you who's on call in the group, it also gives you the option to invite them to the channel if it's public (again, we can't invite people to a private channel). By the way, it also understands @xmatters oncall.
- @xmatters invite + a group name: Use xMatters notifications to invite the on-call members in a group to the channel (make sure it's a public channel - we can't invite people to a private channel). xMatters looks up the on-call members in the group (if needed, looking up the on-call members of any groups that are on call, etc.), sends them a notification on their preferred devices (including a link to the channel, if supported — we can't send a link in a voice message). If they get the alert via email or the xMatters mobile app, they can click the link right in the notification to join the channel. (Again, always trying to be helpful, our bot also understands @xmatters engage and @xmatters page.)
We use @xMatters in the examples above, but you can change the @ command in the App settings in Slack.
The slash commands let you initiate an incident in xMatters right from within Slack. If you use the command in a public channel, that channel automatically gets added to the incident as a collaboration channel, allowing resolvers to join the conversation by clicking the link.
To use the slash commands, the bot needs to be installed in Slack, but you don't need a Slack workflow installed in xMatters unless you also want to use the @ commands to look up who's on call and invite them to a channel. Once it's installed, you can connect to xMatters with your account to initiate incidents.
- /xmatters connect: Connect Slack to your xMatters account
- /xmatters initiate: Initiate an incident in xMatters
- /xmatters disconnect: Disconnect Slack from your xMatters account
- /xmatters help: See a list of what you can do with the slash commands
- /xmatters status: Check if the bot is connected to xMatters and as who
Using the /xmatters initiate slash command, you can initiate an incident in xMatters right from a conversation in Slack, as long as you have access to the default xMatters Incident Management workflow or another custom incident resolution workflow.
- Enter /xmatters initiate (if you're not connected, a dialog appears asking you to connect).
- In the Initiate Incident dialog box, select an incident submission form to use.
- You won't get an option to select a form if you only have access to one form, such as the 'Trigger an Incident' form in the default xMatters Incident Management workflow.
For a custom incident resolution workflow form to appear as an option in the list, it must be enabled for the mobile app.
- Type a summary and description for the incident, and select a severity.
- These populate the incident details. The status defaults to "Open", and the xMatters user you log in as is set as the owner, initiator, and resolver.
- Provide values for any additional fields in the incident submission form.
- Select the conversation where you want incident details posted after the incident is created (this defaults to where you used the command).
- Click Submit.
- Close the message that appears to let you know we're working on it and watch for the message to appear in Slack. You can optionally click View All Incidents to watch for the incident to be created in xMatters.
- If something goes wrong, we'll also post a message to you in Slack.
Once the incident is initiated, a success dialog box gives you the option to view the incident in xMatters, and a message with the incident details is posted in the conversation you selected in Slack. You can also click the Incident ID in this message to link to the incident in xMatters.
If you initiate an incident from a public channel, a collaboration channel is automatically created and added to the incident in xMatters, allowing resolvers to join the conversation by clicking a link in xMatters.
Because private channels are private, and conversations between you and another person are just between you, we don't add collaboration channels in these scenarios.
Here are the most common issues you might experience. You get a message saying:
- You don't have access to the workflow: You don't have permission to use the default xMatters Incident Management workflow; contact your xMatters administrator to get access to the workflow.
- You're not connected: Use the /xmatters connect command to connect Slack to your xMatters account.
- You should try again, and contact support if that doesn't work: It might be an intermittent glitch somewhere along the line, so try again. If it still doesn't work, contact support — we'll help you dig into it.
For more information on working with incidents in xMatters, see Incident Management.