Microsoft System Center Operations Manager (SCOM) 2012 integration for xMatters On-Demand

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

Configure SCOM 2012

Test the integration

Troubleshooting

Download resources

Introduction

This article provides installation, configuration, and implementation details when integrating xMatters On-Demand with Microsoft System Center Operations Manager 2012.

How it works

This integration uses a client-hosted integration agent, installed on the SCOM 2012 server. 

When a new SCOM 2012 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 2012.

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

  • This integration requires a SCOM 2012 user name and password.
  • This integration requires administrator access to the xMatters On-Demand web user interface; contact your Client Success Manager for assistance with the configuration.

Release Qualifications

This release has been qualified against the following software components

  • xMatters On-Demand 5.5.68 (or later)
  • xMatters integration agent 5.1.5
  • Microsoft System Center Operations Manager 2012

This integration created and supplied by Kevin Akey.

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 reference specific folders within the extracted integration archive. 

Configure xMatters

The first step in setting up your integration is to configure xMatters.

Create a REST API user

This integration requires a REST API user to authenticate REST web service calls when injecting events.

This user needs to be able to work with events, but not update administrative settings. Check with your Client Success Manager to find out which role in your deployment have the correct permissions.

Alternately, you can create a user for this integration with a dedicated "REST Web Service User" role that includes the permissions and capabilities. If this role does not exist in your deployment, your xMatters Client Success Manager can create it for you. (For detailed procedures about creating the role, see Authentication and Permissions.)

In the following example, this role is named "REST Web Service User".

To create a REST API 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 other parts of this integration.

Create users and groups that will receive notifications

This integration uses notification subscriptions to associate particular alerts to users and groups in SCOM 2012.  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 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/SCOM2012.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 NewEvent 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 REST API user you created 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 may appear twice in the drop-down menu. Ensure that you click the option just below Create Event Web Service.

To get the web service URL for the REST API, see the xMatters Web Help.

You'll need these URLs when you configure the rest of the integration.

Defining the integration service

Next, define the integration service so you can view the status of the connecting integration agents for the integration service from within xMatters On-Demand.

The integration service name must match the name specified in the the msscom.xml file installed on the integration agent.

To define an integration service:

  1. In xMatters, on the Event Domains page, click the applications event domain.
  2. On the Event Domain Details page, in the Integration Services area, click Add New.
  3. Enter the following information into the form:
    • Name: msscom
    • Description: Microsoft SCOM 2012 Integration Service
    • Path: Not required (this feature is used by a deprecated component)

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

To install the package and configure the integration agent:

  1. Within the extracted integration archive, navigate to \components\integration-agent
  2. Copy the contents of this folder to the installation directory of the integration agent: for example: C:\integrationagent-5.1.5
    • This folder is referred to as <IAHOME> in the remainder of the instructions.
  3. 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 web service URL of the communication plan form (see Accessing web service URLs, above).
REST_SERVICE_URL The REST service URL of the xMatters On-Demand instance (For information on retrieving this value for your deployment, see Web service URLs in the On-Demand help).
INITIATOR The User ID of the REST API user you created 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, refer to the xMatters integration agent guide.
CALLBACKS This is defaulted to null for outbound-only integrations but may be configured to accept supported callbacks (which are now known as outbound integration webhooks; it is recommended that you configure these in the xMatters web user interface, rather than in this file.
DEDUPLICATOR_FILTER_NAME Must be set to "msscom" for this integration.
ANNOTATE_DELIVERY Update alerts with xMatters notification delivery status
acknowledgedResolutionStateID The ResolutionState ID used when Acknowledging a Alert from xMatters
workInProgressResolutionStateID  The ResolutionState ID used when setting Work In Progress for an Alert from xMatters
sentToxMattersResolutionStateID The ResolutionState ID used when the Alert is sent to xMatters
 closeResolutionStateID  The ResolutionState ID used when the Alert is Closed
userName The User ID of the SCOM user that is accessing the Alert, changing the status and updating Alerts.
SCOM_PASSWORD Path and filename of the password file containing the encrypted SCOM user's password.
For more information about creating this file, refer to the xMatters integration agent guide.
simpleLogin When set to true, will use only the serverName to create a connection to the Microsoft Enterprise Management Group
serverName Server name for the server running SCOM
domain  Domain from which SCOM Alerts will be queried
debugLogging When set to true, debug logging information will be logged into <IA_HOME>\integrationservices\applications\msscom\log\
  1. Save and close the file.
  2. Open the <IAHOME>\integrationservices\conf\deduplicator-filter.xml file and add the duplicator filter (everything from <filter name="msscom"> to and including </filter>) found in the deduplicator-filter.msscom.xml file in the same folder.
  3. Save and close the file.
  4. Restart the integration agent.

Configure SCOM 2012

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

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

Configure notification channels

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

To set the notification channels:

  1. In SCOM 2012, in the Administration pane, 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, in the Channel Name field, type Send Alert via xMatters, 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.
    • The path must include the short version of the Program Files (x86) folder; for example: C:\PROGRA~2\integrationagent\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: If you want to copy and paste the above command from this article into the Command line parameters field, paste the text into a plain text file first, and remove any line breaks and other formatting. You can then copy the command from the text file and paste it into the SCOM 2012 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 2012 notification subscribers allow users to specify who is to be notified, and on which devices. You must configure subscribers to use the xMatters command channels, and set the xMatters recipient as the delivery address. Note that the following instructions use the group “xMattersSCOMGroup” as an xMatters recipient; if you want to use a different group, replace xMattersSCOMGroup with the name of the group you want to use.

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, in the Address name field, type xMattersSCOMGroup, and then click Next.
  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, in the Address name field, type xMattersClose, and then click Next.
  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 against SCOM 2012 alerts. You can create subscriptions against different kinds of alerts; the following instructions describe how to subscribe against two criteria 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 the notification subscriptions:

  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 will notify on all new alerts of a Warning or Critical severity.
    • The Criteria description field should resemble the following:

  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.

Repeat steps 2 through 4 to create another subscription named Delete xMatters events when alerts are closed that will notify on all alerts with a resolution state of “Closed” and matching the criteria of the xMattersSubscription notification subscription; this will allow xMatters to terminate events once they are resolved. 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:

  1. On the Subscribers page, add the “xMattersClose” subscriber you defined in the previous section, and then click Next.
  2. 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.
  3. Click Next.
  4. Click Finish, and then click Close.

Configure alert resolution settings

You must add three new resolution states to account for alerts that are sent to xMatters: Acknowledged, Owned, and SentToxMatters. Note that the resolution state names and IDs described in the details below match those configured in the default integration files; if you want to use different names or IDs, you must also edit the configuration file (as described above).

To add new Alert Resolution Settings:

  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 Acknowledge.
  4. In the ID field, type 101.
  5. Click Save.
  6. Repeat steps 3 to 6 to add two more resolution states:
    • Work In Progress, with an ID of 102
    • Sent To xMatters, with an ID of 103
  7. Click OK.

Test the integration

The following sections indicate how the integration works by targeting the example group (xMattersSCOMGroup) with a notification, and reviewing how the alert is updated in SCOM 2012 with the user's response.

Trigger a notification

The example described 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 2012 process the user’s response.

To test the integration:

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

Respond to a notification

This section describes how to respond to a notification from xMatters using the xMatters mobile app.

To respond to a notification:

  1. When a notification arrives for the user, the device indicates the arrival if push notifications have been configured.
  2. Open the notification to view the details.
  3. Scroll down to review the details, and the list of possible replies.
  4. To respond to the notification, click a response choice.
    • xMatters updates the event in SCOM 2012.

View the response results

After responding to the notification, for example with Acknowledge, you can view the results of the response in SCOM 2012; 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.

Response processing

Some integrations have found responses do not work properly unless the following line is commented out in the msscom-config.js file:

CALLBACKS = null;// ["status", "deliveryStatus", "response"];

Enable SCOM Logging

It is possible to enable logging for the component that interacts with SCOM within the Integration.  

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 will be logged into:

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

        .

Download resources

 

Have more questions? Submit a request

3 Comments

  • 0
    Avatar
    Don Clark
    With a little (okay, a LOT) of help from Jeremy, I've uploaded a new version (3.0.1) with fixed code.
  • 0
    Avatar
    Anthony Matthews

    There is an issue with the 3.0 version of the integration. The call to get the alertdescription from SCOM will throw an error that says:

    Java class "[B" has no public instance field or method named "toJSON"

    The fix is to replace the following line:
    form.properties.event_description = alertDescription;

    with:
    form.properties.event_description = new String(alertDescription);

  • 0
    Avatar
    Don Clark

    Thanks Anthony! Which file is the bad line in? I'll try to get it changed and upload a working version....

Please sign in to leave a comment.
Powered by Zendesk