Creating SCOM Connector, Subscription in Code

Microsoft System Center Operations Manager 2007 and 2012 allow developers to create their own connectors for the purpose of product integration with third-party systems. Connectors serve as notification channels for new events, which can be polled, processed, and acknowledged back to SCOM servers.

It isn’t always desirable to create connectors manually, since it is easy to make mistakes or typos. In this post we will look at how these connectors can be manipulated programmatically.

Prepare Your Project for SCOM Work

Before you can start making calls into SCOM API, you need to create a new project (I use VB.NET), reference SCOM SDK libraries, and import SCOM namespaces. For details on how to do this, refer to this post.

Anatomy of a SCOM Connector

SCOM connector objects by themselves are pretty useless – they don’t do anything until you create a subscription. Subscription(s) are used as filters of sorts, that describe to SCOM what kinds of events we deem “interesting” to a given connector. So connector and subscription always go together – think of them as two sides of the same coin.

Initialize SCOM Connector

Some of these methods are marked as obsolete in the SCOM 2012 SDK, but they still work. They also work in the SCOM 2007 SDK.

First we need to create a connector, then we will add subscriptions.

Dim mg As ManagementGroup
Dim conInfo As ConnectorInfo
Dim conGuid As Guid

Try
     mg = New ManagementGroup(My.Settings.ManagementGroup)
     cfa = mg.GetConnectorFrameworkAdministration

     conInfo = New ConnectorInfo
     conGuid = My.Settings.ConnectorGUID
     conInfo.Description = My.Settings.ConnectorDescription
     conInfo.DisplayName = My.Settings.ConnectorDisplayName
     conInfo.Name = My.Settings.ConnectorName

     Try
          con = cfa.GetMonitoringConnector(conGuid)
     Catch exx As Exception
          con = cfa.Setup(conInfo, conGuid)
          con.Initialize()
     End Try

Catch ex As Exception
     'deal with anything unexpected here
End Try

First, on line 6, we open a new connection to a management group name as configured in ManagementGroup setting in this VB project. Lines 9-13 create a new object of class ConnectorInfo, which we will need to provide to SCOM in order to create a new connector.

Generating a GUID

Finally, on line 16 we make the call to get the existing connector using the GUID we determined to use (as configured in ConnectorGUID project setting). The GUID can be an arbitrary GUID string but you are advised to get a unique GUID by calling GUID.NewGuid method as described on MSDN, or simply by typing this command in the PowerShell:

[System.Guid]::NewGuid().Guid

Make sure to add the generated GUID to your settings or public/constant variable, to make sure that you create and then connect to the same connector as identified by this GUID.

If this is the first time you are running this code from the snippet above, line 16 will result in a runtime error, since no connectors with this GUID should exist at this point. This is why we have a Catch block, that makes two calls that actually create and initialize the new connector.

Adding Subscriptions to an Existing Connector

Still assuming that this is the first time you are running the code, you would proceed to generate a subscription as follows:

Dim subs As MonitoringConnectorSubscription
Dim config As AlertChangedSubscriptionConfiguration
Dim subname As String = My.Settings.SubscriptionName

Try
     subs = cfa.GetConnectorSubscription(subname)
Catch ex As Exception
     config = New AlertChangedSubscriptionConfiguration(AlertSubscriptionConfigurationType.Any)
     config.Criteria = My.Settings.SubscriptionCriteria
     config.PollingIntervalMinutes = My.Settings.PollingIntervalMinutes
     config.ExpirationStartTime = Now
     subs = New MonitoringConnectorSubscription(subname, con.Id, config)
     subs.DisplayName = My.Settings.SubscriptionDisplayName
     subs.Description = My.Settings.SubscriptionDescription
     cfa.InsertConnectorSubscription(subs)
Finally
     config = Nothing
     subs = Nothing
End Try

And… that’s all there is to it.

As you can see, on line 6 we are checking if subscription under the name supplied using SubscriptionName setting (line 3) already exists. If it does not, a runtime error will be thrown, and we will end up inside the Catch block. The next 4 lines set up the parameters of the new subscription, and the following 4 lines bind the new subscription with our connector and insert it into the SCOM API.

New AlertChangedSubscriptionConfiguration

A few words about this class. When you are creating a new SCOM subscription, using this class in your subscription configuration will result in all alert changes being sent to the connector. This can be good or bad, depending on what you are trying to achieve. If you want to know of ALL alert changes, this is the way to do it. If you would rather prefer alert to settle (or even auto-resolve), use New AlertNotChangedSubscriptionConfiguration class, which uses alert aging and delays alert notifications by IdleMinutes (10 minutes by default).

AlertSubscriptionConfiguration.Criteria

This subscription parameter is by far the most complicated bit that can suck up a ton of time trying to tweak it just right to fit into a particular scenario. If you make a mistake either in syntax or in logic, which last time I looked isn’t documented on MSDN, the call to save the subscription will fail with some non-descriptive error, and connector will not work.

One of the ways to get an idea of how this XML construct looks, try creating a simple connector/subscription manually, and then query for it directly in the database, or simply Google around.

To give you an idea, Criteria string should look somewhat similar to the following:

<SimpleExpression>
   <ValueExpression>
      <Property>ResolutionState</Property>
   </ValueExpression>
   <Operator>NotEqual</Operator>
   <ValueExpression>
      <Value>255</Value>
   </ValueExpression>
</SimpleExpression>

In this example above, the connector/subscription will catch all alert updates as long as the affected alert state is not equal to 255 (closed).

PollingIntervalMinutes

This parameter specifies, how often should connector poll SCOM SDK internally to catch alert events matching your subscription. You should not set this parameter to less than 1 minute, since SCOM has internal delay of about 30 seconds between the actual alert event and its first availability to the connector space.

ExpirationStartTime

To me, this property name is somewhat counter-intuitive. What it really does is allows you to specify a point in time, from which to catch alert changes. Set ExpirationStartTime = Now() to start monitoring your SCOM alerts from the point of creating the subscription.

Finally

Create a new object of class MonitoringConnectorSubscription (line 12) and call InsertConnectorSubscription method (line 15) to commit. Code on line 12 establishes the link between this subscription and the connector we created earlier.

Leave a Reply

Your email address will not be published. Required fields are marked *

*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>