Welcome to the xMatters community!

We created this site for our customers and partners and we encourage you to explore, engage, and learn. To ensure that this community is fun and helpful, professional and respectful participation is expected... and troll-like behavior won't be tolerated.

How it works

Lets people know when they are needed to participate in a Slack conversation.

Quickly identifies and notify on-call members of xMatters groups

Allows for voice, SMS, and push messages to users.

Allows users to reply with "Acknowledge" and "Ignore" from their device.

Allows users to post responses back to Slack channel from their device.

Event injection is initiated when a custom "slash-command" is used in Slack to identify the xMatters groups you want to invite to a channel; for example:

/xmatters Operations

Slack server builds a payload and sends it to the xMatters inbound integration URL configured in Slack's custom slash-command integration.

The integration includes the inbound integration "Inbound from Slack" that handles Slack submissions by notifying the xMatters group with the name that matches the one typed into the Slack channel.

Recipients can respond with "On my way" or "Can't make it". By default, the responses and delivery notifications are posted back to Slack channel.

NOTE: If you prefer not to receive delivery notifications, just disable the Delivery updates outbound integration.

Configure xMatters

The first step in setting up your integration is to configure xMatters.

Download the communication plan

To begin, download the communication plan (.zip file) attached to this article; it contains everything needed for this integration. You do NOT need to extract the contents - you can import it directly into xMatters.

Set up an integration user

This integration requires a user who can authenticate REST web service calls when working with events – these permissions are provided by the "REST Web Service User" role in xMatters.

For Free and Trial customers, your system has an "Integration User" already configured with the REST Web Service User role, so you don't need to burn up an extra user from your limited supply. Make sure you've changed this user's password from the default, then you're good to go.

For everyone else, we recommend you create a user specifically for this integration because this user appears as the initiator or submitter of events from the integration (in messages, the Communication Center, event reports, etc.). Give this user the "REST Web Service User" role and a profile that lets you easily identify the user as specific to the integration – for example:

User ID: slack

First name: Slack

Last name: Integration

Note: Make sure you keep the user ID and password of this user handy. You'll need them when configuring other parts of this integration.

Create users and groups to receive notifications

The integration notifies the xMatters group whose name matches the Slack channel. If the group does not exist, the xMatters event will not be created.

For the Invite to Channel form, in the drop-down list, click the Web UI, Web Service drop-down list, click Sender Permissions.

Enter the integration user, and then click Save Changes.

Configure inbound integrations

You need to make sure the inbound integration is set to use URL authentication, and then retrieve the URLs to configure the app in Slack.

To configure an inbound integration and retrieve its URL:

In the Integration Builder, expand the list of inbound integrations.

Click the name of the integration to view its details.

Scroll down to How to trigger the integration at the bottom of the page, and select the integration user as the authenticating user (make sure the authentication method is set to URL authentication). The URL trigger is updated to reflect the new user.

To be able to select the integration user, you need to be a supervisor of that user and the user needs to be assigned to the REST Web Services role.

Click Copy beside the field:

You'll need the URL for the inbound integration service when configuring Slack.

Configure Slack

Now that you've configured xMatters, you can configure Slack to integrate with xMatters.

Add Slash Command

Slack uses Slash Commands to initiate the xMatters events when assistance is required from an on-call group.

Log into Slack and access the App Directory.

The easiest way to do this is to click the arrow beside your Slack domain and select Customize Slack. A page to customize Slack opens in your browser. From there, click Configure Apps.

Under Manage, click Custom Integrations then select Slash Commands.

You can also use the search box at the top of the page to find the Slash Commands integration option.

Provide a name for the Slash command, for example /xMatters, then click Add Slash Command Integration:

Scroll down to the Integration Settings and set the value of the URL field to the inbound integration URL, and then save the integration.

Test the integration

To test the integration, enter the slash command you created into a Slack channel following by a space delimited list of groups you want to notify.

For example:

To invite the on-call members of the DBA and Operations groups to the current channel in Slack, enter the following command.

/xmatters DBA Operations

Troubleshooting

When troubleshooting why an event doesn't seem to make it over to xMatters, the best place to look is the Integration Builder Activity Stream. While on the Integration Builder tab, click the gear icon beside an integration service, and then click Activity Stream.

The Activity Stream contains the incoming (and for outbound integrations, the outgoing) request, any logging statements as well as the final event creation messages.

Extend the integration

Integration Builder endpoints can now be configured to use Slack authentication. If you want to change the imported default endpoint to use the Slack authentication type, you will also need to update the outbound integration scripts.

To update the endpoint:

In xMatters, navigate to the Integration Builder for the Slack communication plan, and click Edit Endpoints.

Click the Slack endpoint, and then, in the Authentication drop-down list, select Slack.

Click Connect.

A new browser window will open to slack.com to authorize access to your Slack account. (Make sure your browser allows popups for this step.)

Select or sign into the Slack team that you want to allow xMatters to access.

Click Authorize.

In the Integration Builder, expand the list of outbound integrations and then click Delivery updates.