7.1 RunCommand

Use this Knowledge Script to run the Microsoft Windows PowerShell cmdlet, PowerShell script (.PS1 file), or code blocks you specify. This script raises an event with the command results and generates a datastream with the value returned by the command.

You can also use this script to run any command that can be run from a Windows PowerShell command prompt, such as dir c:\temp. PowerShell accepts commands in cmdlet, .PS1, and Windows cmd.exe formats.

The PowerShell_RunCommand script makes a number of callback and helper functions available to the PowerShell commands or scripts being run. For more information, see Appendix A, “Using PowerShell Callback and Helper Functions” in the management guide.

7.1.1 Prerequisites

  • Microsoft Windows PowerShell version 1.0 or later

  • Microsoft .NET Framework version 3.0

  • AppManager for Windows version 7.6 or later

7.1.2 Resource Object

PowerShell folder

7.1.3 Default Schedule

By default, this script runs once.

7.1.4 Setting Parameter Values

Set the following parameters as needed:

Parameter

How to Set It

General Settings

Job Failure Notification

Event severity when job fails

Set the event severity level, from 1 to 40, to indicate the importance of an event in which the RunCommand job fails. The default is 5.

PowerShell Command

PowerShell to run

Provide the PowerShell scripts, cmdlets, or code blocks you want to run. You can string multiple commands together. For example:

Select-String -Path C:\Temp\*.log -Pattern 'Error:.*CPU' | foreach {$_.ToString()}

This command returns all lines in all log files in the C:\Temp directory that contain the text strings Error: followed by CPU, with any number of characters (zero or more) between the two strings.

Ensure your command contains no syntax errors. The RunCommand job will fail if the command contains syntax errors.

Note Double quotation marks within a command are automatically doubled up, unless the only double-quotes in the command are already doubled up because they represent empty strings.In this situation, you can work around this issue by adding a final statement to the command. For example:

$foo -eq ""; [void] "x"

where the ; separates this final statement from the rest of the statements, and the [void] "x" has no actual effect on the command execution, but it enables the script to recognize that all double-quotes in the command need to be doubled up.

Restrictions

  • You can run scripts that have pathnames with spaces, but you need to use the call operator (&), such as: & 'C:\Program Files\My Files\Agent.ps1' The quotes (either single or double-quotes) around the full pathname are required if the path contains spaces.

  • PowerShell scripts (.PS1 files) must be located on the computer on which you run the RunCommand script. The RunCommand script cannot run remote PowerShell scripts.

Event Notification

Raise event with result of command?

Select Yes to raise an event when the command you run returns text or numeric results. The default is Yes.

Format results as

Select whether to format command results in a Table or a List or to apply no formatting. Select Unformatted if the command returns results that are already formatted. The default is Unformatted.

Event title

Provide text to use as the title of the event.

Event severity

Set the event severity level, from 1 to 40, to indicate the importance of an event in which a command returns text or numeric results. The default is 25.

Raise event only if result contains specified pattern?

Select Yes to raise an event if the command returns text that matches the expression you provide in the Pattern to find in the results parameter. The default is unselected.

This parameter is valid only if the Raise event with result of command parameter is enabled.

Pattern to find in the results

Provide the text you want to compare to the command results. The following wildcards are acceptable:

  • * - matches zero or more instances of a character.

  • ? - matches exactly one instance of a character.

  • [ ] - matches exactly one instance of any character between the square brackets, including ranges.

Examples:

  • [abc][def] matches “ad,” “bad,” and “ace,” but not “bleary.”

  • [a-z][a-z] matches text that contains two adjacent alphabetic characters.

  • foo? Bar matches “food bar” and “This is a food bar!” but not “foobar” or “foo bar.”

  • *maximum mailbox* matches “user smith has reached maximum mailbox size.”

Raise event only if numeric result crosses threshold?

Select Yes to raise an event if the command returns a numeric value that exceeds or falls below the threshold you set in the Threshold value parameter. The default is unselected.

Operator to compare numeric result to threshold

Select the operator with which to compare the command results to the threshold value. Choose from one of the following:

  • Greater than

  • Less than

  • Greater than or equal to

  • Less than or equal to

An event is raised if the command results do not match the threshold value based on the operator you choose.

The default is Greater than.

Threshold value

Provide the numeric value to compare with the command results. An event is raised if the command results do not match the threshold value based on the option you choose in the Select operator to compare numeric result to threshold parameter. The default is 0.

Metric name to include in event title

Provide the name of the metric for which the command returns numeric results. For example, specify the name of a Performance Monitor counter. The name of the metric will be part of the title of the event raised when the numeric result crosses the threshold.

Raise event if command returns no results?

Select Yes if the command you run returns no results. The default is unselected.

Hint You can use this parameter to raise an event when a command that should return text or numeric results does not return any results. Enable this parameter and disable the Raise event with result of command? parameter.

Event severity when command returns no results

Set the event severity level, from 1 to 40, to indicate the importance of an event in which a command does not return text or numeric results. The default is 5.

Data Collection

Collect data for numeric command result?

Select Yes to collect data for charts and reports. This parameter is valid only if the Raise event only if numeric result crosses threshold? parameter is enabled. The default is unselected.

Use the following parameters to format the wording and units of datastream legends.

Name of monitored metric

Provide the name of the metric for which the command returns numeric results. For example, specify the name of a Performance Monitor counter. The name of the metric will be part of the datastream legend.

Name of monitored resource

Provide the name of the device associated with the metric for which the command returns numeric results. For example, specify the hostname of a computer. The name of the device will be part of the datastream legend.

Datastream units

Identify the unit of measure associated with the metric for which the command returns numeric results. For example, specify MB or Mbytes. The unit of measure will be part of the datastream legend.