This article provides installation, configuration, and implementation details when integrating xMatters On-Demand with Slack.
How it works
Slack is a popular cloud-based team collaboration tool.
Coupled with the power of xMatters alerts, the integration will:
- Let 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 publish a message:
Slack server builds a payload and sends it to the xMatters inbound integration URL configured in Slack's custom clash-command integration.
The integration includes the inbound integration "Inbound from Slack" that handles Slack submissions by notifying the xMatters group with name that matches name of 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 response callback in Invite to Channel form.
Download the integration package
To begin, download the communication plan attached to this article; it contains everything needed for this integration.
The first step in setting up your integration is to configure xMatters.
This integration requires a user who can authenticate REST web service calls when injecting events.
This user needs to be able to work with events, but does not need to update administrative settings. While you can use the default Company Supervisor role to authenticate REST web service calls, the best method is to create a user specifically for this integration with the "REST Web Service User" role that includes the permissions and capabilities.
Note: If you are installing this integration into an xMatters trial instance, you don't need to create a new user. Instead, locate the "Integration User" sample user that was automatically configured with the REST Web Service User role when your instance was created and assign them a new password. You can then skip ahead to the next section.
To create an integration user:
- Log in to the target xMatters system.
- On the Users tab, click the Add New User icon.
- Enter the appropriate information for your new user.
- Assign the user to the REST Web Service User role.
- Click Save.
- On the next page, set the web login ID and password.
Make a note of these details; you will need them when configuring other parts of this integration.
The integration will notify the group with name than matches the Slack channel. If the group does not exist, the xMatters event will not be created.
For more information about creating users and devices in xMatters, refer to the xMatters On-Demand help.
The next step is to import the communication plan.
To import the communication plan:
- In the target xMatters system, on the Developer tab, click Import Plan.
- Click Browse, and then locate the downloaded communication plan (.zip file).
- Click Import Plan.
- Once the communication plan has been imported, click Plan Disabled to enable the plan.
- In the Edit drop-down list, select Forms.
- For the Send Event form, in the Not Deployed drop-down list, click Create Event Web Service.
- After you create the web service, the drop-down list label will change to Web Service Only.
- In the Web Service Only drop-down list, click Permissions.
- Enter the integration user you configured above, and then click Save Changes.
Each integration service has its own URL that you can use to target it from Slack.
To get a web service URL for an integration service:
- On the Integration Builder tab, expand the list of inbound integrations.
- Click the gear icon beside the integration service you want to target, and then select Integration URL.
You will need the URL for each integration service when configuring Slack.
Now that you've configured xMatters, you can configure Slack to integrate with xMatters. The following sections require you to log into Slack and access the Apps & Integrations settings page.
Slack uses Slash Commands to initiate the xMatters events when assistance is required from an on-call group.
To configure the webhook, select the BUILD A CUSTOM INTEGRATION option, and click SLASH COMMANDS.
Provide the name of the Slash command, for example /xMatters, and add the Slash Command Integration:
On the Integration Settings page, set the value of the URL field to the inbound integration service URL, and then save 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.
To request the on-call members of the DBA and Operations team to the current channel in slack, enter the following command.
/xmatters DBA Operations
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.