Microsoft SCOM

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 attached .zip file to a location on your local machine, and extract the contents. The file contains all of the components required to integrate xMatters and SCOM.

If you navigate through the folders, you will find another .zip file called scom.zip. This is the workflow, which contains pre-configured integrations, forms, properties, and messages specifically designed for SCOM. Don't extract the contents of the scom.zip file! You'll import it directly into xMatters in the next section of instructions.

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.

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

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.

• To create a new group, see Create a new group.
• To create a new user, see Add a new user.

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

The next step is to import the workflow. You can find the workflow scom.zip file in the extracted archive you downloaded.

1. In xMatters, click the Workflows tab, and then click Import.
2. Go to the location of the extracted xM-MS-SCOM folder.
3. Go to components > xmatters and select the scom.zip file.
4. Click Import Workflow.
   • Once the import is finished, the workflow should be automatically enabled. If it isn't, click the Disabled toggle to enable it.
5. Click the gear icon beside the workflow, and select Editor Permissions.

6. Add the integration user, and then click Save.
7. Click the workflow name to open the Forms tab.
8. For the first form in the list, click the Web Service drop-down, and then select Sender Permissions.

9. Add the integration user, and then click Save Changes.

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 Save.
4. Scroll down to the bottom of the page, and click Copy beside the field (you need this later to configure the Integration Agent):

This integration requires a web service user with specific permissions in xMatters to receive user responses and notifications about alert 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.

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>

3. Save and close the file.
4. Open the <IAHOME>\integrationservices\applications\msscom\msscom-config.js file and add or set the values for the following variables:

5. Save and close the file.
6. Configure the password files and deduplication (if required).
7. Restart the Integration Agent.

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:

• "initiatorpasswd" stores the password for the integration user
• "msscompasswd" stores the password for the SCOM user

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

3. 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

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

The integration package includes a filter that engages the Integration Agent's filtering and suppression module to suppress duplicate alerts (also know as deduplication). This can help avoid disruption of traffic due to alert 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 alerts for two minutes. You can configure the filter to extend the time period in which an alert is considered to be a duplicate, the number of alerts within that period, and the tokens or properties that xMatters uses to determine what makes the alert 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.

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

To set the notification channels:

1. In the 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.

6. In the Startup folder for the command line field, enter your <IAHOME> directory.
7. Click Finish, and then click Close.
8. Repeat steps 2 through 4 to add another notification channel with the name Delete Closed Alerts From xMatters.
9. In the Command line parameters field, type the following:

--map-data "applications|msscom" "del" "$Data/Context/DataItem/AlertId$"

10. In the Startup folder for the command line field, type enter your <IAHOME> directory.
11. Click Finish, and then click Close.

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.

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 alert 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:

5. Click Next.
6. On the Subscribers page, add the “xMatters” subscriber you defined in the previous section, and then click Next.
7. On the Channels page, add the xMatters command channel you already defined, and then select the Send notifications without delay option.
8. Click Next.
9. 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 alerts when 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:

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

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.

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".

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.

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:

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

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\

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"
};

var READABLE_SEVERITY_MAP = {

"0": "Information",

"1": "Caution",

"2": "Critical"

};

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

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.