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 Panopta.
How it works
Panopta is an advanced website and server monitoring and outage management service that informs users of outages as soon as they occur.
Coupled with the power of xMatters alerts, the integration:
- Quickly identifies and notifies the on-call resource on a variety of devices.
- Allows for voice, SMS, and push messages to users.
- Allows users to reply with "Accept" and "Escalate" from their device.
When an outage is detected or cleared in Panopta, the server builds an event payload and sends it to the xMatters inbound integration URL configured in the webhook integration.
The integration includes the following inbound integrations:
Panopta Outage Event handles notifications about outages by notifying a recipient (an individual or a group) defined either in the communication plan's form or in the custom 'target' property of the payload. The latter enables the user specify the recipient(s) directly in Panopta.
- Email notifications include a link to view the outage details in the browser.
- Recipients can respond with "Accept", which causes xMatters to stop notifying other users but keeps the event alive, or "Escalate", which causes the integration to escalate the event in xMatters.
Panopta Clear Event terminates all xMatters events associated with a outage and creates an FYI event to notify a recipient or recipients configured in the corresponding plan's form when the outage is cleared in Panopta.
- Alternatively, the recipient can be configured as 'target' custom attribute in the payload. The target's value can be a single string - the username of an xMatters user or the name of an xMatters group - or an array of names.
NOTE: By default, the response callbacks are disabled for both forms.
Download the integration package
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 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 required 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 Add.
- Enter the appropriate information for your new user. Because this user affects how messages appear for recipients and how events are displayed in the reports and Communication Center, you may want to identify the user as specific to Panopta; for example:
- First Name: Panopta
- Last Name: Integration
- User ID: panopta
- Assign the user to the REST Web Service User role.
- Make a note of the user ID and the password you choose; you need them when configuring other parts of this integration.
- Click Add.
The integration will notify the group or user defined as a recipient in the communication plan's forms, or as 'target' property in the payload. If the recipient is not defined, and 'target' property is missing, 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 Choose File, and then locate the downloaded communication plan (.zip file).
- Click Import Plan.
- Click the Edit drop-down list for the plan, and select Access Permissions.
- Add the integration user you created above, and then click Save Changes.
- In the Edit drop-down list, select Forms.
- For the Panopta Outage form, in the Web Service drop-down list, click Sender Permissions.
- Enter the integration user you configured above, and then click Save Changes.
- Click Edit beside the Panopta Outage form, and then select Layout.
- In the Recipients area, specify a recipient (a user or a group) for events, and then click Save Changes.
- Repeat steps 6-10 for the Panopta Clear form.
You will need to update each of the inbound integrations to use basic authentication, and retrieve the URLs to configure Panopta. (The following steps assume that you are using the URL Authentication option, which is the default setting for this communication plan. For more information about these options, see Inbound integration service authentication.)
To configure an inbound integration and retrieve its URL:
- Log out of xMatters, and then log back in as the integration user you configured above.
- Navigate to the Integration Builder tab for the Panopta communication plan, and expand the list of inbound integrations.
- Click the name of an integration.
- Scroll down to the bottom of the page, and click Copy URL beside the field:
Once you have retrieved the URLs, you can log the integration user out of xMatters.
Now that you've configured xMatters, you can configure Panopta to integrate with xMatters. The following sections require you to log into Panopta and access the Configuration page.
Panopta uses the Webhook integration to initiate the web service calls when outages are detected or cleared.
To configure a Webhook for xMatters, open the CONFIGURATION menu item, and then click INTEGRATIONS. In the APPLICATION INTEGRATION section of the SUPPORTED INTEGRATIONS tab and click the Install button for the Webhook integration:
On the Webhook configuration page, in the Label field, type xMatters. On the OUTAGE WEBHOOK tab, in the Request method list, select POST, and then paste the URL for the Panopta Outage Event inbound integration in the Postback URL field.
Leave the HTTP Headers and authentication fields blank, select Raw Payload as the Payload Type, and then paste the following code in the Raw Payload field:
If you only want to receive Outage notifications, click "Create Webhook Notification" button now. If you want to also receive FYI notifications when an outage is cleared, continue with the next section.
Clear Event Notifications
To enable FYI notifications when an outage is cleared, click the CLEAR WEBHOOK tab, clear the Same as Outage option, and then repeat the steps outlined above, using the Panopta Clear Event inbound integration's URL as the Postback URL.
Once you are finished, click the Create Webhook Notification button.
Once the integration is configured, you can add it to the Notification Schedule of your choice. Should you need to update the integration, it can be accessed on the CONFIGURED CONFIGURATIONS tab.
To test the integration, you can use the Outage Simulator provided by Panopta. Choose any server associated with a Notification Schedule that includes the integration call, and click the Outage Simulator button. (It may take a minute or two for the integration to be called.)
You can monitor the progress in Panopta on the OUTAGE LOG tab:
There are several places you can inspect when troubleshooting why an event doesn't seem to make it over to xMatters.
Inbound to xMatters
The first place to look is the Integration Builder Activity Stream. 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 (and for outbound integrations, the outgoing) request, any logging statements as well as the final event creation messages.
Outbound from xMatters
For the two-way integration from xMatters to Panopta, the primary source of logging is the Integration Builder Activity Stream for that particular integration.