How to Use Discovery Data in a Management Pack
Applies To: System Center 2012 - Operations Manager
[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]
After creating a custom runtime script to collect discovery data, you must add the script to a management pack. You can add a script to any of the following management pack elements:
A data source module type—Adding a script to a data source module makes it possible for you to define configuration overrides and reuse the script in different discoveries that are defined in the management pack.
A discovery—Adding a script to a specific discovery makes it possible for you to use the script for only that discovery.
Example
In this example, a management pack creates a discovery that runs a custom script at regular intervals. The script discovers instances of an application, by checking for the existence of a specific directory, and its components, by checking for files within the directory. For more information about the script that is used in this example, see How to Create Discovery Data by Using a Script.
Note
This example shows how to add a script to a management pack by editing the management pack's XML file. For information about how to add a script to a management pack by using the Operations Console, see the System Center 2012 – Operations Manager Help.
To create the discovery, the example management pack creates the following elements:
A new data source module type, which contains the script.
A discovery, which runs the script at regular intervals.
The example management pack creates the data source module type Microsoft.Demo.Scripting.AppY.DiscoveryProvider as follows:
<ModuleTypes>
<DataSourceModuleType ID="Microsoft.Demo.Scripting.AppY.DiscoveryProvider" Accessibility="Internal">
<!-- Creating a new data source allows the author to reuse a script. -->
<!-- It also allows the author to specify overridable parameters for the script. -->
<Configuration>
<!-- This module configuration requires two elements. -->
<xsd:element name="IntervalSeconds" type="xsd:integer"/>
<xsd:element name="Computer" type="xsd:string"/>
</Configuration>
<OverrideableParameters>
<!-- This section declares what configuration elements the management pack user can override. -->
<!-- In this case, the user can override the IntervalSeconds. -->
<OverrideableParameter ID="IntervalSeconds" ParameterType="int" Selector="$Config/IntervalSeconds$"/>
</OverrideableParameters>
<ModuleImplementation>
<!-- The module is composed using a single member module. -->
<Composite>
<MemberModules>
<DataSource ID="DS" TypeID="Windows!Microsoft.Windows.ScriptDiscoveryProvider">
<IntervalSeconds>$Config/IntervalSeconds$</IntervalSeconds>
<ScriptName>DiscoveryAppY.vbs</ScriptName>
<Arguments>$MPElement$ $Target/Id$ $Config/Computer$</Arguments>
<ScriptBody>
<![CDATA[
Option Explicit
Dim oAPI
Set oAPI = CreateObject("MOM.ScriptAPI")
Dim oArgs
Set oArgs = WScript.Arguments
' Check for the required script arguments.
if oArgs.Count < 3 Then
' If the script is called without the required arguments,
' create an information event and then quit.
Call oAPI.LogScriptEvent("DiscoveryAppY.vbs",101,0, _
"DiscoveryAppY script was called with fewer than three " _
& "arguments and was not executed. ")
Wscript.Quit -1
End If
Dim SourceID, ManagedEntityId, TargetComputer
SourceId = oArgs(0) ' The GUID of the Discovery that launched the script.
ManagedEntityId = oArgs(1) ' The GUID of the computer class targeted by the script.
TargetComputer = oArgs(2) ' The FQDN of the computer targeted by the script.
Dim oFso
Set oFso = CreateObject("Scripting.FileSystemObject")
Dim oDiscoveryData, oInst
Set oDiscoveryData = oAPI.CreateDiscoveryData(0, SourceId, ManagedEntityId)
If (oFso.FolderExists("C:\AppY")) Then
' Discovered the application. Create the application instance.
Set oInst = oDiscoveryData.CreateClassInstance("$MPElement[Name='Microsoft.Demo.Scripting.AppY']$")
' Define the property values for this class instance.
' The available properties are determined by the
' management pack that defines the class.
Call oInst.AddProperty("$MPElement[Name='Windows!Microsoft.Windows.Computer']/PrincipalName$", TargetComputer)
Call oInst.AddProperty("$MPElement[Name='Microsoft.Demo.Scripting.AppY']/Version$", "2.0")
Call oInst.AddProperty("$MPElement[Name='Microsoft.Demo.Scripting.AppY']/Path$", "C:\AppY")
Call oInst.AddProperty("$MPElement[Name='System!System.Entity']/DisplayName$", "Application Y")
Call oDiscoveryData.AddInstance(oInst)
' Discover the application's components.
Dim oFolder, oFile
Set oFolder = oFso.GetFolder("C:\AppY")
' Create a separate class instance for each file in the folder.
For each oFile in oFolder.Files
Set oInst = oDiscoveryData.CreateClassInstance("$MPElement[Name='Microsoft.Demo.Scripting.AppYComponent']$")
' Define the property values for this class instance.
' The available properties are determined by the
' management pack that defines the class.
Call oInst.AddProperty("$MPElement[Name='Windows!Microsoft.Windows.Computer']/PrincipalName$", TargetComputer)
Call oInst.AddProperty("$MPElement[Name='Microsoft.Demo.Scripting.AppYComponent']/ID$", StripExtension(oFile.Name))
Call oInst.AddProperty("$MPElement[Name='Microsoft.Demo.Scripting.AppYComponent']/FileName$", oFile.Name)
Call oInst.AddProperty("$MPElement[Name='System!System.Entity']/DisplayName$", StripExtension(oFile.Name))
Call oDiscoveryData.AddInstance(oInst)
Next
End If
' Submit the discovery data for processing.
Call oAPI.Return(oDiscoveryData)
' A helper function to remove the extension from a file name.
Function StripExtension (sFile)
StripExtension = Left(sFile, Len(sFile) -4)
End Function
]]>
</ScriptBody>
<TimeoutSeconds>20</TimeoutSeconds>
</DataSource>
</MemberModules>
<Composition>
<Node ID="DS"/>
</Composition>
</Composite>
</ModuleImplementation>
<!-- The type must specify the type of data output by the module. (In this case, discovery data.) -->
<OutputType>System!System.Discovery.Data</OutputType>
</DataSourceModuleType>
</ModuleTypes>
The custom module type is based on the Microsoft.Windows.ScriptDiscoveryProvider module type that is defined in the Microsoft.Windows.Library management pack. The ScriptDiscoveryProvider module type accepts the following configuration elements that are used to define and run the script:
IntervalSeconds—The length of time between each run of the script.
ScriptName—A user-defined script name with the required .vbs or .js extension. To run the script, the agent creates a temporary script file with the specified name, which is then executed by CScript.exe, the command-line version of the Windows Script Host.
Arguments—White-space-delimited values for any arguments that are required by the script.
ScriptBody—The body of the script.
TimeoutSeconds—The amount of time to allow the script to run before terminating it.
The custom module type defines values for each of these required configuration elements. When it defines the script's body, the module wraps the script in CDATA to ensure that any XML characters in the script that are not valid are not exposed in the management pack's XML file (for example, an ampersand or a greater than or less than symbol).
The custom module type also makes it possible for users of the management pack to override the value of the IntervalSeconds configuration element, which defines how frequently the monitoring script runs.
The management pack uses the module to create a new discovery. Agents in the management group automatically run this discovery at the defined interval—in this case, every 60 seconds.
Note
In this example, the discovery interval is set to a short value to facilitate testing the discovery example. When you are defining a discovery for use in real systems, the value should be set to a longer interval that is appropriate for the system's performance.
<Discoveries>
<Discovery ID="Microsoft.Demo.Scripting.AppY.Discovery" Target="Windows!Microsoft.Windows.Server.Computer" Remotable="false" Enabled="true">
<Category>Discovery</Category>
<DiscoveryTypes>
<DiscoveryClass TypeID="Microsoft.Demo.Scripting.AppY">
<Property PropertyID="Version"/>
<Property PropertyID="Path"/>
<Property TypeID="System!System.Entity" PropertyID="DisplayName"/>
</DiscoveryClass>
<DiscoveryClass TypeID="Microsoft.Demo.Scripting.AppYComponent">
<Property PropertyID="ID"/>
<Property PropertyID="FileName"/>
<Property TypeID="System!System.Entity" PropertyID="DisplayName"/>
</DiscoveryClass>
<DiscoveryRelationship TypeID="Microsoft.Demo.Scripting.AppYHostsAppYComponent"/>
</DiscoveryTypes>
<DataSource ID="DS" TypeID="Microsoft.Demo.Scripting.AppY.DiscoveryProvider">
<IntervalSeconds>60</IntervalSeconds>
<Computer>$Target/Property[Type="Windows!Microsoft.Windows.Computer"]/PrincipalName$</Computer>
</DataSource>
</Discovery>
</Discoveries>
See Also
Tasks
How to Create Discovery Data by Using a Script
Concepts
Getting Started Developing Runtime Scripts
Runtime Scripts Overview