Monitoring Scripts

Applies To: System Center Operations Manager 2007

Monitoring scripts are used when the required data cannot be collected through other standard means such as an event or performance counter. The script collects data from information on the agent and creates a property bag by using the MOM.ScriptAPI object that is installed with the Operations Manager 2007 agent.

Monitoring scripts may be written in any script language that can access the MOM.ScriptAPI object that is installed on all Operations Manager 2007 agents. The most common languages used are VBScript, JScript, and Windows PowerShell. Scripts that use VBScript or Jscript can be created by using modules in management pack libraries and wizards in the Authoring console. Modules are available for monitoring scripts that are written in Windows PowerShell in Operations Manager 2007 R2 but are not supported by wizards in the Authoring console. A custom workflow would have to be created by using the appropriate module as described in the Composition section of this guide.

Property Bags

$Data/Property[@Name="PropertyName"]

Typed Property Bags

MOMScriptAPI.CreateTypedPropertyBag(type)

Basic Script Structure

The following sample shows a monitoring script with the following characteristics.

• Accepts arguments for the name of the computer that is running the script and a path of the location of the application.

• Creates a property bag with the values named ComputerName, InstanceName, and PerfValue.

sComputerName = WScript.Arguments(0) 
sApplicationPath = WScript.Arguments(1)

Set oAPI = CreateObject("MOM.ScriptAPI")
Set oBag = oAPI.CreatePropertyBag()

oBag.AddValue "ComputerName", sComputerName
oBag.AddValue "InstanceName", "MyInstance"
oBag.AddValue "Value", 1.0

oAPI.Return(oBag)

Script Breakdown

Details of each section of the script are discussed here.

sComputerName = WScript.Arguments(0) 
sApplicationPath = WScript.Arguments(1)

The first two lines of the script accept arguments. These values would be expected to be in the Arguments parameter of the rule or monitor running the script. The script can use any number of arguments that are required for the logic of the script.

Set oAPI = CreateObject("MOM.ScriptAPI")
Set oBag = oAPI.CreatePropertyBag()

The next two lines create a property bag. These lines will also be unchanged in most monitoring scripts. The main purpose of the rest of the script will be to add values to the property bag by using data that is collected from the agent computer.

oBag.AddValue "ComputerName", sComputerName
oBag.AddValue "InstanceName", "MyInstance"
oBag.AddValue "Value", 1.0

After the property bag is created, any number of values can be added to it. You do this with the AddValue method on the property bag object by using the name of the item followed its value. This example uses explicit values. In actual monitoring script, additional code would be expected that would collect information from the agent computer to include in these values.

oAPI.Return(oBag)

After all values are added to the property bag, it is returned into the workflow. This line is required, and without it the property bag is discarded when the script ends. This method is only used when the script creates only a single property bag. For more information about scripts that return multiple property bags and conditions when such a strategy is used, refer to the Cookdown section of this guide.

Defining a Script

Script Name

Scripts in a management pack must be given a name with either a .vbs or ,js extension depending on their language. This name is used to create the file in the temporary directory on the agent. There is no requirement to make this name unique because each script is provided its own temporary directory on the agent.

Script Arguments

Arguments are provided to the script in a single line separated by spaces. This is identical to the command line that would be provided if the script were run on a command line. This is access in the Authoring console from the Parameters button.

Each argument can be either an explicit value or a $Target variable to use the value of a property on the target object. Any $Target variables are resolved when the script is run so that the script is provided with the resolved values on the command line.

For example, the sample script earlier expects two arguments for the computer name and the application path. Assuming this was part of a workflow targeted at a class hosted by the Windows Computer class, the computer name could be retrieved from the PrincipalName property. If the application path were a property on the target class, then the arguments might look similar to the following example. Notice the quotation marks around the ApplicationPath property, because this could resolve to a value that contains a space.

$Target/Host/Property[Type="Windows!Microsoft.Windows.Computer"]/PrincipalName$ "$Target/Property[Type="MyApp.MyClass"]/ApplicationPath$"

Script Timeout

All scripts are given a timeout value which indicates the number of seconds that the script can run before the agent stops it. This prevents problem scripts from running continuously and putting excess overhead on the agent computer.

The timeout value assigned to a script should allow enough time for the script to run under ordinary conditions, but should be less than the interval that the script is scheduled to run. If a script is configured to have a timeout value greater than its duration, then possibly multiple copies of the script could be running concurrently.

Windows PowerShell

The following script is the Windows PowerShell equivalent of the VBScript sample monitoring script shown previously. Both scripts use the same MOM.ScriptAPI object and methods.

param($computerName,$version)

$api = New-Object -comObject 'MOM.ScriptAPI'
$bag = $api.CreatePropertyBag()

$bag.AddValue 'ComputerName', $computerName
$bag.AddValue 'InstanceName', '1.0'
$bag.AddValue 'Value', '1.0'

$bag

Other than obvious syntax, there are two primary differences between the VBScript and Windows PowerShell scripts, as follows.

param($computerName,$version)

The first difference is in the means of retrieving script arguments. Windows PowerShell can accept positional arguments as VBScript does, but named parameters that use the param command better support the Windows PowerShell modules included with Operations Manager 2007 R2. These modules let parameters be separately specified in the module configuration where they are retrieved by the script as named parameters.

$bag

Another important difference is the way that the property bag data is returned to the workflow. In VBScript, the Return method of the MOM.ScriptAPI object is used. In Windows PowerShell, this method will not return the data correctly. The Return method sends the discovery data to the Standard Out (StdOut) stream, whereas Windows PowerShell requires the data to be sent to the output pipeline. This is achieved by typing the property bag variable on its own line.

Monitors and rules that use PowerShell scripts cannot be created by using wizards in the Authoring Console. Custom workflows must be created by using the PowerShell modules available in Operations Manager 2007 R2. Information on custom workflows is provided in the Composition section of this guide.

For management packs that must support Operations Manager 2007 SP1, the PowerShell modules cannot be used. In this case, a custom solution running PowerShell.exe from a custom workflow would have to be employed.

Supported Workflows

Scripts can be used in the following kinds of workflows:

• Monitors

• Collection Rules

Collection rules based on scripts can map values in the property bag to either events or performance data. There is no difference in the scripts for either of these kinds of rules. The only difference is in the properties of the resulting data type that the property bag values are mapped into.

See Also

Concepts

Script Monitors