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:
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.
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).
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).
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.
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.
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.