xMatters

xMatters is a digital service availability platform that prevents technology issues from becoming business problems.

Supported VersionsTypeAuthentication Type
6+APIAPI Key

This integration creates a sharing channel from BigPanda to xMatters. When a BigPanda incident has a change in status, an API call is triggered to xMatters with a payload. The payload arrives at xMatters' Integration Builder and an event is subsequently created, followed by recipient notification.

xMatters has two methods of notification:

  • User targeted, the user's device or devices will be notified. This recipient can respond with "Acknowledge" to read the details of the incident and then terminate the event.

  • Group targeted, the first active member in a group's roster will be notified. This recipient can respond with "Acknowledge" or "Escalate", which forwards the event to the next user in the escalation list.

📘

The xMatters integration follows standard AutoShare rules. See the Sharing Rules documentation for more information.

Key Features

  • Automatically notify recipients on a variety of devices when a correlated BigPanda incident is created.

  • Utilize xMatters to communicate via email, voice, SMS, and push messages to recipients.

  • Allows users to action correlated incidents by replying with "Acknowledge" or "Escalate" from their device.

Before You Start

Download the xMatters Communication Plan

A communication plan will need to be imported into xMatters during the configuration process. Download the required communication plan below. Further modification of the plan is not necessary.

BigPanda.zip</ahttps://s3-us-west-1.amazonaws.com/bp-docs-artifacts/BigPanda.zip>

Configure xMatters

Create a Rest API User

This integration requires a REST API user to 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 a dedicated "REST Web Service User" role that includes the permissions and capabilities.

  1. Navigate to the Users tab, select Add.
  2. Enter the prompted information for the new user. It may be helpful to specifically identify this user to BigPanda because it will affect how messages appear for recipients.
  • First Name: BigPanda
  • Last Name: Integration
  • User ID: bigpanda
  1. Under the Roles section, add the REST Web Service User role.
  2. Select Add.

Import the Communication Plan

  1. Navigate to the Developer tab.
  2. Select Import Plan.
  3. Select Choose File and browse the saved communication plan (.zip file) from the Prerequisites section.
  4. Select Import Plan.
  • Importing the plan will automatically enable it and enable its forms for webservices.
  1. After the import completes, select Edit > Forms.
  2. For the AutoShare Webhook form, select Web Service Only > Sender Permissions.
  3. Enter the REST API user credentials from the previous step.
  4. Select Save Changes.

Set Notification Recipients

  1. Navigate to the Forms tab.
  2. Select Edit > Layout.
  3. In the Recipients section, add all of the groups and users you want to receive BigPanda AutoShare notifications.
  4. Select Save Changes.

Configure Integration Settings

  1. From the communication plan, select the Integration Builder tab.
  2. Select Edit Constants.
  3. Select the BigPanda_$(token) constant.
  4. Paste your BigPanda Bearer Token into the Value field then select Save Changes.

Configure an Inbound Integration

  1. In the Integration Builder, expand the list of inbound integrations.
  2. Click the AutoShare webhook integration to view its details.
  3. Under the Select authentication method step, select Basic Authentication from the drop-down list.
  4. Click Update Inbound Integration.
  5. Scroll down to the bottom of the page, and click Copy URL beside the field. You'll use this URL to setup the BigPanda webhook.

Configure BigPanda

  1. Navigate to BigPanda's Integrations menu.
  2. Select the Collaboration tab.
  3. Select the Integrate button under Webhooks.

  1. On the Webhook integration page, enter a name and then select the Generate App Key button.
  2. In the Callback URL field, paste the integration URL for your inbound integration from xMatters.

  1. In a separate window or tab, go to <https://www.base64encode.org>. Using the username and password of the integration user you created in xMatters, type user:password into the input field (replacing user and password with the actual values). Click Encode and copy the result.
  2. Back in BigPanda, click on the Plus (+) button under Custom Headers. Enter "Authorization" for key. For value, enter "Basic" followed by a space and then the Base64-encoded value from step #6.

  1. Click on Configure Webhook.
  2. Create an AutoShare rule based on your needs. This can be done on entire Environments or on a per incident basis. Please see [Define AutoShare Rules](https://docs.bigpanda.io/v2.0/docs/managing-sharing#autoshare-configuration) for more information.

Uninstall the Integration

Deleting an integration requires changes to both the integrated system and BigPanda. You must uninstall the integration on the integrated system and then delete the integration from BigPanda.

🚧

When replacing an existing integration with a new tool or system, we recommend configuring the new integration first to ensure no data is lost.

Stop Sending Data from BigPanda

In BigPanda, disable any settings that send data to the integrated system. This includes modifying or removing [AutoShare rules](https://docs.bigpanda.io/docs/managing-sharing) or [Environments](https://docs.bigpanda.io/docs/environments) that are tied to the integration.

Delete the Integration from BigPanda

  1. In BigPanda, navigate to the Integrations tab and select the desired integration from the list.
  2. In the integration details on the right, click Delete Integration. A support message opens, pre-populated with a request to delete the selected integration.
  3. Press Enter to send the request.
  4. The BigPanda support team will remove the integration from the UI.

This procedure does not remove any data from BigPanda or the integrated system. As needed, remove data from each system before deleting the integration.