Help Menu

This help page is for version 6.1. The latest available help is for version 8.0.

Execute Script Action

The Execute Script Action allows you to receive action parameters that were sent from a monitor and handle them in your own specific way.

The script is run using the computer's built-in VBScript, JavaScript or Powershell interpreter. This means you can make use of the full scripting language as well as any installed 3rd party components that are installed on the system.

Near the top of the action dialog is a "Run script at" selection box. Here you can specify where the script should be run if you have Satellite monitoring services. The default is to run the script on the Central Monitoring Service.

The next control simply allows you to select the language for your script. If the script window is empty or still showing the default script, changing the current language will show a new default script in the language you speciy.

The script window is where you enter your script. The script can do anything that can be done in the select language (including creating external components) with all the standard restrictions. A good VBScript reference is available at: http://msdn.microsoft.com/en-us/library/d1wf56tt.aspx

There are two Test buttons. One will run the script within the Console. The other will send the script to the monitoring service that is monitoring the target computer (Central Monitoring Service or a Satellite) and run the script there. This helps find any problems that might come up from the script possibly running on a different machine, or running as a different user (the service Log As user).

Keep in mind that when the script runs, it might run on a different computer than where you are editing it. That means drive mappings, HKEY_CURRENT_USER registry hive, Internet Explorer settings and the currently running user will often be different.

IMPORTANT: Do not show any user interface elements in the script -- they will not be visible in the monitoring service and will block the script from ever completing.

Topics

Example scripts

VBScript

JavaScript

PowerShell

SSH

Additional Script Elements

Besides the scripting language's own objects and elements, the following additional global variables and methods are available within each scripting environment:

VBScript

AlertType

This value indicates if the script is running because of an alert condition, a fixed condition, because an error was acknowledged, or for a reminder of a still open error.
Possible values are:
1 = Alert
2 = Fixed
3 = Acknowledged
4 = Reminder


Example:

if AlertType = 1 Then {do something ... }

CurrentValue

This is an array of string values, representing the current value (if any) for the item being tested. See Row Variables from the "Variables..." button for the action.

Example:

myStr = CurrentValue(1)

CustomProp

This function retrieves the named value of a custom property. It checks the Monitor first, and if not found, checks the monitor's owning computer, and then the computer's group, and then the group's parent group, etc. Custom properties can be set on Groups, Computers and Monitors by right-clicking on the item and choosing the Custom Properties menu.

Example:

myStr = CustomProp("NotifyGroupID")
.

Details

This is a string value. This value is the content of the action being fired. It is sent from the monitor and typically contains information about the alert.

Example:

myStr = Details

Description

This is an array of string values, representing a description of this particular item's status. The Details value (above) is usually all of the Description values appended together.

Example:

myStr = Description(1)

Extra1

This is an array of string values, representing extra information that may be available from a particular monitor. See Row Variables from the "Variables..." button for the action.

Example:

myStr = Extra1(1)

Extra2

This is an array of string values, representing extra information that may be available from a particular monitor. See Row Variables from the "Variables..." button for the action.

Example:

myStr = Extra2(1)

Group

The name of the group that the computer the monitor is attached to belongs in.

Example:

myStr = Group

GroupPath

The name of the group that the computer the monitor is attached to belongs in, with child groups delimited with a > (ie, Servers/Devices > Austin > Lab )

Example:

myStr = GroupPath

InventoryValue

Request an inventory value for the current computer, or a different one. An inventory propertyID must be used to specify which inventory value to retrieve. An optional ComputerID value can be used to get the inventory value from a computer other than the current computer. If a property can have multiple values (CPU Names for example), each one will have a newline character appended.

Example:


'returns the Operating System (18) for the current computer myStr = InventoryValue(18)
'returns the Operating System (18) for the current computer (0 means use default) myStr = InventoryValue(18, 0)
'returns the Operating System (18) for computerID 238 myStr = InventoryValue(18, 238)

The inventoryID values are given below. Note that not all computers/devices will have all inventory values, and some may have none (especially if an Inventory Collector monitor is not added to the computer).

Anti-virus Version38
Anti-virus Pattern File39
Anti-virus Pattern File Date40
Anti-virus Status41
Operating System18
OS Architecture19
OS Version20
OS Last Boot Time (_time_t UTC value)21
OS Current Time (_time_t UTC value)22
CPU Count13
CPU Name (multi value)15
CPU Number of Cores (multi value)16
CPU Clock Speed (multi value)17
Display Name6
Drive Status (multi value)23
Domain9
Manufacturer10
Page File size in MB24
RAM in MB14
System Architecture12
System Model11
Time Zone Offset8
Uptime % this month28
Uptime % last month29
Item

This is an array of string values, representing the item being tested. See Row Variables from the "Variables..." button for the action.

Example:

myStr = Item(1)

ItemType

This is an array of string values, representing the type of item being tested. See Row Variables from the "Variables..." button for the action.

Example:

myStr = ItemType(1)

LimitValue

This is an array of string values, representing the limit/threshold (if any) for the item being tested. See Row Variables from the "Variables..." button for the action.

Example:

myStr = LimitValue(1)

Machine

This read-only string variable is the name of the computer that caused the script action to fire.

Example:

myStr = Machine

MachineAlias

This read-only string variable is the aliased name of the computer that caused the script action to fire.

Example:

myStr = MachineAlias

MachineIP

IP address text string of the computer that the firing monitor is attached to

Example:

myStr = MachineIP

MachineID

Returns the numeric value that uniquely identifies this computer (Computer ID - CID) within the application. Useful in conjunction with the External API.

Example:

myID = MachineID

MonitorTitle

This read-only string variable is the title of monitor that caused this script action to fire.

Example:

myStr = MonitorTitle

MonitorType

This read-only string variable is the type of monitor that caused this script action to fire.

Example:

myStr = MonitorType

SecondsInError

Number of seconds that the monitor has been in error.

Example:

inErrSeconds = SecondsInError

State

An array of string values that contain the OK or PROBLEM state for each item being reported on. See Row Variables from the "Variables..." button for the action.

Example:

myStr = State(1)

SendMail

This method sends an email message to the recipient that you choose. This would be useful for sending the incoming Details variable to a different email recipient based on some external factors (such as who is currently carrying the pager)

Example:

SendMail "to_address@host.com", "from_address@host.com", "Subject of message", "Body of email message"

SetComputerCustomPropByID

Custom Properties can be used in directory paths, email messages, scripts and other places. Your script can set a Custom Property on a computer by specifying its ID (first parameter), or use 0 to indicate the computer that the action is running for should be targeted.

Example:

SetComputerCustomPropByID(0, "DEVICEID", "BSQL")

Sleep

This method takes a single integer value, which is the number of milliseconds that the script should stop and sleep. Be careful about using this -- causing too many actions to sleep for very long means other actions may get delayed

Example:

Sleep 1500

Status

A read-only string indicating the current status of the monitor. To see all possible values, See Row Variables from the "Variables..." button for the action.

Example:

myStat = Status

StatusText

A read-only string indicating the current status of the monitor. This is a more human-friendly value than Status. To see all possible values, See Row Variables from the "Variables..." button for the action.

Example:

myStat = Status

TimeInErrorStr

A text string of how long the monitor has been in error

Example:

myStr = TimeInErrorStr

ToLog

This method takes a string value and appends it to the service's log file (useful for debugging scripts). The line will start with ACTION_SCRIPT_LOG.

Example:

ToLog "Arrived at first loop"
ToLog resultVal

JavaScript

AlertType

This value indicates if the script is running because of an alert condition, a fixed condition, because an error was acknowledged, or for a reminder of a still open error.
Possible values are:
1 = Alert
2 = Fixed
3 = Acknowledged
4 = Reminder


Example:

if(AlertType == 1) {do something ... }

CurrentValue

This is an array of string values, representing the current value (if any) for the item being tested. See Row Variables from the "Variables..." button for the action.

Example:

myStr = CurrentValue(1);

CustomProp

This function retrieves the named value of a custom property. It checks the Monitor first, and if not found, checks the monitor's owning computer, and then the computer's group, and then the group's parent group, etc. Custom properties can be set on Groups, Computers and Monitors by right-clicking on the item and choosing the Custom Properties menu.

Example:

myStr = CustomProp("NotifyGroupID");

Details

This is a string value. This value is the content of the action being fired. It is sent from the monitor and typically contains information about the alert.

Example:

myStr = Details;

Extra1

This is an array of string values, representing extra information that may be available from a particular monitor. See Row Variables from the "Variables..." button for the action.

Example:

myStr = Extra1(1);

Extra2

This is an array of string values, representing extra information that may be available from a particular monitor. See Row Variables from the "Variables..." button for the action.

Example:

myStr = Extra2(1);

Group

The name of the group that the computer the monitor is attached to belongs in.

Example:

myStr = Group;

GroupPath

The name of the group that the computer the monitor is attached to belongs in, with child groups delimited with a > (ie, Servers/Devices > Austin > Lab )

Example:

myStr = GroupPath;

InventoryValue

Request an inventory value for the current computer, or a different one. An inventory propertyID must be used to specify which inventory value to retrieve. An optional ComputerID value can be used to get the inventory value from a computer other than the current computer. If a property can have multiple values (CPU Names for example), each one will have a newline character appended.

Example:

//returns the Operating System (18) for the current computer myStr = InventoryValue(18);
//returns the Operating System (18) for the current computer (0 means use default) myStr = InventoryValue(18, 0);
//returns the Operating System (18) for computerID 238 myStr = InventoryValue(18, 238);

The inventoryID values are given below. Note that not all computers/devices will have all inventory values, and some may have none (especially if an Inventory Collector monitor is not added to the computer).

Anti-virus Version38
Anti-virus Pattern File39
Anti-virus Pattern File Date40
Anti-virus Status41
Operating System18
OS Architecture19
OS Version20
OS Last Boot Time (_time_t UTC value)21
OS Current Time (_time_t UTC value)22
CPU Count13
CPU Name (multi value)15
CPU Number of Cores (multi value)16
CPU Clock Speed (multi value)17
Display Name6
Drive Status (multi value)23
Domain9
Manufacturer10
Page File size in MB24
RAM in MB14
System Architecture12
System Model11
Time Zone Offset8
Uptime % this month28
Uptime % last month29
Item

This is an array of string values, representing the item being tested. See Row Variables from the "Variables..." button for the action.

Example:

myStr = Item(1);

ItemType

This is an array of string values, representing the type of item being tested. See Row Variables from the "Variables..." button for the action.

Example:

myStr = ItemType(1);

LimitValue

This is an array of string values, representing the limit/threshold (if any) for the item being tested. See Row Variables from the "Variables..." button for the action.

Example:

myStr = LimitValue(1);

Machine

This read-only string variable is the name of the computer that caused the script action to fire.

Example:

myStr = Machine;

MachineAlias

This read-only string variable is the aliased name of the computer that caused the script action to fire.

Example:

myStr = MachineAlias;

MachineIP

IP address text string of the computer that the firing monitor is attached to

Example:

myStr = MachineIP;

MachineID

Returns the numeric value that uniquely identifies this computer (Computer ID - CID) within the application. Useful in conjunction with the External API.

Example:

myID = MachineID;

MonitorTitle

This read-only string variable is the title of monitor that caused this script action to fire.

Example:

myStr = MonitorTitle;

MonitorType

This read-only string variable is the type of monitor that caused this script action to fire.

Example:

myStr = MonitorType;

SecondsInError

Number of seconds that the monitor has been in error.

Example:

inErrSeconds = SecondsInError;

State

An array of string values that contain the OK or PROBLEM state for each item being reported on. See Row Variables from the "Variables..." button for the action.

Example:

myStr = State(1);

SendMail

This method sends an email message to the recipient that you choose. This would be useful for sending the incoming Details variable to a different email recipient based on some external factors (such as who is currently carrying the pager)

Example:

SendMail("to_address@host.com", "from_address@host.com", "Subject of message", "Body of email message");

SetComputerCustomPropByID

Custom Properties can be used in directory paths, email messages, scripts and other places. Your script can set a Custom Property on a computer by specifying it's computer ID, or use 0 to indicate the computer the action is bring run for should be targeted.

Example:

SetComputerCustomPropByID(0, "DEVICEID", "BSQL");

Sleep

This method takes a single integer value, which is the number of milliseconds that the script should stop and sleep. Be careful about using this -- causing too many actions to sleep for very long means other actions may get delayed

Example:

Sleep 1500;

Status

A read-only string indicating the current status of the monitor. To see all possible values, See Row Variables from the "Variables..." button for the action.

Example:

myStat = Status;

StatusText

A read-only string indicating the current status of the monitor. This is a more human-friendly value than Status. To see all possible values, See Row Variables from the "Variables..." button for the action.

Example:

myStat = Status;

TimeInErrorStr

A text string of how long the monitor has been in error

Example:

myStr = TimeInErrorStr;

ToLog

This method takes a string value and appends it to the service's log file (useful for debugging scripts). The line will start with ACTION_SCRIPT_LOG.

Example:

ToLog("Arrived at first loop");
ToLog(resultVal);

PowerShell

PowerShell interaction happens via the $act object.

$act.AcknowledgeAlert

This Function will allow you to acknowledge the alert and to fire or not fire alerts. The three parameters are AlertID ($act.AlertID), AckAlerts, and Acknowledged By. AckAlerts needs to be set to either 0 (doesn't fire achnowledge alerts) or 1(fire achnowledge alerts), defaults is 1.

Example:

$act.AcknowledgeAlert($act.AlertID, 1, "Quinn")

$act.AlertType

This value indicates if the script is running because of an alert condition, a fixed condition, because an error was acknowledged, or for a reminder of a still open error.
Possible values are:
1 = Alert
2 = Fixed
3 = Acknowledged
4 = Reminder


Example:

if($act.AlertType)

$act.CurrentValue

This is an array of string values, representing the current value (if any) for the item being tested. See Row Variables from the "Variables..." button for the action.

Example:

myStr = $act.CurrentValue[0]

$act.CustomProp

This function retrieves the named value of a custom property. It checks the Monitor first, and if not found, checks the monitor's owning computer, and then the computer's group, and then the group's parent group, etc. Custom properties can be set on Groups, Computers and Monitors by right-clicking on the item and choosing the Custom Properties menu.

Example:

myStr = $act.CustomProp("NotifyGroupID")

$act.Details

This is a string value. This value is the content of the action being fired. It is sent from the monitor and typically contains information about the alert.

Example:

myStr = $act.Details

$act.Extra1

This is an array of string values, representing extra information that may be available from a particular monitor. See Row Variables from the "Variables..." button for the action.

Example:

myStr = $act.Extra1[0]

$act.Extra2

This is an array of string values, representing extra information that may be available from a particular monitor. See Row Variables from the "Variables..." button for the action.

Example:

myStr = $act.Extra2[0]

$act.GetMonitorList

GetMonitorList is a function that uses the Server ID to return a list of monitors assigned to the server and the monitor's attributes. The server ID can be for any server and if no server is given the default will be the current server that this monitor is assigned to. The returned value is a Hashtable that can be iterated through to find the value needed.

Example:

$myTable = $act.GetMonitorList(1)

The monitor's attributes values:

Statusstatus
Error TexterrText
Dependencydepends_on
Titletitle
Error Action IDserrActionIDs
Scheduled Next Run TimenextRun
Time in Error (seconds)inErrSeconds
Fixed Action IDfixedActionIDs
Last Run TimelastRun
$act.GetServerList

GetServerList is a function that returns a list of servers assigned to a group and the server's attributes. Two parameter are needed for this function; GroupID and include Child Groups. If no GroupID is used the default 0 is used, which is the entire list of servers at the root level. The second parameter is a switch used to return or not return servers that are in child groups under the starting group. Use to 0 to return all servers and 1 to return servers at the parent level only. The returned value is a Hashtable that can be iterated through to find the value needed.

Example:

$myTable = $act.GetServerList(2, 1)

The server's attributes values:

Server Namename
Group Levelgroup
Group IDgroupID
Statusstatus
Alias for Serveralias
$act.Group

The name of the group that the computer the monitor is attached to belongs in.

Example:

myStr = $act.Group

$act.GroupPath

The name of the group that the computer the monitor is attached to belongs in, with child groups delimited with a > (ie, Servers/Devices > Austin > Lab )

Example:

myStr = $act.GroupPath

$act.InventoryValue

Request an inventory value for the current computer, or a different one. An inventory propertyID must be used to specify which inventory value to retrieve. An optional ComputerID value can be used to get the inventory value from a computer other than the current computer. If a property can have multiple values (CPU Names for example), each one will have a newline character appended.

Example:

//returns the Operating System (18) for the current computer myStr = $act.InventoryValue(18)
//returns the Operating System (18) for the current computer (0 means use default) myStr = $act.InventoryValue(18, 0)
//returns the Operating System (18) for computerID 238 myStr = $act.InventoryValue(18, 238)

The inventoryID values are given below. Note that not all computers/devices will have all inventory values, and some may have none (especially if an Inventory Collector monitor is not added to the computer).

Anti-virus Version38
Anti-virus Pattern File39
Anti-virus Pattern File Date40
Anti-virus Status41
Operating System18
OS Architecture19
OS Version20
OS Last Boot Time (_time_t UTC value)21
OS Current Time (_time_t UTC value)22
CPU Count13
CPU Name (multi value)15
CPU Number of Cores (multi value)16
CPU Clock Speed (multi value)17
Display Name6
Drive Status (multi value)23
Domain9
Manufacturer10
Page File size in MB24
RAM in MB14
System Architecture12
System Model11
Time Zone Offset8
Uptime % this month28
Uptime % last month29
$act.Item

This is an array of string values, representing the item being tested. See Row Variables from the "Variables..." button for the action.

Example:

myStr = $act.Item[0]

$act.ItemType

This is an array of string values, representing the type of item being tested. See Row Variables from the "Variables..." button for the action.

Example:

myStr = $act.ItemType[0]

$act.LimitValue

This is an array of string values, representing the limit/threshold (if any) for the item being tested. See Row Variables from the "Variables..." button for the action.

Example:

myStr = $act.LimitValue[0]

$act.Machine

This read-only string variable is the name of the computer that caused the script action to fire.

Example:

myStr = $act.Machine

$act.MachineAlias

This read-only string variable is the aliased name of the computer that caused the script action to fire.

Example:

myStr = $act.MachineAlias

$act.MachineIP

IP address text string of the computer that the firing monitor is attached to

Example:

myStr = $act.MachineIP

$act.MachineID

Returns the numeric value that uniquely identifies this computer (Computer ID - CID) within the application. Useful in conjunction with the External API.

Example:

myID = $act.MachineID

$act.MonitorTitle

This read-only string variable is the title of monitor that caused this script action to fire.

Example:

myStr = $act.MonitorTitle

$act.MonitorType

This read-only string variable is the type of monitor that caused this script action to fire.

Example:

myStr = $act.MonitorType

$act.SecondsInError

Number of seconds that the monitor has been in error.

Example:

inErrSeconds = $act.SecondsInError

$act.State

An array of string values that contain the OK or PROBLEM state for each item being reported on. See Row Variables from the "Variables..." button for the action.

Example:

myStr = $act.State[0]

$act.SendMail

This method sends an email message to the recipient that you choose. This would be useful for sending the incoming Details variable to a different email recipient based on some external factors (such as who is currently carrying the pager)

Example:

$act.SendMail "to_address@host.com", "from_address@host.com", "Subject of message", "Body of email message"

$act.SetComputerCustomPropByID

Custom Properties exist on groups, computers and monitors. This function lets you set the custom property on a computer. You can specify the computer ID in the first parameter, or set it to 0 to indicate the computer the actions is running for should be targeted.

Example:

   $act.SetComputerCustomPropByID(0, "DEVICEID", "BSQL")

Sleep

This is a PowerShell cmdlet that takes two parameters and is not part of the $act object. The first parameter specifies timer in seconds (-s) or milliseconds (-m) and the second is an integer that specifies period of time.

Example:

Start-Sleep -s 10

$act.Status

A read-only string indicating the current status of the monitor. To see all possible values, See Row Variables from the "Variables..." button for the action.

Example:

myStat = $act.Status

$act.StatusText

A read-only string indicating the current status of the monitor. This is a more human-friendly value than Status. To see all possible values, See Row Variables from the "Variables..." button for the action.

Example:

myStat = $act.Status

$act.TimeInErrorStr

A text string of how long the monitor has been in error

Example:

myStr = $act.TimeInErrorStr

SSH

The SSH script works using replacement variables. You can use the variables below which will be replaced with the real values from the monitor. Then the finished script is set to the target computer to be executed.

$AlertID$
A unique integer value representing this error. If Event Deduplication is enabled, this value will represent the latest error of this type.
$CustomProp$
$CustomProp("propertyName")$ will be replaced with the value of propertyName which can from from the source monitor, source computer or a parent group.
$Date$
Date in a human-readable format
$Details$
Details of the alert, meaning the text that is normally seen in an email alert for example.
$Details_Single_Line$
Same as $Details$ above, but all new lines and carriage returns have been removed
$Group$
Name of the group that the owning monitor is in (i.e. could be a value like "Routers").
$GroupPath$
Full path name of the group that the owning monitor is in (i.e. could be a value like "Servers/Devices > Boston > Routers")
$Machine$
Name of the target server
$MachineAlias$
Alias of the target server if one has been set. There will be no value (meaning an empty string) if no alias has been set.
$MachineID$
Internal ID representing the target server. These IDs can be obtained using the External API.
$MachineIP$
IP address of the target server
$MonitorType$
Textual name of the monitor type (i.e. "Event Log Monitor")
$NL$
Value that gets turned into a carriage return-newline pair.
$Status$
Text representing the monitor status. To see all possible values, See Row Variables from the "Variables..." button for the action.
$StatusText$
A text value that is more human-friendly that $Status$ above. To see all possible values, See Row Variables from the "Variables..." button for the action.
$Time$
Human readable time on the monitoring server.
$TimeInError$
Human readable amount of time the monitor has been in an error/alert state.

Example VBScripts


Connect to a database

Option Explicit
Dim objconnection
Dim objrecordset
Dim strDetails

Const adOpenStatic = 3
Const adLockOptimistic = 3

Set objconnection = CreateObject("ADODB.Connection")
Set objrecordset = CreateObject("ADODB.Recordset")

objconnection.Open _
   "Provider=SQLOLEDB;Data Source=;" & _
   "Initial Catalog=;" & _
   "User ID=;Password=;"

objrecordset.Open "", objconnection, adOpenStatic, adLockOptimistic

Delete Log Files

DirToCheck = "C:\Logs"
ExtensionToDelete = "txt"

set oFSO = CreateObject("Scripting.FileSystemObject")
set oFolder = oFSO.GetFolder(DirToCheck)
For Each aFile In oFolder.Files
   if(oFSO.GetExtensionName(aFile.Path) = ExtensionToDelete) then
      oFSO.DeleteFile(aFile.Path)
   end if
Next

Example PowerShell


Delete Log Files

$TargetFolder = "D:\Testing Dir\"
$strFileName = "*.txt"

get-childitem $TargetFolder -include $strFileName -recurse | foreach ($_) {remove-item $_.fullname}

Your Script


If you would like to share your script, please contact us.

PA Server Monitor

Help Map