SolarWinds Orion Network Performance Manager Integration

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.

Contents

Introduction

Configure xMatters

Configure SolarWinds

Using the integration

Download resources

Introduction

This article provides installation, configuration, and implementation details for the xMatters On-Demand for SolarWinds Orion integration.

How it works

This integration (version 1.4) uses a client-hosted xMatters Agent, installed on the SolarWinds server. 

A "Send a GET or POST Request to a Web Server" trigger action in the network alerts creates an event in xMatters that drives communication to end users. When a SolarWinds alert is triggered, xMatters creates an event and notifies the specified recipients.

The latest version of this integration is two-way: responses from recipients are sent back to the SolarWinds server to update the originating event.

This integration sends alert information to xMatters including severity, alert definition ID, alert ID, alert name, object type, object ID, status, node name, IP address, location, and details. The "details" field is a flexible text field that can be used to provide additional information in the xMatters communications to recipients; the default configuration is to include a URL back to the details for the related object in the SolarWinds server.

Prerequisites

SolarWinds REST user

You will need the user ID and password for a SolarWinds user that has the ability to control nodes, administer alerts, and put nodes into an "unmanaged" state. This user will be used to authenticate the calls made by the xMatters Agent into the SolarWinds environment via their RESTful web service interface. If you do not already have a user with these permissions in your environment, create a new user in Solarwinds (Settings > Manage Account). You will need their credentials when configuring the SolarWinds endpoint in your communication plan.

SolarWinds hostname

When you install a copy of SolarWinds, the process creates a self-signed certificate for the hostname "solarwinds-orion", which you can use to make TLS-secured requests to the SWIS/JSON API. This name must be resolvable to the IP address of the SolarWinds Orion server by the machine on which you install the xMatters Agent. Typically, this is the same machine hosting the SolarWinds software. For more information about identifying the hostname for your instance, consult your SolarWinds documentation.

Download the communication plan

Before you begin, download the communication plan .zip file attached to this article and save it to a location on your local machine. You do not need to extract the contents! 

Configure xMatters

The first step in configuring the integration is to configure the components within xMatters.

Create an integration user

This integration requires a user who can authenticate REST web service calls when injecting events, and access the inbound integration settings to retrieve the URL.

While you can use the default Company Supervisor role for this integration, the best method is to create a user specifically for this integration with roles that include 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. Add the Standard User and Limited Developer roles to their permissions, and assign them a new password. You can then skip ahead to the next section.

To create an integration user:

  1. In xMatters, on the Users tab, click the Add New User icon.
  2. Enter the appropriate information for your new user; for example:
    • First Name: SolarWinds
    • Last Name: Integration
    • User ID: solarwinds
  3. Assign the user to the REST Web Service User, Standard User, and Limited Developer roles.
  4. Click Save.
  5. On the next page, set the web login ID and password, and save the user. 

Make a note of the login details; you will need them when configuring the xMatters Agent and the inbound integration authentication.

Create users and groups that will receive notifications

SolarWinds alerts are targeted to an individual or a group in xMatters. Each alert that will trigger an event in xMatters will specify the target for the notification. You will need to create the target groups and users in xMatters before you can send them SolarWinds alerts. 

Import the communication plan

The next step is to import the SolarWinds communication plan.

To import the SolarWinds communication plan:

  1. In the target xMatters system, on the Developer tab, click Import Plan.
  2. Click Browse, and then locate the downloaded communication plan.
  3. Click Import Plan.
  4. Once the communication plan has been imported, click Edit > Access Permissions.
  5. In the Communication Plan Access Permissions dialog box, add the integration user you configured above, and then click Save Changes.
  6. Now click Edit > Forms.
  7. For the Alert form, in the Web UI and Web Service drop-down list, click Sender Permissions.
  8. In the Form Sender Permissions dialog box, add the integration user, and then click Save Changes.

Configure the SolarWinds endpoint

The xMatters Agent will need to know where to target the SolarWinds REST API. To create this connection, you need to set the SolarWinds endpoint for the Integration Builder to a hostname resolvable by the SolarWinds machine.

To configure the endpoint:

  1. In the communication plan for SolarWinds, click the Integration Builder tab.
  2. In the Integration Builder, click Edit Endpoints, and then click the SolarWinds endpoint.
  3. In the SolarWinds endpoint settings, set the Base URL to your SolarWinds REST API hostname; for example: https://solarwinds-orion:17778
  4. Select the Trust self-signed certificates check box.
  5. In the Authentication Type drop-down, select Basic.
  6. In the Username and Password fields, enter the credentials for your SolarWinds REST user.
  7. Click Save Changes

Retrieve inbound integration URLs

To help get your integration up and running quickly, the following instructions explain how to use URL Authentication for your inbound integrations. If you are planning to use this integration in a production environment, we recommend using a more secure authentication method.

To get the URL for an inbound integration:

  1. Log out of xMatters.
  2. Log back into xMatters as the integration user, and navigate to the Developer tab.
  3. Beside the communication plan you imported, click Edit > Integration Builder.
  4. Expand the list of inbound integrations, and then click the name of an inbound integration.
  5. At the bottom of the page, click Copy URL.
    • Save the URL to a safe place for now - you'll use it to configure SolarWinds in a minute.

DO NOT log out as the integration user yet - you'll need to be logged in as this user for the next steps, too.

Install and configure the xMatters Agent

Now that you've configured xMatters On-Demand, it's time to configure the xMatters Agent. (For complete xMatters Agent documentation, see the On-Demand online help.)

To install the xMatters Agent:

  1. Make sure you are logged into xMatters as the integration user, navigate to the Developer tab, and then click Agents.
  2. On the Available tab, select your operating system from the drop-down list, and then follow the instructions on the screen to download and install the xMatters Agent to your local machine (the SolarWinds server).
  3. When the process is complete, check the Installed tab to confirm that the Agent has registered to your xMatters instance.
    • A successful installation should resemble the following:

We recommend that you rename the Agent to something easier to remember and indicative of its purpose; for example, "SolarWinds Agent". This name is used when configuring the outbound integrations, as described in the next section.

Configure outbound integrations

The final step in configuring xMatters is to set up the outbound integrations so they can use the new xMatters Agent to send updates and information back to SolarWinds. You must perform this step while logged in as the integration user.

To configure outbound integrations:

  1. Open the Integration Builder tab for the SolarWinds communication plan, and expand the list of outbound integrations.
  2. To enable the outbound integrations, click the toggle beside the name of each integration. (By default, the outbound integrations in the imported plan are disabled.)
  3. Click the name of the first outbound integration in the list to open it for editing.
  4. In step 2 on the Outbound Integration details page, in the Location drop-down list, select xMatters Agents.
  5. In the Agents list, select the xMatters Agent you installed for SolarWinds:

  1. Click Update Outbound Integration.
  2. Click the name of the communication plan at the top of the page to return to the Integration Builder tab, and then repeat steps 3-6 for the remaining outbound integrations in the list.

You can now log out as the integration user and log back in under your own credentials.

Configure SolarWinds

Now that you've configured xMatters, it's time to configure SolarWinds. 

Configure an alert

Each alert in SolarWinds can be configured to execute an event in xMatters.

Create SolarWinds Alert Trigger:

  1. In the SolarWinds web console, navigate to the Alerts tab, and then click Manage Alerts
  2. Click the Trigger Actions step, and then click Add Action (or click the Edit icon to edit an existing action).
  3. For the type of action, select Send a GET or POST Request to a Web Server.
  4. In the Configure action dialog box, type a name for the action (for example, "Post to xMatters").
  5. In the URL field, paste the URL you copied from the Alert - Inbound inbound integration.
  6. Select the Use HTTP Post option.
  7. In the Body to POST field, enter the following code as the body of the HTTP POST.
    • The "recipient" line is optional; if it is not included, xMatters will notify any recipients set on the form's Layout tab. Or you can change RECIPIENT to the target name of the xMatters user or group you want to notify:
payload={
  "recipient": "RECIPIENT",
"severity": "Critical",
"alert_id": "${N=Alerting;M=AlertID}",
"alert_time": "${N=Alerting;M=AlertTriggerTime;F=DateTime}",
"solarwinds_id": "${N=Alerting;M=AlertDefID}",
"objectid": "${N=SwisEntity;M=NodeID}",
"objecttype": "${N=Alerting;M=ObjectType}",
"alert_name": "${N=Alerting;M=AlertName}",
"status": "${N=SwisEntity;M=Status;F=Status}",
"node_name": "${N=SwisEntity;M=Caption}",
"ip_address": "${N=SwisEntity;M=IP_Address}",
"location": "${N=SwisEntity;M=Location}",
"details": "More details here: ${N=SwisEntity;M=DetailsUrl}"
}
  1. Save the alert.

Note: The payload structure used in this version of the integration has changed from previous versions. If you are updating an existing xMatters - SolarWinds integration, make sure you use the new format above.

Using the integration

Whenever an event in SolarWinds triggers the alert, the HTTP POST will send the information to xMatters and initiate the form. The integration will send the information to the recipient specified in the HTTP request, prompting them to respond. When xMatters receives the response, the outbound integration will send the response back to SolarWinds via the xMatters Agent, and update the original event. 

To test the integration, use the test alert feature available in SolarWinds on the alert configured to send an xMatters notification. 

Customize the response options

The two-way integration provides the ability to put a node or service into maintenance mode, or "unmanaged" in SolarWinds terminology. Whenever you put a node into an unmanaged state, you must specify a duration.

By default, the communication plan includes three responses that, when selected by a recipient, will put a node into maintenance mode for a different duration: 5 minutes, 15 minutes, or 1 hour. You can modify these options by editing the response in the communication plan and adjusting the time value encoded in the response.

Each of the responses in the communication plan contains a specially formatted string that encodes how long the object should be put into an unmanaged state. The format for the time frame specifier appended to each response is:

for <x>d:<y>h:<z>m

The word "for" must be following by all three components, where:

  • <x> is the number of days (0 to 365)
  • <y> is the number of hours (0 to 23)
  • <z> is the number of minutes (0 to 59)

Examples:

  • A response option of Maintenance Mode for 30d:0h:0m will put the object into an unmanaged state for 30 days.
  • A response option of Maintenance Mode for 0d:4h:30m will put the object into an unmanaged state for 4-and-a-half hours.
  • A response option of Maintenance Mode for 0d:0h:45m will put the object into an unmanaged state for 45 minutes.

Editing the responses in xMatters

Notification

The following is an illustration of how the response options would appear in an email:

 

Download resources

 
Have more questions? Submit a request

2 Comments

  • 0
    Avatar
    Don Clark

    Good news! This integration has been updated to version 1.4, and is now designed to use the xMatters Agent.

  • 0
    Avatar
    Don Clark

    Just a head's-up to anyone who might be updating an older version of this integration: the format of the payload used in the HTTP POST has changed!

    Previously, the integration used the payload to send a JSON body, so the POST had the following structure:

    {
    "properties": {
    "recipient": "RECIPIENT",
    ... }
    }

    In this version of the integration, however, SolarWinds sends URL-encoded parameters to the Integration Builder. The key is "payload", and xMatters parses the value to get the JSON data. So now the payload structure (as the article indicates) looks like this:

    payload={
    "recipient": "RECIPIENT",
    ...
    }

    I hope this helps!

    Edited by Don Clark
Please sign in to leave a comment.
Powered by Zendesk