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. When an outage is detected or cleared in Panopta, it sends a JSON-formatted webhook to xMatters. A Panopta trigger in xMatters parses the webhook and initiates a flow. The webhook includes essential alert data you can use to enrich notifications to users or when building automated tasks.

Install the workflow

Here's how to install the Panopta workflow through the xMatters one-click installation process. If you already installed the previous, built-in version of the integration, you can find instructions here.

  1. Go to the Workflows Templates page and click the Panopta tile.
  2. On the Set up the Workflow tab, give the workflow a name that identifies its purpose (this must be unique in your instance), add an optional description, and set the default incident type (if applicable). Any built-in Initiate Incident steps in the workflow will automatically be set to the selected incident type.
    • You can edit these later, if needed.

  3. Click Next to set up the connection.
  4. Choose the authentication method you want to use to generate the trigger URL.
  5. Copy the trigger URL — you’ll use this to configure the webhook in Panopta.
    • The trigger URL includes the recipients parameter, which specifies who should be notified. By default, this parameter is set to notify you (the logged in user), but you can set it to target any user or group you want.

  6. You can copy the Configuration Payload to configure the signal in the source application.
  7. Send a test signal to the trigger URL to test the connection.
  8. Click Open Workflow to view and customize the workflow, or Close to return to the Workflows page..

Configure Panopta to send requests to the trigger URL

To have Panopta send alerts to the flow trigger, you need to configure a webhook and set it to use the trigger URL.

  1. In Panopta go to Settings > Integrations.
  2. Under Webhook, click Configure.

  3. Fill in the following fields on the webhooks screen:

    • Title:xMatters
    • Trigger Event: Expand the drop-down menu and select Incident Detection and Incident Close.
    • Request Method:  Paste the trigger URL you copied from Flow Designer. Add the target names of any recipients you want to notify when the alert fires to the end of the URL.
      • For URL authentication, use an ampersand to attach recipients. For example, if you want to notify Emma Pearson and the on-call members in the group responsible for the Antares service, you'd add &recipients=epearson,antares to the URL.
      • For other authentication types, use a question mark to attach recipients. For example, if you want to notify Barry Gull and the on-call members in the group responsible for the Cassiopeia service, you'd add ?recipients=bgull,cassiopeia to the URL.
      • You must URL-encode any special characters or spaces in the target names.
    • Payload Type: Expand the drop-down menu and select Raw Payload.
    • In the Raw Payload field, insert the Configuration Payload you copied from the Panopta trigger in Flow Designer.
  4. Click Save.

You'll now need to add the webhook to an alert timeline.

  1. In Panopta go to Monitoring > Alert Timelines.
  2. Select the Alert Timeline you want to add the alert to.
  3. Click Add New Alert Event.

  4. Configure the Trigger Time by selecting hour, minutes, and seconds from the drop-down menu.
  5. In the Integrations drop-down menu, select xMatters.

  6. Click Create Action to add it to the alert timeline.

You're ready to use the webhook to trigger automated flows, including steps such as sending alerts and initiating incidents, though we always recommend testing before putting things into use.

Set recipients in the trigger URL

The trigger expects the recipients in the trigger URL. When you copy the URL from xMatters, it includes the recipients parameter: recipients=<yourname>. Of course, you don’t want to receive all the alerts.

To change the recipients for alerts from this webhook, swap out your name for the people or groups you want to target. For example, to target the 'DatabaseTeam', 'Antares Service Team', and 'HR & Marketing' groups, add recipients=databaseteam,antares%20service%20team,HR%20%26%20Marketing to the trigger URL. Remember to URL-encode any special characters, including spaces, in your group names.

We recommend using groups so you can take advantage of the xMatters group features — rotations, escalations, and absences — to reach the right on-call people to jump on an issue.

How to use the workflow

When a condition you've set fires, it sends a signal to xMatters, which creates an alert and notifies the individual or the on-call members of the people or groups you set as recipients in the webhook URL. When the trigger receives a signal saying the issue is resolved, it automatically terminates related alerts in xMatters.

The person responding to the notification has the following response options:

  • Acknowledge: Acknowledges the notifications and stops escalations.
  • Escalate: Immediately escalates the alert to the next on-call resolver in a targeted group.
  • Close: Ends the xMatters alert and stops notifying all targeted recipients.
  • Initiate Incident: Initiates an incident in xMatters.

Next Steps

Now that you've installed the Panopta workflow, you can use it as-is, or customize it to suit your needs better. Here are some examples of things you can add to the workflow to customize it:

Previous version of the integration

While the previous version of this integration is no longer available, the instructions for it are included below for anyone who has it installed in their system already.

This article provides installation, configuration, and implementation details when integrating xMatters with Panopta.

  • How it works
  • Download the integration package
  • Confgure xMatters
  • Configure Panopta
  • Test the integration
  • Troubleshooting
  • Download resources

    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:

    This handles notifications about outages by notifying a recipient (an individual or a group) defined either in the corresponding form or in the custom 'target' property of the payload. The latter enables you to 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 alert alive, or "Escalate", which causes the integration to escalate the alert in xMatters.

    This terminates all xMatters alerts associated with a outage and creates an FYI alert to notify a recipient or recipients configured in the corresponding 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.

    By default, the response callbacks are disabled for both forms.

    Download the integration package

    To begin, download the workflow at the bottom of this article; it contains everything needed for this integration. Don't extract the contents — you'll import the .zip file into xMatters.

    Configure xMatters

    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 working with alerts – these permissions are provided by the "REST Web Service User" role in xMatters. See Create an integration user for more information.

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

    The integration notifies the group or user defined as a recipient in the workflow's forms or as the 'target' property in the payload. If the recipient is not defined, and the 'target' property is missing, the xMatters alert will not be created.

    For more information about creating users and devices in xMatters, refer to the xMatters online help.

    Import the workflow

    The next step is to import the Panopta workflow.

    1. In the target xMatters system, on the Workflows tab, click Import.
    2. Browse to the .zip file you downloaded, or drag it onto the Import Workflow dialog box.
    3. Click Import Workflow.
    4. Click the gear icon beside the workflow, and select Editor Permissions.
    5. Add the integration user, and then click Save.
    6. Click the workflow name to open the Forms tab.
    7. For the Panopta Outage form, in the Web Service drop-down list, click Sender Permissions.
    8. Enter the integration user, and then click Save Changes.
    9. Click Edit beside the Panopta Outage form, and then select Layout.
    10. In the Recipients area, specify a recipient (a user or a group) for alerts, and then click Save Changes.
    11. Repeat steps 6-10 for the Panopta Clear form.

    Configure inbound integrations

    You need to update each of the inbound integrations to use URL authentication, and retrieve the URLs to configure Panopta.

    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 Trigger field:

    Once you have retrieved the URLs, you can log the integration user out of xMatters.

    Configure Panopta

    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:

    {

    "fqdn":"$fqdn",

    "name":"$name",

    "timestamp": "$timestamp",

    "event":"$event",

    "services": "$services",

    "resource":"$resource",

    "items":"$items",

    "reasons":"$reasons",

    "duration": "$duration",

    "tags":"$tags",

    "server_key":"$server_key",

    "partner_server_id":"$partner_server_id",

    "item_type":"$item_type",

    "alert_label":"$alert_label",

    "target":null

    }

    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.

    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.

    Test the integration

    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:

    Troubleshooting

    There are several places you can inspect when troubleshooting why an event doesn't seem to make it over 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 alert creation messages.

    For the two-way integration from xMatters to Panopta, the primary source of logging is the Integration Builder Activity Stream for that particular integration.

    Download resources

    Panopta.zip