SCOM Connector Quickstart Guide
A Starter’s Guide ToDeveloping Product Connectors
Ambrose Wong
Microsoft Corporation
December 07
Table of Contents
Overview
Sample Outbound Connector
Development Platform
Step-By-Step Instructions
Create an Outbound Connector
Create An Application To Query and Close Alerts
Install the Outbound Connector
Simulate an Alert Scenario
Appendix A: About Knowledge Articles
Adding Your Own Company Knowledge Article
Appendix B: Operations Manager 2007 Command Shell
Getting Details from an Alert
Query For Alert Properties
Query for Monitor
Query for Monitoring Rule
Query for Management Pack
References
Blogs
Newsgroups
Overview
A connector is a custom service or program that allows System Center Operations Manager 2007 (SCOM) to communicate with external systems. For example, you can create a connector that sends Operations Manager alerts to an application that tracks the alerts. The application can use the connector to send an update to Operations Manager, indicating that the alert has been resolved.
You can develop a custom connector by using the Operations Manager Connector Framework (OMCF). The OMCF provides methods and types that you can use to initialize and manage a connector.
The following illustration shows the architecture of the SDK, and where OMCF positions.
As a quickstart guide, this document focuses ondeveloping a sample outbound connector. You can easily use the same techniques to develop other types of SDK client applications.
Sample Outbound Connector
In the diagram below, an outbound connector can send Operations Manager alerts to external systems for alert tracking. Alerts closed by external systems can update Operations Manager to reflect the change of alert state.
Development Platform
The samples in this document are developed and tested on the following platforms:
- Windows Server 2003 Enterprise Edition 32-bit (x86) with SP2, Active Directory and Internet Information Services 6.0 enabled
- System Center Operations Manager 2007
- Microsoft Windows Server 2000/2003 Internet Information Services Management Pack
- Visual Studio 2005 Team Suite with SP1
- SQL Server 2005 Enterprise Edition with SP2
- Windows Powershell 1.0
Step-By-Step Instructions
This section contains step-by-step instructions to produce a simulated outbound connector scenario where an outbound connector subscribes to and receives alerts. An accompanying application is used to close the alerts.
Note that the samples are implemented as simplified C# console applications. In real settings the connector is usually implemented as a service with more sophisticated error handling and event logging.
Also note the following:
- The connector’s alert subscriptions can be administered through Operations Manager console to specify subscription groups, targets, and criteria. They can also be administered programmatically through Operations Manager SDK for more granular control.
- Operations Manager polls for alerts every 30 seconds. The connector’s alert subscriptions are used to mark the alerts for forwarding.
- The connector polls for alerts at a set interval (30 seconds in the sample). Once alerts are retrieved from a poll, the connector can further forward them to external systems for processing. Each alert has a unique AlertId identifier.
- The connector can optionally set application specific TicketId and CustomField# values for the alert.
Create an Outbound Connector
Base on the sample fromHow to Create Outbound Connectors, create a C# console application called TestConn with the code below, with reference to the following assemblies under C:\Program Files\System Center Operations Manager 2007\SDK Binaries:
Microsoft.EnterpriseManagement.OperationsManager.dll
Microsoft.EnterpriseManagement.OperationsManager.Common.dll
using System;
using Microsoft.EnterpriseManagement;
using Microsoft.EnterpriseManagement.ConnectorFramework;
using Microsoft.EnterpriseManagement.Common;
using System.Collections.ObjectModel;
using System.Threading;
namespace OutboundConnector
{
class Program
{
static void Main(string[] args)
{
ManagementGroup mg = new ManagementGroup("localhost");
ConnectorFrameworkAdministration cfAdmin = mg.GetConnectorFrameworkAdministration();
Guid connectorGuid = new Guid("{6A1F8C0E-B8F1-4147-8C9B-5A2F98F10003}"); // Or create/use your own Guid.
MonitoringConnector connector;
try
{
if (args.Length == 1)
{
if (args[0] == "InstallConnector")
{
ConnectorInfo info = new ConnectorInfo();
info.Description = "Sample connector";
info.DisplayName = "Sample connector";
info.Name = "Sample connector";
connector = cfAdmin.Setup(info, connectorGuid);
connector.Initialize();
Console.WriteLine("Created {0} with ID: {1}", connector.Name, connector.Id);
}
else if (args[0] == "UninstallConnector")
{
connector = cfAdmin.GetMonitoringConnector(connectorGuid);
ReadOnlyCollection<MonitoringConnectorSubscription> subscriptions;
subscriptions = cfAdmin.GetConnectorSubscriptions();
foreach (MonitoringConnectorSubscription subscription in subscriptions)
{
if (subscription.MonitoringConnectorId == connectorGuid)
{
cfAdmin.DeleteConnectorSubscription(subscription);
}
}
connector.Uninitialize();
cfAdmin.Cleanup(connector);
Console.WriteLine("Connector removed.");
}
return;
}
connector = cfAdmin.GetMonitoringConnector(connectorGuid);
while (true)
{
ReadOnlyCollection<ConnectorMonitoringAlert> alerts;
alerts = connector.GetMonitoringAlerts();
if (alerts.Count > 0)
{
connector.AcknowledgeMonitoringAlerts(alerts);
}
int i = 1;
foreach (ConnectorMonitoringAlert alert in alerts)
{
// Here you can send the alert to the other management system.
Console.WriteLine("#{0} Alert received on {1}", i.ToString(), DateTime.Now);
Console.WriteLine("> Id: {0}", alert.Id.ToString());
Console.WriteLine("> Category: {0}", alert.Category.ToString());
Console.WriteLine("> ConnectorId: {0}", alert.ConnectorId.ToString());
Console.WriteLine("> ConnectorStatus: {0}", alert.ConnectorStatus.ToString());
Console.WriteLine("> RepeatCount: {0}", alert.RepeatCount.ToString());
Console.WriteLine("> ResolutionState: {0}", alert.ResolutionState.ToString());
if (!string.IsNullOrEmpty(alert.ResolvedBy))
{
Console.WriteLine("> ResolvedBy: {0}", alert.ResolvedBy.ToString());
}
Console.WriteLine("> LastModified: {0}", alert.LastModified.ToString());
Console.WriteLine("> LastModifiedByNonConnector: {0}", alert.LastModifiedByNonConnector.ToString());
Console.WriteLine("> Priority: {0}", alert.Priority.ToString());
Console.WriteLine("> Severity: {0}", alert.Severity.ToString());
Console.WriteLine("> Description: {0}", alert.Description);
Console.WriteLine("");
i = i + 1;
}
//Wait for 30 sec before checking for new alerts again.
Console.WriteLine("Sleeping for 30 seconds...");
Thread.Sleep(30 * 1000);
}
}
catch (MonitoringException error)
{
Console.WriteLine(error.Message);
}
}
}
}
Note that for the following ManagementGroup constructor in the above code:
ManagementGroup mg = new ManagementGroup("localhost");
In actual connector development you should consider which cache mode that best fit your needs. The cache mode you want to use can be specified using the ManagementGroupConnectionSettings object for the constructor.
Create An Application To Query and Close Alerts
Create a C# console application called Alertswith the code below, with reference to the following assemblies under C:\Program Files\System Center Operations Manager 2007\SDK Binaries:
Microsoft.EnterpriseManagement.OperationsManager.dll
Microsoft.EnterpriseManagement.OperationsManager.Common.dll
using System;
using Microsoft.EnterpriseManagement;
using Microsoft.EnterpriseManagement.ConnectorFramework;
using Microsoft.EnterpriseManagement.Monitoring;
namespace Alerts
{
class Program
{
static void Main(string[] args)
{
if (args.Length != 2)
{
Console.WriteLine("Usage: alerts [get|set] [alertid]");
return;
}
string op = args[0].ToLower();
if ((op != "get") & (op != "set"))
{
Console.WriteLine("First parameter needs to be either 'get' or 'set'.");
return;
}
if (args[1].Length != 36)
{
Console.WriteLine("Second parameter needs to be an alert id guid in the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.");
return;
}
try
{
ManagementGroup mg = new ManagementGroup("localhost");
ConnectorFrameworkAdministration cfAdmin = mg.GetConnectorFrameworkAdministration();
MonitoringAlert alert = mg.GetMonitoringAlert(new Guid(args[1]));
ManagementPack mp;
if (alert.IsMonitorAlert)
{
mp = mg.GetMonitor(alert.ProblemId).GetManagementPack();
}
else
{
mp = mg.GetMonitoringRule(alert.MonitoringRuleId).GetManagementPack();
}
Console.WriteLine("> Management Pack Id: {0}", mp.Id.ToString());
Console.WriteLine("> Id: {0}", alert.Id.ToString());
Console.WriteLine("> Category: {0}", alert.Category.ToString());
Console.WriteLine("> ConnectorId: {0}", alert.ConnectorId.ToString());
Console.WriteLine("> ConnectorStatus: {0}", alert.ConnectorStatus.ToString());
Console.WriteLine("> RepeatCount: {0}", alert.RepeatCount.ToString());
Console.WriteLine("> ResolutionState: {0}", alert.ResolutionState.ToString());
if (!string.IsNullOrEmpty(alert.ResolvedBy))
{
Console.WriteLine("> ResolvedBy: {0}", alert.ResolvedBy.ToString());
}
Console.WriteLine("> LastModified: {0}", alert.LastModified.ToString());
Console.WriteLine("> LastModifiedByNonConnector: {0}", alert.LastModifiedByNonConnector.ToString());
Console.WriteLine("> Priority: {0}", alert.Priority.ToString());
Console.WriteLine("> Severity: {0}", alert.Severity.ToString());
Console.WriteLine("> Description: {0}", alert.Description);
if (op == "set")
{
Console.WriteLine("Setting ResolutionState to 255.");
alert.ResolutionState = 255;
alert.Update("Alert closed.");
}
}
catch (Exception e)
{
Console.WriteLine(e.Message);
}
}
}
}
Install the Outbound Connector
Run the following at the cmd prompt to install the outbound connector.
TestConn InstallConnector
In Operations Console, you should see the connector installed as "Sample connector".
Right-click on Sample connector and select Properties. You should see the Properties dialog box as shown below.
Click the "Add…" button to add a subscription for the connector.
In the General tab, put "Test" for both Subscription Name and Description.
In the Groups tab, select all groups.
In the Targets tab, select "Forward alerts from targets are automatically, including targets in Management Packs imported in the future."
In the Criteria tab, select the following:
- Error for Alerts of any of checked severity
- High, Medium, and Low for Priority
- New for Resolution State
- All items in Category
Click the Update button to save the changes. You should now see Test listed in the Subscriptions list.
Run the following at the cmd prompt to start polling for alerts every 30 seconds.
TestConn
Leave TestConn running and the cmd prompt window open.
Simulate an Alert Scenario
Go to Internet Information Services (IIS) Manager from Administrative Tools, and stop the Default Web Site.
In Operations Console, go to Monitoring tab and select Active Alerts. After a short period you should see the alert about the stopped default web site.
At the cmd prompt where TestConn is running, you should see the same alert as received by the connector:
#1 Alert received on 12/14/2007 1:46:55 PM
> Id: 3a07c24d-a13c-43b3-be44-f6cab6ecffb3
> Category: PerformanceHealth
> ConnectorId: 6a1f8c0e-b8f1-4147-8c9b-5a2f98f10003
> ConnectorStatus: Pending
> RepeatCount: 0
> ResolutionState: 0
> LastModified: 12/14/2007 5:46:19 AM
> LastModifiedByNonConnector: 12/14/2007 5:46:19 AM
> Priority: Low
> Severity: Error
> Description: The Internet Information Services Web Site named W3SVC/1 is unav
ailable as the site has been stopped.
In the OperationsManager database you can see the alert in the Alert table:
Note the AlertId and run the following command at the cmd prompt (substitute the alert id with the one in your environment).
alerts get 3a07c24d-a13c-43b3-be44-f6cab6ecffb3
You should see an output similar to the following:
> Management Pack Id: 7a920be5-d53c-fa2d-07a8-b415265e95b0
> Id: 3a07c24d-a13c-43b3-be44-f6cab6ecffb3
> Category: PerformanceHealth
> ConnectorId: 6a1f8c0e-b8f1-4147-8c9b-5a2f98f10003
> ConnectorStatus: SuccessfullyForwarded
> RepeatCount: 0
> ResolutionState: 0
> LastModified: 12/14/2007 5:46:19 AM
> LastModifiedByNonConnector: 12/14/2007 5:46:19 AM
> Priority: Low
> Severity: Error
> Description: The Internet Information Services Web Site named W3SVC/1 is unav
ailable as the site has been stopped.
Note that ConnectorStatus is SuccessfullyForwarded. ResolutionState is 0 (New).
Now run the following command at the cmd prompt to close the alert.
alerts set 3a07c24d-a13c-43b3-be44-f6cab6ecffb3
Run the following command at the cmd prompt to check the status again.
alerts get 3a07c24d-a13c-43b3-be44-f6cab6ecffb3
You should see an output similar to the following from the "get" operation:
> Management Pack Id: 7a920be5-d53c-fa2d-07a8-b415265e95b0
> Id: 3a07c24d-a13c-43b3-be44-f6cab6ecffb3
> Category: PerformanceHealth
> ConnectorId: 6a1f8c0e-b8f1-4147-8c9b-5a2f98f10003
> ConnectorStatus: Pending
> RepeatCount: 0
> ResolutionState: 255
> ResolvedBy: TESTDOMAIN\Administrator
> LastModified: 12/14/2007 6:01:13 AM
> LastModifiedByNonConnector: 12/14/2007 6:01:13 AM
> Priority: Low
> Severity: Error
> Description: The Internet Information Services Web Site named W3SVC/1 is unav
ailable as the site has been stopped.
Note that ConnectorStatus is now Pending, with ResolutionState set to 255 (Closed) and ResolvedBy set to the credential that was used to connect to Operations Manager.
In the cmd prompt where TestConn is running, you should also see an output similar to the following notifying that the alert is closed:
#1 Alert received on 12/14/2007 2:02:02 PM
> Id: 3a07c24d-a13c-43b3-be44-f6cab6ecffb3
> Category: PerformanceHealth
> ConnectorId: 6a1f8c0e-b8f1-4147-8c9b-5a2f98f10003
> ConnectorStatus: Pending
> RepeatCount: 0
> ResolutionState: 255
> ResolvedBy: TESTDOMAIN\Administrator
> LastModified: 12/14/2007 6:01:13 AM
> LastModifiedByNonConnector: 12/14/2007 6:01:13 AM
> Priority: Low
> Severity: Error
> Description: The Internet Information Services Web Site named W3SVC/1 is unav
ailable as the site has been stopped.
Since the alert is closed, you should see the alert disappear from Operations Console’s Active Alerts list.
Run Alerts with "get" operation again, and you should see an output similar to the following:
> Management Pack Id: 7a920be5-d53c-fa2d-07a8-b415265e95b0
> Id: 3a07c24d-a13c-43b3-be44-f6cab6ecffb3
> Category: PerformanceHealth
> ConnectorId: 6a1f8c0e-b8f1-4147-8c9b-5a2f98f10003
> ConnectorStatus: SuccessfullyForwarded
> RepeatCount: 0
> ResolutionState: 255
> ResolvedBy: TESTDOMAIN\Administrator
> LastModified: 12/14/2007 6:01:13 AM
> LastModifiedByNonConnector: 12/14/2007 6:01:13 AM
> Priority: Low
> Severity: Error
> Description: The Internet Information Services Web Site named W3SVC/1 is unav
ailable as the site has been stopped.
Note that the ConnectorStatus is now set to SuccessfullyForwarded, meaning the connector has successfully processed the notification.
The test scenario is now complete.
Appendix A: About Knowledge Articles
A product knowledge article is a knowledge articlethat resides in a sealed management pack. A company knowledge article resides in an unsealed management pack.
Knowledge articles are tied to monitors or monitoring rules. Below is a sample code fragment that demonstrates how you can get all knowledge articles that tie to an alert’s monitor. For monitoring rules, use alert.MonitoringRuleId instead of alert.ProblemId.
ReadOnlyCollection<MonitoringKnowledgeArticle> kbs = mg.GetMonitoringKnowledgeArticles(alert.ProblemId);
foreach (MonitoringKnowledgeArticle kb in kbs)
{
Console.WriteLine("KB ID: {0}", kb.Id.ToString());
Console.WriteLine("KB ElementReference: {0}", kb.ElementReference.ToString());
Console.WriteLine("KB LanguageCode: {0}", kb.LanguageCode.ToString());
Console.WriteLine("KB Status: {0}", kb.Status.ToString());
Console.WriteLine("KB Visible: {0}", kb.Visible.ToString());
if (!string.IsNullOrEmpty(kb.MamlContent))
Console.WriteLine("KB MAML: {0}", kb.MamlContent.ToString());
if (!string.IsNullOrEmpty(kb.HtmlContent))
Console.WriteLine("KB HTML: {0}", kb.HtmlContent.ToString());
Console.WriteLine("MP ID: {0}", kb.GetManagementPack().Id.ToString());
Console.WriteLine("MP FriendlyName: {0}", kb.GetManagementPack().FriendlyName.ToString());
Console.WriteLine("MP DisplayName: {0}", kb.GetManagementPack().DisplayName.ToString());
Console.WriteLine("MP Name: {0}", kb.GetManagementPack().Name.ToString());
}
The output from the above code fragment shows the product knowledge article for the Default Web Site stopped alert from the sample outbound connector scenario.
KB ID: 6c4a6080-3fe1-1e9f-717c-15fb118c92d3
KB ElementReference: ManagementPackElementUniqueIdentifier=ce89d4d4-8264-8c51-5c
d9-a1ff0e314cdd
KB LanguageCode: ENU
KB Status: Unchanged
KB Visible: True
KB MAML: <maml:section xmlns:maml="
aml:title>Summary</maml:title<maml:para>This monitor checks the status of the I
IS Web sites. If you receive an alert from this monitor, action is required in o
rder to bring the Web site back to an operational state.</maml:para<maml:para /
<maml:para>Operational States:</maml:para<maml:para>An IIS Web site can be eit
her in a "Running" or "Not Running" operational state.</maml:para<maml:para /<
/maml:section<maml:section xmlns:maml="
0"<maml:title>Causes</maml:title<maml:para>An IIS Web site can stop for many r
easons, including:</maml:para<maml:list<maml:listItem<maml:para>The Web site
was stopped by an administrator</maml:para</maml:listItem<maml:listItem<maml:
para>The Web site was stopped by IIS due to one or more errors that occured duri
ng run time.</maml:para</maml:listItem<maml:listItem<maml:para>The Web site w
as improperly configured which caused it to fail or prevented it from starting.<
/maml:para<maml:para /</maml:listItem</maml:list</maml:section<maml:section
xmlns:maml="
/maml:title<maml:para>If an IIS Web site is "Not Running" you can diagnose the
issue or restart the site by taking the following actions:</maml:para<maml:list
<maml:listItem<maml:para>Check for additional Web site related alerts that mig
ht have occurred concurrently. These alerts might help better identify the reaso
n why the service entered a "Not Running" state.</maml:para</maml:listItem<mam
l:listItem<maml:para>Review the event logs on the managed computer, and correct
any underlying problems that might have caused the web site to stop unexpectedl
y.</maml:para</maml:listItem<maml:listItem<maml:para>Use the following Task t
o attempt to restart the Web Site.</maml:para<maml:para<maml:navigationLink<m
aml:linkText>Start IIS Web Site</maml:linkText<maml:uri condition="Task" href="
Microsoft.Windows.InternetInformationServices.2003.WebSite.StartWebSite.Task&
;tasktarget={$TARGET$}" uri="MOM.Console.Exe" /</maml:navigationLink</maml:par
a</maml:listItem</maml:list<maml:para /</maml:section<maml:section xmlns:ma
ml="
itle<maml:para>This monitor doesn't include any configuration settings that can
be modified.</maml:para<maml:para /</maml:section>
MP ID: 7a920be5-d53c-fa2d-07a8-b415265e95b0
MP FriendlyName: Windows Internet Information Services 2003
MP DisplayName: Windows Server Internet Information Services 2003
MP Name: Microsoft.Windows.InternetInformationServices.2003
Note that the GUID for the knowledge article’s ElementReference is the monitor or monitoring rule ID, which helps tie them together.
Adding Your Own Company KnowledgeArticle
For many organizations, having company knowledge to accompany the monitor’s or monitoring rule’s alert is desirable to achieve operational excellence with System Center Operations Manager.
Company Knowledge article can be addedthrough Operations Console:
As external system tracks alerts from Operations Manager, corresponding company-specific knowledge information about the monitor’s or monitoring rule’s alerts can be added.
Note:
You cannot modify knowledge articles that reside in sealed management pack. To add your company knowledge article, you need to save it in an unsealed management pack. Although there is a default management pack available, best practices dictate that you do not use the default management pack to store information such as company knowledge articles and overrides. You should create your own management packs to store such information.
To create a management pack, you can use Operations Console, go to Administration tab, right-click on Management Packs, and select Create Management Pack.
Once you created your unsealed management pack, you can use get-managementpack cmdlet to get the management pack’s ID. Below is a sample get-managementpack output for a management pack called Test Management Pack (refer to "Operations Manager 2007 Command Shell" for additional information on cmdlets).
>get-managementpack -name "Test.Management.Pack"
Name : Test.Management.Pack
TimeCreated : 1/4/2008 4:47:54 PM
LastModified : 1/4/2008 4:47:54 PM
KeyToken :