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

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 Version	38
Anti-virus Pattern File	39
Anti-virus Pattern File Date	40
Anti-virus Status	41
Operating System	18
OS Architecture	19
OS Version	20
OS Last Boot Time (_time_t UTC value)	21
OS Current Time (_time_t UTC value)	22
CPU Count	13
CPU Name (multi value)	15
CPU Number of Cores (multi value)	16
CPU Clock Speed (multi value)	17
Display Name	6
Drive Status (multi value)	23
Domain	9
Manufacturer	10
Page File size in MB	24
RAM in MB	14
System Architecture	12
System Model	11
Time Zone Offset	8
Uptime % this month	28
Uptime % last month	29

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

RunAction

This method allows you to run other actions from within the script. The method takes an action ID to specify which action to run. Action IDs can be viewed in the Console by enabling the View > Show Object IDs in Navigation Tree menu item.

Example:

RunAction 12

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")

The Custom Property DISPLAYED_NOTES is the value you can set by right-clicking a computer and selecting Notes. Notes show up at the top of a Server Status Report.

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

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

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

//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);

Anti-virus Version	38
Anti-virus Pattern File	39
Anti-virus Pattern File Date	40
Anti-virus Status	41
Operating System	18
OS Architecture	19
OS Version	20
OS Last Boot Time (_time_t UTC value)	21
OS Current Time (_time_t UTC value)	22
CPU Count	13
CPU Name (multi value)	15
CPU Number of Cores (multi value)	16
CPU Clock Speed (multi value)	17
Display Name	6
Drive Status (multi value)	23
Domain	9
Manufacturer	10
Page File size in MB	24
RAM in MB	14
System Architecture	12
System Model	11
Time Zone Offset	8
Uptime % this month	28
Uptime % last month	29

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;

RunAction

RunAction(12);

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

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");

The Custom Property DISPLAYED_NOTES is the value you can set by right-clicking a computer and selecting Notes. Notes show up at the top of a Server Status Report.

Sleep

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

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

if($act.AlertType)

$act.ChangeMonitorStatus

SetMonitorStatus is a function that sets the status of any monitor. This function takes three values: Monitor ID, Monitor Status, and Status Text. The Monitor ID is assigned in the monitoring service and you can find the ID value by showing the IDs from the View menu and then looking in the navigation colunm. If you use 0 for the Monitor ID the function will change the staus of the monitor the action is attached to. There are four statuses that are available: msOK, msAlert, msError, and msDISABLED. The Status Text is the message that you can supply that is listed for the monitor and will be shown in reports.

Example:

$act.ChangeMonitorStatus(43, $act.msAlert, "Status changed for monitor")

Possible values:

Monitor Status	Values
OK	$act.msOK
Alert	$act.msAlert
Error	$act.msError
Disabled	$act.msDISABLED
Alert Show as Green	$act.msALERT_GREEN
Alert Show as Red	$act.msALERT_RED

$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

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.GetCredentials

The GetCredentials function lets your script request credentials for use within the script. The relevent setting must be enabled (disabled by default) in the Security Protected Settings. This function takes two parameters: A server name/key value, and a credential type.

Credential types can be one of: ctWIN, ctESX, ctSSH, ctAWS, ctCUSTOM

Example:

$user = ""
$info = ""
$pass = ""
if ($act.GetCredentials("TEST-ENV-DB", [PALowPriorityHelper_Net4.CredType]::ctCUSTOM, [ref]$user, [ref]$info, [ref]$pass))
{
#use credentials
}
else
{
#failed to get credentials
}

Because of the concern of scripts exfiltrating credentials, we recommend locking monitors or actions that use the GetCredentials function.

$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:

Status	status
Error Text	errText
Dependency	depends_on
Title	title
Error Action IDs	errActionIDs
Scheduled Next Run Time	nextRun
Time in Error (seconds)	inErrSeconds
Fixed Action ID	fixedActionIDs
Last Run Time	lastRun

$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 Name	name
Group Level	group
Group ID	groupID
Status	status
Alias for Server	alias

$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

//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)

Anti-virus Version	38
Anti-virus Pattern File	39
Anti-virus Pattern File Date	40
Anti-virus Status	41
Operating System	18
OS Architecture	19
OS Version	20
OS Last Boot Time (_time_t UTC value)	21
OS Current Time (_time_t UTC value)	22
CPU Count	13
CPU Name (multi value)	15
CPU Number of Cores (multi value)	16
CPU Clock Speed (multi value)	17
Display Name	6
Drive Status (multi value)	23
Domain	9
Manufacturer	10
Page File size in MB	24
RAM in MB	14
System Architecture	12
System Model	11
Time Zone Offset	8
Uptime % this month	28
Uptime % last month	29

$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.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.MachineIP

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

Example:

myStr = $act.MachineIP

$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.RunAction

$act.RunAction(12)

$act.SecondsInError

Number of seconds that the monitor has been in error.

Example:

inErrSeconds = $act.SecondsInError

$act.SendMail

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

NOTE: It works best if the From address is the same From address being used in your Email Actions.

$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")

The Custom Property DISPLAYED_NOTES is the value you can set by right-clicking a computer and selecting Notes. Notes show up at the top of a Server Status Report.

$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.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

myStat = $act.Status

$act.TimeInErrorStr

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

Example:

myStr = $act.TimeInErrorStr

$act.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:

$act.ToLog "Arrived at first loop"
$act.ToLog $resultVal

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

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(propName)$: $CustomProp(propertyName)$ will be replaced with the value of propertyName which came from from the source monitor, source computer or a parent group. It will be blank if the property is not defined.
$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.

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

Check files in a directory

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

Execute Script Action

Topics

Additional Script Elements

VBScript

JavaScript

PowerShell

SSH

Example VBScripts

Example PowerShell

PA Server Monitor