Microsoft SCOM 2016 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

Before you begin

Configure xMatters

Configure the Integration Agent

Configure SCOM

Use the integration

Troubleshooting

Extend and optimize your integration

Download resources

Introduction

This article provides you with the installation, configuration, and implementation details you need to integrate xMatters On-Demand with Microsoft System Center Operations Manager 2016 (SCOM).

How it works

This integration uses a client-hosted Integration Agent, installed on the SCOM server. 

When a new SCOM alert triggers a given subscription, a notification channel delivers notification subscriber alerts, which send incident information to xMatters, including severity, priority, alert ID, server name, event source, event time, management group name, resolution state, and event description. xMatters then creates an event and notifies the specified recipients.

This integration is a configurable, two-way integration; updates from xMatters are recorded in SCOM.

The integration includes authentication from the Integration Agent to SCOM and from the Integration Agent to the xMatters On-Demand platform, in addition to the secure Integration Agent communication channel.

Features and updates

This version of the integration includes the following updates:

  • Injects events to xMatters via inbound integrations.
  • Adds support for the Event Comments trigger for outbound integrations.
  • Uses the latest version of the embedded Integration Agent utilities.
  • Makes the "Sent to xMatters" state change optional when injecting events.
  • Allows "del" injections to terminate existing events.
  • Removes the "Work in Progress" response option. (If you still want this response option, you can customize the integration to include it.) 

Before you begin

SCOM username and password

This integration requires the username and password of a SCOM user with Administrator privileges. Make sure you have these ready before you configure the integration.

Download the integration package

The .zip file attached to this article contains all of the components required to integrate xMatters and SCOM. Download the attached .zip file to a location on your local machine, and extract the contents.

You may also notice that there is another .zip file within the extracted integration package. This is the communication plan, which contains pre-configured integrations, forms, properties, and messages specifically designed for SCOM. Don't extract the contents of the communication plan .zip file! You'll import it directly into xMatters.

Configure xMatters On-Demand

The first step in setting up your integration is to configure 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 necessary permissions and capabilities.

Note for trial: 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 Add.
  3. Enter the appropriate information for your new user. Because this user affects how messages appear for recipients and how events are displayed in reports and the Communication Center, you may want to identify the user as specific to this integration. For example:
    • First Name: SCOM.
    • Last Name: Integration
    • User ID: scom
  4. Set the password for the user.
    • Make a note of the user ID and password details – you need them when configuring other parts of the integration.
  5. Assign the user to the REST Web Service User role.
  6. Click Add.

Create users and groups to receive notifications

This integration uses SCOM notification subscriptions to associate particular alerts to users and groups in SCOM. These users and groups must also be present in xMatters (with the same ID) to be targeted for notifications.

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

Import the communication plan

The next step is to import the communication plan.

To import the communication plan:

  1. In xMatters, click the Developer tab, and then click Import Plan.
  2. Click Choose File, and then locate the plan you downloaded from this article (the .zip file within the .zip file).
  3. Click Import Plan.
    • Once the import is finished, the plan should be automatically enabled. If it isn't, click Plan Disabled to enable the plan.
  4. Click the Edit drop-down list for the plan, and select Access Permissions.
  5. Add the integration user you created above, and then click Save Changes.
  6. In the Edit drop-down list for the plan, select Forms.
  7. Click the Web Service drop-down list for the SCOM Alert form, and then select Sender Permissions.
  8. Add the integration user you created above, and then click Save Changes.

Configure inbound integrations

You need to configure the authentication and retrieve the URL for the inbound integration. You'll use the URL when you configure the Integration Agent.

To configure an inbound integration:

  1. In the Integration Builder, expand the list of inbound integrations.
  2. Click the name of the integration to view its details.
  3. Under the Select authentication method step, make sure the authentication is set to Basic 
    • If it is not, select Basic then click Update Inbound Integration.
  4. Scroll down to the bottom of the page, and click Copy URL beside the field (you need this later to configure the Integration Agent):

CopyURL.jpg

Create a web service user

This integration requires a web service user with specific permissions in xMatters to receive user responses and notifications about event status changes for the Integration Agent. ("Web service users" are a specific type of user in xMatters that can work with the SOAP web services used by the Integration Agent; this means you can't just use a regular user and assign them a specific role or permission – you have to create a dedicated user.)

To set up a web service user:

  1. In xMatters, click the Users tab, and then, in the menu on the left side of the page, click Add Web Service User.
  2. On the Add Web Service User page, enter a User ID.
  3. In the Denied Web Services list, locate and select the following web service, and then click Add:
    • Register Integration Agent
    • Receive APXML
    • Send APXML
  4. Enter a password for the new web service user.
  5. Click Save.

Configure the xMatters Integration Agent

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

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.

Install and configure the integration files

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

Note: As usual for our Integration Agent documentation, <IAHOME> refers to the installation folder of the Integration Agent on your system.

To install and configure the integration files:

  1. Within the extracted integration archive, navigate to \components\integration-agent\integrationservices, and copy the entire contents of this folder to the <IAHOME>\integrationservices installation directory of the Integration Agent.
  2. Open the <IAHOME>\conf\IAConfig.xml file and add the following line to the "service-configs" section:
<path>applications/msscom/msscom.xml</path>
  1. Save and close the file.
  2. Open the <IAHOME>\integrationservices\applications\msscom\msscom-config.js file and add or set the values for the following variables:
WEB_SERVICE_URL The inbound integration URL of the communication plan form.
XMATTERS_DOMAIN The URL of your xMatters On-Demand instance.
CALLBACKS The default for this is null. You can configure it to accept supported outbound integrations (callbacks). However, we recommend that you configure these in the xMatters web user interface, rather than in this file.
INITIATOR The User ID of the integration user you created in xMatters.
PASSWORD Path and filename of the password file containing the encrypted integration user's password.
DEDUPLICATOR_FILTER_NAME The deduplication filter to use for this integration (this must be set to "msscom").
SCOM_EXECUTABLE_PATH The path to the xMatters SCOM executable, relative to the <IAHOME> directory.
SCOM_USERNAME The username of the SCOM user that will access, change the status of and update Alerts.
SCOM_PASSWORD Path and filename of the password file containing the encrypted SCOM user's password.
SCOM_USE_SIMPLE_LOGIN When set to true, the integration uses only the SCOM_SERVER_NAME to create a connection to the Microsoft Enterprise Management Group.
SCOM_SERVER_NAME Server name for the server running SCOM
SCOM_DOMAIN Domain on which the server that the Alerts will be queried from is running.
SCOM_DEBUG_LOGGING_ENABLED When set to true, debug logging information is logged into <IA_HOME>\integrationservices\applications\msscom\log\
USE_XMATTERS_STATUS When set to true, SCOM alerts are set to the "sentToxMattersResolutionStateID" status (see below) after an event is created. 
ALERT_SENT_MESSAGE The message added to the alert history in SCOM when an xMatters event is created for the alert.
XMATTERS_HISTORY_COMMENT_PREFIX The prefix that is added to the history comments for xMatters updates to an alert.
acknowledgedResolutionStateID The ResolutionState ID used when the "Acknowledge" response is selected in xMatters.
closeResolutionStateID The ResolutionState ID used when the "Closed" response is selected in xMatters.
sentToxMattersResolutionStateID The ResolutionState ID used when the alert is sent to xMatters. This is only used if the USER_XMATTERS_STATUS (see above) is set to true.
  1. Save and close the file.
  2. Configure the password files and deduplication (if required).
  3. Restart the Integration Agent.

Set the password files

This integration includes encrypted files, located in the <IAHOME>\conf folder, that store the passwords for the integration user and the SCOM user. You need to update (or create) the files with the correct passwords for these users:

Note: If you store the passwords with a different file name or in a different location, make sure you update the <IAHOME>/integrationservices/applications/msscom/msscom-config.js file with the correct name and path.

To configure the integration user password:

  1. Open a command prompt and navigate to <IAHOME>\bin.
  2. Run the following command, where <new_password> is the password for the INITIATOR (integration user) specified in the msscom-config.js file, and <old_password> is the existing password (the default password for a newly installed integration is "password"):
iapassword.bat --new <new_password> --old <old_password> --file conf/.initiatorpasswd
  1. Next, run the following command, where <new_password> is the password for the SCOM user specified in the msscom-config.js file, and <old_password> is the existing password (the default password for a newly installed integration is "password"):
iapassword.bat --new <new_password> --old <old_password> --file conf/msscompasswd.pwd

For more information about working with the iapassword command, and creating password files, refer to the xMatters Integration Agent Guide.

Configure deduplication

The integration package includes a filter that engages the Integration Agent's filtering and suppression module to suppress duplicate events (also know as deduplication). This can help avoid disruption of traffic due to event floods (a potential issue with improperly configured management systems).

The deduplicator is installed into the <IAHOME>\conf folder, and is configured by default to suppress up to 100 duplicate events for two minutes. You can configure the filter to extend the time period in which an event is considered to be a duplicate, the number of events within that period, and the tokens or properties that xMatters uses to determine what makes the event unique.

To enable deduplication:

  1. Navigate to the <IAHOME>/conf directory.
  2. If you have an existing deduplicator-filter.xml file in this folder, create a backup version in a separate location.
  3. Copy the deduplicator-filter.xml file from the integration-agent/conf folder in the extracted integration archive into the <IAHOME>/conf directory.
  4. If you backed up an existing deduplicator file, merge the contents of your backup with the newly installed <IAHOME>/conf/deduplicator-filter.xml file: open both files in a text editor, and then copy the <filter> node from the backup file into the new deduplicator file after the last </filter> node.
  5. Save and close the file. 
  6. Restart the Integration Agent.

For more information about the deduplication filter and the available settings, refer to the "Filtering and Suppression" section in the xMatters Integration Agent Guide

Configure SCOM

Now that you've configured xMatters to integrate with your system, it's time to configure SCOM to integrate with xMatters. This requires you to configure the following components in SCOM:

  • Notification channels
  • Notification subscribers
  • Notification subscriptions
  • Add/update resolution status

Configure notification channels

The notification channels define how SCOM delivers the information to xMatters, which attributes of the event are sent, and when to remove the event from xMatters.

To set the notification channels:

  1. In Administration pane in SCOM, expand Notifications, and then click Channels.
  2. Right-click in the Channels pane, and then select New Channel.
  3. In the Command Notification Channel dialog box type Send Alert via xMatters in the Channel Name field, and then click Next.
  4. In the Full path of the command file field, type the path to the APClient.bin.exe file in the xMatters Integration Agent installation folder (the default location is <IAHOME>\bin\APClient.bin.exe).
  5. In the Command line parameters field, type the following:
--map-data "applications|msscom" "add" "$Data/Context/DataItem/AlertId$" "$Data/Context/DataItem/AlertName$" "$Data/Context/DataItem/TimeRaisedLocal$" "$Target/ManagementGroup/Name$" "$Data/Recipients/To/Address/Address$" "$Data/Context/DataItem/Priority$" "$Data/Context/DataItem/Severity$" "$Data/Context/DataItem/ManagedEntityDisplayName$" "$Data/Context/DataItem/ResolutionState$"

Note: You can copy and paste the above command from this article into the Command line parameters field, but first you need to paste the text into a plain text file and remove any line breaks or other formatting. You can then copy the command from the text file and paste it into the SCOM field.

  1. In the Startup folder for the command line field, enter your <IAHOME> directory.
  2. Click Finish, and then click Close.
  3. Repeat steps 2 through 4 to add another notification channel with the name Delete Closed Alerts From xMatters.
  4. In the Command line parameters field, type the following:
--map-data "applications|msscom" "del" "$Data/Context/DataItem/AlertId$"
  1. In the Startup folder for the command line field, type enter your <IAHOME> directory.
  2. Click Finish, and then click Close.

Configure notification subscribers

SCOM notification subscribers allow you to specify who should be notified, and on which devices. You must configure subscribers to use the xMatters command channels, and set the xMatters recipient (the target user or group) as the delivery address.

Note: In the SCOM interface, selecting some options will lock other fields in the dialog box, preventing you from making necessary changes. The following steps indicate the best way to prevent this, and describe which options to set first so that other required settings are not locked before you can modify them.

To set the notification subscriber:

  1. In the Administration pane, under Notifications, click Subscribers.
  2. Right-click in the Subscribers pane, and then select New Subscriber.
  3. In the Notification Subscriber Wizard, in the Subscriber Name field, type xMatters, and then click Next.
  4. On the Schedule Notifications page, select Always send notifications, and then click Next.
  5. On the Subscriber Addresses page, click Add.
  6. On the Describe the Subscriber Address page, type xMattersSCOMGroup in the Address name field, and then click Next.
    • This example uses the group xMattersSCOMGroup as an xMatters recipient. Replace xMattersSCOMGroup here and in step 7 with the name of the user or group you want to use.
  7. In the Delivery address for the selected channel field, type xMattersSCOMGroup.
  8. In the Channel Type drop-down list, select Command.
  9. In the Command Channel field, select Send Alert to xMatters, and then click Next.
  10. Click Finish to complete the Schedule Notifications configuration.
  11. Click Finish, and then click Close.

To set the closed alerts subscriber:

  1. Right-click in the Subscribers pane, and then select New Subscriber.
  2. The Schedule Notifications page, select Always send notifications, and then click Next.
  3. On the Subscriber Addresses page, click Add.
  4. On the Describe the Subscriber Address page, type xMattersClose in the Address name field, and then click Next.
    • This example uses the group xMattersClose as an xMatters recipient. Replace xMattersClose with the name of the user or group you want to use.
  5. In the Channel Type drop-down list, select Command.
  6. In the Command Channel field, select Delete Closed Events From xMatters and then click Next.
  7. Click Finish to complete the Schedule Notifications configuration.
  8. Click Finish, and then click Close.

Configure notification subscriptions

Once you have created the command channel and configured the subscribers, you can set up a subscription to allow xMatters to subscribe to SCOM alerts.

You can create subscriptions for many different kinds of alerts. The following instructions describe how to subscribe with two criteria (severity and resolution state) as a way of demonstrating the process, and how to configure a subscription that will delete the corresponding event in xMatters when an alert is closed.

To configure a "new" notification subscription:

  1. In the Administration pane, under Notifications, click Subscriptions.
  2. Right-click in the Subscriptions pane, and then select New Subscription.
  3. On the Create Notification Subscription page, in the Subscription name field, type xMattersSubscription, and then click Next.
  4. On the Criteria page, use the Conditions and Criteria description boxes to create a subscription that notifies on all alerts with a resolution state of "New" and a Warning or Critical severity.
    • The Criteria description field should resemble the following:

NotifyNew.png

  1. Click Next.
  2. On the Subscribers page, add the “xMatters” subscriber you defined in the previous section, and then click Next.
  3. On the Channels page, add the xMatters command channel you already defined, and then select the Send notifications without delay option.
  4. Click Next.
  5. Click Finish, and then click Close.

To configure a "delete on close" notification subscription:

  1. Right-click in the Subscriptions pane again, and select New Subscription.
  2. On the Create Notification Subscription page, in the Subscription name field, type Delete xMatters events when alerts are closed, and then click Next.
  3. On the Criteria page, use the Conditions and Criteria description boxes to create a subscription that notifies on all alerts with a resolution state of "Closed" and a Warning or Critical severity (this allows xMatters to terminate events when they are resolved).
    Note: If the criteria other than the resolution state do not match the criteria of the xMattersSubscription subscription, xMatters may attempt to terminate events that it may not have received.
    • The Criteria description field should resemble the following:

NotifyClosed.png

  1. Click Next.
  2. On the Subscribers page, add the “xMattersClose” subscriber you defined in the previous section, and then click Next.
  3. On the Channels page, add the Delete Closed Alerts From xMatters command channel you already defined, and then select the Send notifications without delay option.
  4. Click Next.
  5. Click Finish, and then click Close.

Configure alert resolution settings

You need to make sure that SCOM has resolution state IDs that match the xMatters response options. Generally this means adding a new resolution state  for the Acknowledge response and confirming that the ID in the msscom-config.js matches the Closed ID in your SCOM setup. 

You might also need to configure a new resolution state for the Sent to xMatters status if the USE_XMATTERS_STATUS variable is set to true

To add new resolution states:

  1. In the Administration pane, click Settings, and then double-click Alerts.
  2. In the Global Management Group Settings dialog box, on the Alert Resolution States tab, click New.
  3. In the Resolution state name field, type a name that matches the new resolution state (for example, Acknowledge).
  4. In the ID field, type the resolution state ID that matches the state name (for example, for Acknowledge, enter 101).
  5. Click Save.
  6. Repeat steps 2 to 5 to add any additional resolution states.
  7. Click OK.

Use the integration

The example in this section uses a forced IP address conflict to illustrate how an alert is sent through xMatters to a user’s device, and how xMatters and SCOM process the user’s response, targeting an example group name "xMattersSCOMGroup" – replace this with the group you set up, making sure you have access to a device belonging to a user who is part of this group so you can receive the notification and respond.

Trigger a notification

To trigger a notification:

  1. Using the Windows Local Area Connection Properties dialog, force an IP conflict between two computers that SCOM is monitoring. For example, assign the SCOM server’s IP address to another machine on the network.
    • The alert is created in SCOM.
  2. SCOM passes the alert into xMatters.
    • The Alert Properties dialog box displays the details of the alert, and the Status is updated to "Sent to xMatters".

Respond to a notification

On a device with the xMatters mobile app, you can respond to the message simply by tapping Respond, and then tapping one of the response choices. Other devices use similar methods.

SCOM_xMattersApp.png

View the response results

After responding to the notification (for example, with Acknowledge), xMatters updates the event in SCOM. You can view the results of the response in SCOM:

SCOM_History.png

The Active Alerts pane updates the Resolution State to Acknowledged and the History tab displays the sequence of notifications and responses.

Troubleshooting

For those familiar with previous versions of the integration, the following functionality has been deprecated and is not available in this integration:

  • No FYI flag is available and the integration does not currently support FYI notifications
  • No failsafe functionality has been implemented as this is not technically possible with integrations based on communication plans.

Enable logging

You can temporarily enable low-level logging for the integration to help with troubleshooting. We recommend you turn this off after you're done troubleshooting to make sure it doesn't impact day-to-day performance. 

To enable logging:

Open the <IAHOME>\integrationservices\msscom\msscom-config.js file in a text editor and set the debugLogging parameter to "true".

When set to true, debug logging information is logged into:

<IA_HOME>\integrationservices\applications\msscom\log\

Extend and optimize your integration

You can use the following tips to customize your integration to better suit your deployment.

Change the human-readable text is used for values

You can change the text associated with the SCOM integer values for resolution state, severity, priority, and status. 

To change the human-readable text sent to xMatters for the numeric values:

  1. Open the <IAHOME>\integrationservices\applications\msscom\msscom-config.js file and change the following variables to match the text you want to appear for the numeric values:
    • READABLE_SEVERITY_MAP
    • READABLE_PRIORITY_MAP
    • READABLE_STATUS_MAP
    • READABLE_STATUS_MAP[acknowledgedResolutionStateID.toString()]
    • READABLE_STATUS_MAP[sentToxMattersResolutionStateID.toString()]
    • READABLE_STATUS_MAP[closeResolutionStateID.toString()]

For example, to re-map "1": "Warning" to read "Caution" when it appears in xMatters, change the variable as follows:

var READABLE_SEVERITY_MAP = {
"0": "Information",
"1": "Caution",
"2": "Critical"
};
  1. Save and close the file.
  2. Restart the Integration Agent.

Adding xMatters response options to the responses that update a SCOM Alert's Status and Owner

By default, only the Acknowledge response updates an Alert's Status and Owner. In previous releases, you might have seen this happen with a "Work in Progress" resolution state as well. You can change this if needed for your implementation. 

The existing "Close", "Annotate" and "Escalate" responses are handled differently and may require further customization to if you want to add these to the list.

To change which responses update an alert's status and owner:

  1. Open the <IAHOME>\integrationservices\applications\msscom\msscom-config.js file and add the additional status to the RESPONSE_STATUS_MAP variable. 
  2. Save and close the file.
  3. Restart the Integration Agent.

Download resources

 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.
Powered by Zendesk