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 the Integration Agent

Install and configure SolarWinds

Test 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 uses a client-hosted Integration 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..

Credits: This integration was created and supplied by Brannon Vann, with additional updates and contributions from Travis Depuy and Jordan Olin.

Download the integration package

To begin, download the integration archive attached to this article and extract it to a location on your local machine. Some of the instructions in this article will reference specific folders within the extracted integration archive. 

Setup begins with configuring xMatters and the Integration Agent, and then requires configuring SolarWinds Alerts to execute events in xMatters.

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.

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:

  1. Log in to the target xMatters system.
  2. On the Users tab, click the Add New User icon.
  3. Enter the appropriate information for your new user.
  4. Assign the user to the REST Web Service User role.
  5. Click Save.
  6. On the next page, set the web login ID and password. 
Make a note of these details; you will need them when configuring the Integration Agent.

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. 

You can create multiple groups and users at once using the EPIC feature. 

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 following file within the extracted integration archive:

/components/xmatters/SolarWindsIntegrationv12.zip

  1. Click Import Plan.
  2. Once the communication plan has been imported, click Plan Disabled to enable the plan.
  3. In the Edit drop-down list, select Forms.
  4. For the Alerts form, in the Not Deployed drop-down list, click Create Event Web Service.
    • After you create the web service, the drop-down list label will change to Web Service Only.
  5. In the Web Service Only drop-down list, click Permissions.
  6. Enter the integration user you configured above, and then click Save Changes.

Accessing web service URLs

To get the web service URL for a form, in the Web Service Only drop-down list, click Access Web Service URL. Copy the highlighted URL at the top of the dialog box.

  • Note: The Access Web Service URL option appears twice in the drop-down menu. Ensure that you click the option just below Create Event Web Service
You'll need these URLs when you configure the Integration Agent.

Configure xMatters Integration Agent

Now that you've configured xMatters On-Demand, it's time to configure the Integration Agent

Prerequisites

The installation instructions below assume you already have a working xMatters Integration Agent.  If this is a new installation and you have not yet deployed the Integration Agent please follow this link to download, deploy and configure:

Integration Agent for xMatters 5.x & xMatters On-Demand

SolarWinds REST user

You will also 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 Integration 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 and note their credentials for use when configuring the Integration Agent.

Install the package

The installation package contains all that you need to configure the SolarWinds integration.

In the following instructions, <IAHOME> refers to the installation folder of your Integration Agent on the SolarWinds server; for example: C:\integrationagent-5.1.5\

To install the package:

  1. Within the extracted integration archive, navigate to:
    /components/xMatters Integration Agent
  2. Copy the solarwinds folder to <IAHOME>\integrationservices
  3. Open the <IAHOME>\conf\IAConfig.xml file and add the following line to the "service-configs" section:
    <path>solarwinds/solarwinds.xml</path>
  4. Save and close the file.
  5. Open the configuration.js file found in the <IAHOME>\integrationservices\solarwinds folder and add or set the values for the following variables:
WEB_SERVICE_URL The web service URL of the communication plan form (see Accessing web service URLs, above).
INITIATOR The User ID of the integration user you configured in xMatters.
PASSWORD

Path and filename of the password file containing the encrypted REST API user's password.

For more information about creating this file, see the comments within the configuration.js file, or refer to the xMatters Integration Agent Guide.

CALLBACKS The default setting of ["status","deliveryStatus", "response"] is required for two-way communication.

SW_REST_USER

Must be set to the user ID of a SolarWinds user capable of authenticating the REST web service requests as explained in Prerequisites, above.
 SW_REST_PASS_LOC  

Path and filename of the password file containing the encrypted REST API user's password.

For more information about creating this file, see the comments within the configuration.js file, or refer to the xMatters Integration Agent Guide.

  1. Save and close the file.
  2. Restart the Integration Agent.

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 Integration Agent").
  5. In the URL field, type the address of the local Integration Agent's web service listener.
    • Typically, this will be http://localhost:8081/http/applications_solarwinds
  6. Select the Use HTTP Post option.
  7. In the Body to POST field, enter the body of the HTTP POST. 
    • You can use the following code as the basis for your POST; change RECIPIENT to the xMatters user or group you want to notify:
{
"properties": {
"recipient": "RECIPIENT",
"severity": "Critical",
"alert_id": "${N=Alerting;M=AlertID}",
"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.

Adjust the maintenance mode time frames

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: 1 week, 2 days, or 2 hours. 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

Notification

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

 

 

Test the integration

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

Download resources

 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk