Slack

1. Go to Workflow Templates on the Workflows tab and start typing "Slack" to filter the list.
2. Once you find it, click its tile then click Next to get to the configuration screen.
3. Give your integration a name and description.
4. 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).

   

5. Save your workflow. After you save, the Add to Slack button appears.



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

7. Click Allow 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 with 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).

Request to install the xMatters app

Your organization's Slack app manager may have set up policies that require the xMatters app to be reviewed by an app manager before you can install it. If your organization has this restriction, the Slack authorization window will have a Request to install tab where you can send your app manager a message requesting permission to install the xMatters app.

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.

1. Open the Slack App Directory and search for xMatters.
2. Click Add to open the app page.
3. Click Add to Slack. You're requested to allow xMatters to access your Slack workspace.
4. 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 have already done this — ask around to make sure you don't overwrite a configuration that is in active use.

The xMatters bot for Slack v2 takes advantage of the latest permissioning models in Slack and offers a number of upgrades to existing features. Also, if you're not using the bot in an instance anymore, it's a good idea to remove it, just in case.

To check your current bot version:

1. Log into Slack as an admin user and under Apps, select the xMatters app.
2. On the Home tab, look for a message indicating that the permissions are out of date.
   1. If you don't see it, you're all good!
   2. If your bot is out of date, click the Add to Slack button to install the latest version.

To remove the bot:

1. Log into Slack as an admin user and under Apps, select the xMatters app.
2. On the About tab, click Configuration to open the configuration settings in a browser.
3. At the bottom of the page that opens in the browser window, click Remove App

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 on-call groups, services, and broadcast groups that match the keyword (or partial keyword — typing 'adm' finds 'System Admins' and 'Database Admins'). Pick your group or service from the list (if there's more than one) and click View to see more information about your selection.



When you select an on-call group, you can view the group's name, description, and owned services. You can also view who's on call in the group, and you have the option to invite the on-call members to the channel if it's public (we can't invite people to a private channel because it's, well, private). To view and manage the on-call group directly in xMatters, click Manage in xMatters.



When you select a service, you can view the service's name, description, and its owner. You can also view the on-call members of the group that owns the service, and you have the option to invite them to the channel if it's public. To view and manage the service directly in xMatters, click Manage in xMatters.



When you select a broadcast group, you can view the broadcast group's name, description, and owned services. You can also view the members of the group, and you have the option to invite them to the channel if it's public. To view and manage the broadcast group directly in xMatters, click Manage in xMatters.

• @xmatters on-call + a group or service name: Type the full name of an on-call group or service to view who's on call in that group (or the group that owns the service) 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). 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). If you type the name of a broadcast group, you can still view its members and invite them to the channel. By the way, the bot also understands @xmatters oncall.

• @xmatters invite + a group or service 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). Type the full name of an on-call group or service to view on-call members in that group (or the group that owns the service). Press Send invite to open a modal where you can send 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.

1. Enter /xmatters initiate (if you're not connected, a dialog appears asking you to connect).
2. 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.

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

   

4. Provide values for any additional fields in the incident submission form.

5. Select the conversation where you want incident details posted after the incident is created (this defaults to where you used the command).
6. Click Submit.
7. Close the message that appears to let you know we're working on it and watch for the message to appear in Slack. Clicking View All Incidents opens the xMatters Incidents page, where you can also view the new incident once it's created.
   • 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.