Microsoft.Windows.ScriptProbeAction

Applies To: Operations Manager 2007 R2

The Microsoft.Windows.ScriptProbeAction probe action module type is used to run a script as part of a monitoring workflow (a rule or a monitor) or a task workflow. The module type accepts any type of data, including trigger, and outputs System.CommandOutput data.

Usage

Use this module when you want to gather data from a script on a monitored computer.

Type Definition

<ProbeActionModuleType ID="Microsoft.Windows.ScriptProbeAction" Accessibility="Public">
  <Configuration>
    <IncludeSchemaTypes>
      <SchemaType>System!System.ParamListSchema</SchemaType>
      <SchemaType>System!System.CommandExecuterSchema</SchemaType>
    </IncludeSchemaTypes>
    <xsd:element name="ScriptName" type="xsd:string" />
    <xsd:element name="Arguments" type="xsd:string" />
    <xsd:element name="ScriptBody" type="xsd:string" />
    <xsd:element name="SecureInput" minOccurs="0" maxOccurs="1">
      <xsd:simpleType>
        <xsd:restriction base="xsd:string">
          <xsd:maxLength value="256" />
        </xsd:restriction>
      </xsd:simpleType>
    </xsd:element>
    <xsd:element name="TimeoutSeconds" type="xsd:integer" />
    <xsd:element minOccurs="0" maxOccurs="1" name="EventPolicy" type="CommandExecuterEventPolicyType" />
  </Configuration>
  <OverrideableParameters>
    <OverrideableParameter ID="Arguments" Selector="$Config/Arguments$" ParameterType="string" />
    <OverrideableParameter ID="TimeoutSeconds" Selector="$Config/TimeoutSeconds$" ParameterType="int" />
  </OverrideableParameters>
  <ModuleImplementation>
    <Composite>
      <MemberModules>
        <ProbeAction TypeID="System!System.CommandExecuterProbe" ID="PA1">
          <ApplicationName><![CDATA[%windir%\system32\cscript.exe]]></ApplicationName>
          <WorkingDirectory />
          <CommandLine>/nologo "$Config/ScriptName$" $Config/Arguments$</CommandLine>
          <SecureInput>$Config/SecureInput$</SecureInput>
          <TimeoutSeconds>$Config/TimeoutSeconds$</TimeoutSeconds>
          <RequireOutput>true</RequireOutput>
          <Files>
            <File>
              <Name>$Config/ScriptName$</Name>
              <Contents>$Config/ScriptBody$</Contents>
              <Unicode>true</Unicode>
            </File>
          </Files>
          <DefaultEventPolicy>
            <StdOutMatches />
            <StdErrMatches>\a+</StdErrMatches>
            <ExitCodeMatches>[^0]+</ExitCodeMatches>
          </DefaultEventPolicy>
          <EventPolicy>$Config/EventPolicy$</EventPolicy>
        </ProbeAction>
      </MemberModules>
      <Composition>
        <Node ID="PA1" />
      </Composition>
    </Composite>
  </ModuleImplementation>
  <OutputType>System!System.CommandOutput</OutputType>
  <InputType>System!System.BaseData</InputType>
</ProbeActionModuleType>

Parameters

The Microsoft.Windows.ScriptProbeAction module supports the configuration parameters described in the following table.

Parameter Type Overrideable Description

ScriptName

String

False

Required parameter. Contains the file name of the script (including the extension) that identifies the script type.

Arguments

String

True

Required parameter. Contains the arguments to be supplied to the script on execution.

ScriptBody

String

False

Required parameter. Contains the script contents. If the script contains XML characters that must be escaped, it is recommended that the entire script be wrapped in a CDATA element.

SecureInput

String

False

Optional parameter. Contains the data to be passed to the script in a secure method. This is used to provide passwords to the script to be used during execution.

TimeoutSeconds

Integer

True

Required parameter. Specifies the time the script is allowed to run before being closed by the module and marked as failed.

ScriptName

The ScriptName parameter specifies the file name of the script to be executed. The module caches a local copy of the script on the agent that is running the script in the health service cache.

The file name should be a legal Windows file name and must contain the correct extension for the script type; for example, .vbs for VBScript and .js for JScript. It is a best practice to name the script something meaningful so that it can be located in the health service cache on an agent computer if you need to debug execution.

Note

The script name should not contain spaces.

Arguments

The Arguments parameter specifies the command-line arguments that are passed to the script when it is executed. This configuration can consist of static values or dynamic references by using $Target or $Data references.

The script has no context of the object being executed against or the data that triggered the execution. Passing data into the script is the only method to provide this data. Arguments can be queried by using the WScript object as required.

The following simple example code passes the computer name and the version of the application that the workflow is targeted at:

<Arguments>$Target/Host/Property[Type='Windows!Microsoft.Windows.Computer"]/NetworkName$ $Target/Property[Type='Microsoft.Samples.ApplicationX']/Version$</Arguments>

The following code is an example of the command line that is actually called when the script is executed:

CScript.exe MyScript.vbs computer1.mydomain.local 2.0

If there can be spaces in your values that are passed to the script, you should be sure to enclose the values in quotes when you specify them, to avoid their being split into multiple arguments by the Windows Script Host.

In the following example, the InstallPath property is wrapped in quotes:

<Arguments>$Target/Host/Property[Type='Windows!Microsoft.Windows.Computer"]/NetworkName$ ‘$Target/Property[Type='Microsoft.Samples.ApplicationX']/Install Path$’</Arguments>

ScriptBody

The ScriptBody parameter contains the actual script text. It is a best practice to wrap the script in a CDATA block, as shown in the preceding example, to avoid having to escape certain characters that are not valid in the XML.

SecureInput

The SecureInput parameter is primarily used to pass secure data, such as passwords, into the script. Passing this data in the Arguments parameter is not secure and should not be done.

Passwords are passed by using $RunAs syntax.

TimeoutSeconds

The TimeoutSeconds parameter specifies the maximum length of time that the script can run before it is terminated. If the script exceeds this time-out and is terminated, the module reports a fatal error on execution. For scripts that are used as part of rule or monitor workflows, the time-out value should be less than the frequency with which the script executes on a given instance.

Composition

The Microsoft.Windows.ScriptProbeAction module is a composite module that contains the member module described in the following table.

Workflow Run Order Module Type Usage

1

System.CommandExecuterProbe

Probe action module that runs a batch file or an executable file from the command prompt.

Module Type

Usage

Microsoft.Windows.ScriptDiscoveryProbe

Used for discovery scripts that are triggered by data sources other than the simple scheduler.

Microsoft.Windows.ScriptPropertyBagProbe

Used for monitoring scripts that are triggered by data sources other than the simple scheduler.

Microsoft.Windows.ScriptWriteAction

Used as a task or recovery when the script is changing something on the system on which it is run.

Microsoft.Windows.TimedScript.DiscoveryProvider

Used for scheduled discovery scripts that are triggered by the simple scheduler.

Microsoft.Windows.TimedScript.EventProvider

Used for scheduled scripts that output data that is mapped to an event and stored in the Operations Manager databases.

Microsoft.Windows.TimedScript.PropertyBagProvider

Used for scheduled scripts that are used in rule or monitor workflows. This module type provides property bag output that is better suited for XPath referencing and expression evaluation. This module is triggered by the simple scheduler.

External Module References

None.

Remarks

This module uses Cscript.exe to run the scripts. The script that is run can be any script type that is supported by the Windows Script Host (WSH) on the target computers. The type of script is identified by the file name extension that is provided in the configuration. The two common types of script are VBScript (.vbs extension) and JScript (.js extension).

For VB Script, you can write to standard output in the following ways:

WScript.Echo "This is some output"

WScript.Echo "This is some output"

You can write to a standard error in the following way:

WScript.StdErr.Write "This is some error text"

To return a non-zero exit code, you must call the Quit function with the required error code, as shown in the following example:

WScript.Quit(2)

For more detailed information about writing to standard output and standard errors, see the Windows Script Host reference documentation.

Important

If you plan on implementing a custom module in order to make a parameter overrideable, you must be certain that the $Target variable notation will not be used within the parameter value. If $Target is used, the engine will simply interpret it as a string literal.

For more information about writing Operations Manager discovery and monitoring scripts, see Operations Manager 2007 R2 Scripting Objects.

Sample

The following code example shows the Microsoft.Windows.ScriptProbeAction module used in a simple task:

<Task ID="Microsoft.Samples.TaskTest1" Accessibility="Internal" Target="Microsoft.Samples.ApplicationX">
  <Category>Operations</Category>
  <ProbeAction ID="Script" TypeID="Windows!Microsoft.Windows.ScriptProbeAction">
    <ScriptName>Microsoft.Samples.TestScript1.vbs</ScriptName>
    <Arguments>$Target/Host/Property[Type='Windows!Microsoft.Windows.Computer']/NetworkName$</Arguments>
    <ScriptBody>
      <![CDATA[
Option Explicit
Dim Args
Set Args = WScript.Arguments
WScript.Echo "This is some output text"
WScript.Echo "This is a parameter passed in: " & Args(0)
WScript.StdOut.Write "This is some more output text"
WScript.StdErr.Write "This is some error text"
WScript.Quit(3)

]]>
    </ScriptBody>
    <SecureInput/>
    <TimeoutSeconds>10</TimeoutSeconds>
    <EventPolicy>
      <Severity>0</Severity>
      <StdErrMatches>\a+</StdErrMatches>
    </EventPolicy>
  </ProbeAction>
</Task>

Information

   

Module Type

ProbeActionModuleType

Input Type

None

Output Type

System.CommandOutput

Implementation

Composite

Library

Microsoft.Windows.Library