The information in this article is the intellectual property of xMatters and is intended only for use with xMatters products by xMatters customers and their employees. Further, this intellectual property is proprietary and must not be reused or resold.
This article provides installation, configuration, and implementation details when integrating xMatters On-Demand with BigPanda.
BigPanda correlates alerts from various monitoring system into high-level incidents, helping users such as IT Administrators or Operations teams reduce noise and spot critical issues faster. By coupling BigPanda with the power of xMatters, this integration:
- Automatically notifies the recipient on a variety of devices when an incident is created or updated.
- Allows for email, voice, SMS, and push messages to recipients.
- Allows recipients to reply with "Acknowledge" or "Escalate" from their device.
The integration combines the highly-customizable Environments and AutoShare features with the notifications webhook in BigPanda, which sends an event to xMatters. When there is a change in the status of an incident, the AutoShare triggers an API call to xMatters with a payload. Once the payload arrives at the Integration Builder, xMatters creates an event and notifies the recipients:
- If a user is targeted, the user's devices will be notified. This recipient can response with "Acknowledge" and terminate the event.
- If a group is targeted, the first active member in the roster will be notified. This recipient can response with one of the following:
- "Acknowledge", which terminates the event, or
- "Escalate", which immediately sends the event to the next user in the escalation list.
All three callback types (event status updates, device delivery updates, and notification responses) are active by default.
This version of the xMatters On-Demand and BigPanda integration uses the notification webhooks created within BigPanda.
Custom Environments and AutoShare
The built-in "All" Environment includes every incident in BigPanda. You can also create custom Environments within BigPanda so different users can focus on the most relevant incidents. These environments can be defined by the areas of responsibility and process in your organization such as "web", "database", "mail", "finance" and so on. A server can be in multiple environments, so different teams can be notified based on the context of the incidents.
The AutoShare feature creates a customized workflow within xMatters to handle BigPanda monitored incidents and alerts. Whenever an incident is created, resolved or reopened in BigPanda, the environment(s) monitoring the incident automatically shares it through the integration channel.
After an event is created in xMatters, Event status updates, Device delivery updates, and Notification responses can be sent back to the source BigPanda incident via outbound integrations.
To begin, download the communication plan attached to this article; it contains everything needed for this integration. You do not need to extract the contents.
The integration will notify groups and users when events are created in xMatters. They must exist in xMatters before they can be listed as recipients:
You need to set a request header that includes a Bearer token for authentication in each BigPanda API call. To find your token in BigPanda, click the Integrations tab at the top of BigPanda screen. Then click the existing integration or create a new integration for the API or wrapper you are using. Your token appears automatically in the instructions.
For more details, see the BigPanda documentation.
The first step in setting up your integration is to configure xMatters.
This integration requires an integration 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.
If this role does not exist in your deployment already, you may need to ask your xMatters Client Success Manager to create it for you. In the following example, this role is named "REST Web Service User".
To create a REST API user:
- Log in to the target xMatters system.
- On the Users tab, click Add.
- Enter the appropriate information for your new user. Because this user will affect how messages appear for recipients, you may want to identify the user as specific to BigPanda. For example:
- First Name: BigPanda
- Last Name: Integration
- User ID: bigpanda
Make a note of the user credentials and details. You will need them when configuring other parts of this integration.
The next step is to import the communication plan into xMatters.
To import the communication plan:
- In the target xMatters system, click Import Plan from the Developer tab.
- Click Choose File, and then locate the downloaded communication plan (.zip file).
- Click Import Plan.
- Importing the plan will automatically enable it, and enable its forms for web services.
The BigPanda Incident form uses the default recipients specified on the Layout tab to determine who to notify about an incoming alert.
- On the Forms tab, click Edit > Layout.
- In the Recipients section, add all of the groups and users you want to receive BigPanda AutoShare notifications.
- Click Save Changes.
After you import the communication plan, you need to setup the BigPanda constant.
- From the communication plan, click the Integration Builder tab, and then click Edit Constants.
- Select the BigPanda_BEARER constant, paste your BigPanda Bearer Token into the Value field, and then click Save Changes.
You will need to configure the authentication and retrieve the URLs for the inbound integration to configure Big Panda.
To configure an inbound integration:
- In the Integration Builder, expand the list of inbound integrations.
- Click the AutoShare webhook integration to view its details.
- Under the Select authentication method step, select Basic from the drop-down list.
- Click Update Integration.
- Scroll down to the bottom of the page, and click Copy URL beside the field:
Now that you've configured xMatters to integrate with your system, it's time to configure BigPanda to integrate with xMatters.
Note: The following sections require you to log into BigPanda with an Admin role.
Encode the authentication header value
All webhooks within BigPanda need a custom HTTP header that identifies the credentials of the integration user to access the xMatters inbound integration.
To create this value:
- Go to https://www.base64encode.org/.
- In the "Encode to Base64 format" area, type the username and password of your integration user in the following format: username:password
- Click Encode, and copy the result.
- For example: hijffpc8b83cqiyriyrbqrbiauf:fabhjw!cbBBUIC85fh
- Login to BigPanda, and then click the Integrations icon.
- Click the New Integration button.
- In the Create a New Integration page, click the Collaboration tab, and then click Webhooks:
- On the Webhook Integration page, enter a name for the integration, and then click Generate App Key button.
- In the Callback URL field, paste the Integration URL for your inbound integration.
- In the Custom Headers section, add a custom HTTP header:
- For the key, enter Authorization
- For the value, enter Basic, followed by the Base64-encoded value that represents the integration user's credentials.
- Click Configure Webhook.
After you create a Notification Webhook, you can associate it with one or more environments:
- Click the Settings drop-down list (the gear icon), and select AutoShare.
- Click Create AutoShare.
- In the Create AutoShare dialog box, select the Environment you want to share.
- In the Escalate via drop-down list, select the webhook you created:
- Click Next to save the AutoShare settings.
To test the integration, create an alert that will satisfy the environment associated with the AutoShare.
The AutoShare will be triggered via the newly created Webhook, followed by these additional comments in the Activity Feed:
- An xMatter Event is created and set to Active
- A notification is sent to the recipient
There are several places you can inspect when troubleshooting why an AutoShare incident is not sent to xMatters, or when no responses are recorded in the Activity Feed.
The xMatters Integration Builder Activity Stream is a good place to look for when the the recipient doesn't receive any notification.
While on the Integration Builder tab, expand the Inbound Integrations section, click the gear icon beside the intended integration service, and then click Activity Stream.
The Activity Stream contains the incoming request, any logging statements, and the final event creation messages.
Similarly, the Activity Stream contains the outbound request sending to BigPanda. The following example shows the Notification Responses activity stream:
Subscriptions allows users to be notified on incidents and events even though they are not on the recipient list in the communication plan.
To allow other users to subscribe to events, you must create a subscription form for the BigPanda communication plan. This form defines who can subscribe to events, which properties they can subscribe to, and whether they can respond to notification. You can also use the form to set message content for the notifications sent to subscribers, and how to handle any responses.
For complete information on how to create subscription and assign them to users, refer to the Subscribe to events section in the On-Demand online help.