The Execute Script Monitor allows you to write your own custom scripts in the VBScript, JavaScript, PowerShell languages, or via an SSH connection to a host. You can check anything that your script can access. For VBScript, JavaScript and PowerShell, this monitor makes use of the applicable scripting engine that is already installed on nearly all Windows computers.
The script window is where you enter your script. The script can do anything that can be done in the selected language (including creating external components if available) with all the standard restrictions.
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
A good VBScript reference is available at: http://msdn.microsoft.com/enus/library/d1wf56tt.aspx ComputerName
This readonly string variable is the name of the computer that the monitor is attached to.
Example:
myStr = ComputerName 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 rightclicking on the item and choosing the Custom Properties menu.
Example:
myStr = CustomProp("NotifyGroupID") Details
This is a string value. This value is passed to any attached actions as the details for the action (ie the content of an email notification for example).
Example:
Details = "Alert! Can't contact remote system"
FireActions
This is a boolean value. If the value is set to True, actions attached to the monitor will fire. If it is False, they will not fire. The value defaults to False.
Example:
FireActions = true GetStatID
RecordStat
GetStatID and RecordStat are used together to record integral data values to the database for reports.
GetStatID is a function that takes a single string value and returns an integer statID. The string value should be a useful name to you, such as the name of the thing you're probing with the script. Including the
server/device name in the string would be a good idea if a similar script will run on multiple computers it will make it easier to choose the specific data that you want when you create reports.
Example:
statID = GetStatID("ftpSvr1myObject")
RecordStat is a method that takes two inputs the statID obtained from GetStatID above, and the integer value to record to the database. The time the value is recorded also gets saved to the database for use in line charts, etc.
Example:
RecordStat statID, objectValue GetValue
StoreValue
GetValue method takes a text name and returns the value that was stored earlier via the StoreValue call described below. If nothing was ever stored with that name, an empty string is returned.
Example:
prevState = GetValue("LastState")
The StoreValue method takes a text name, and a text value and stores it. This named value can be retrieved later (even when the script runs next) via GetValue. Note that these values will be persisted in the
configuration database and kept in memory with the monitor, so they should be kept relatively small (a few hundred characters long or less).
Example:
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).
Antivirus Version 38
Antivirus Pattern File 39
Antivirus Pattern File Date 40
Antivirus 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
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 ReportResults
This method will take the current value of FireActions and Details and report the result as though the monitor had finished. This is a way for a monitor to report multiple individual errors, similarly to how some other monitors have a "report each event separately" check box.
Example:
ReportResults SendMail
This method sends an email message to the recipient that you choose. This method can also send the email in HTML format if it sees the <!DOCTYPE in the body of the message.
Example:
SetComputerCustomPropByID(0, "DEVICEID", "BSQL") Sleep
This VBScript 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 monitors to sleep for very long means other monitors may not get run.
Example:
Sleep 1500 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 MONITOR_SCRIPT_LOG.
Example:
ToLog "Arrived at first loop"
ToLog resultVal
JavaScript
ComputerName
This readonly string variable is the name of the computer that the monitor is attached to.
Example:
myStr = ComputerName;
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 rightclicking on the item and choosing the Custom Properties menu.
Example:
myStr = CustomProp("NotifyGroupID");
Details
This is a string value. This value is passed to any attached actions as the details for the action (ie the content of an email notification for example).
Example:
Details = "Alert! Can't contact remote system";
FireActions
This is a boolean value. If the value is set to True, actions attached to the monitor will fire. If it is False, they will not fire. The value defaults to False.
Example:
FireActions = true;
GetStatID RecordStat
GetStatID and RecordStat are used together to record integral data values to the database for reports.
GetStatID is a function that takes a single string value and returns an integer statID. The string value should be a useful name to you, such as the name of the thing you're probing with the script. Including the
server/device name in the string would be a good idea if a similar script will run on multiple computers it will make it easier to choose the specific data that you want when you create reports.
Example:
statID = GetStatID("ftpSvr1myObject");
RecordStat is a method that takes two inputs the statID obtained from GetStatID above, and the integer value to record to the database. The time the value is recorded also gets saved to the database for use in line
RecordStat(statID, objectValue);
GetValue StoreValue
GetValue method takes a text name and returns the value that was stored earlier via the StoreValue call described below. If nothing was ever stored with that name, an empty string is returned.
Example:
prevState = GetValue("LastState");
The StoreValue method takes a text name, and a text value and stores it. This named value can be retrieved later (even when the script runs next) via GetValue. Note that these values will be persisted in the
configuration database and kept in memory with the monitor, so they should be kept relatively small (a few hundred characters long or less).
Example:
StoreValue("LastState", "1|15|OK");
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).
Antivirus Version 38
Antivirus Pattern File 39
Antivirus Pattern File Date 40
Antivirus 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
This method will take the current value of FireActions and Details and report the result as though the monitor had finished. This is a way for a monitor to report multiple individual errors, similarly to how some other monitors have a "report each event separately" check box.
Example:
ReportResults();
SendMail
This method sends an email message to the recipient that you choose. This method can also send the email in HTML format if it sees the <!DOCTYPE in the body of the message.
Example:
SendMail("[email protected]", "[email protected]", "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 the computer whose ID is given (first parameter), or use 0 to indicate the computer the monitor is running on 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 monitors to sleep for very long means other monitors may not get run.
Example:
Sleep(1500);
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 MONITOR_SCRIPT_LOG.
Example:
ToLog "Arrived at first loop"
ToLog resultVal
PowerShell
PowerShell interaction happens via the $mon object.
$mon.ComputerName
This readonly string variable is the name of the computer that the monitor is attached to.
Example:
$myStr = $mon.ComputerName
$mon.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 rightclicking on the item and choosing the Custom Properties menu.
Example:
$myStr = $mon.CustomProp("NotifyGroupID")
$mon.Details
This is a string value. This value is passed to any attached actions as the details for the action (ie the content of an email notification for example).
Example:
$mon.Details = "Alert! Can't contact remote system"
$mon.FireActions
Example:
$mon.FireActions = $true
$mon.GetStatID $mon.RecordStat
GetStatID and RecordStat are used together to record integral data values to the database for reports.
GetStatID is a function that takes a single string value and returns an integer statID. The string value should be a useful name to you, such as the name of the thing you're probing with the script. Including the
server/device name in the string would be a good idea if a similar script will run on multiple computers it will make it easier to choose the specific data that you want when you create reports.
Example:
$statID = $mon.GetStatID("ftpSvr1myObject")
RecordStat is a method that takes two inputs the statID obtained from GetStatID above, and the integer value to record to the database. The time the value is recorded also gets saved to the database for use in line charts, etc.
Example:
$mon.RecordStat($statID, $objectValue)
$mon.GetValue
$mon.StoreValue
The GetValue method takes a text name and returns the value that was stored earlier via the StoreValue call described below. If nothing was ever stored with that name, an empty string is returned.
Example:
$prevState = $mon.GetValue("LastState")
The StoreValue method takes a text name, and a text value and stores it. This named value can be retrieved later (even when the script runs next) via GetValue. Note that these values will be persisted in the
configuration database and kept in memory with the monitor, so they should be kept relatively small (a few hundred characters long or less).
Example:
$mon.StoreValue("LastState", "1|15|OK")
$mon.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 = $mon.InventoryValue(18);
//returns the Operating System (18) for the current computer (0 means use default) myStr = $mon.InventoryValue(18, 0);
//returns the Operating System (18) for computerID 238 myStr = $mon.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).
Antivirus Version 38
Antivirus Pattern File 39
Antivirus Pattern File Date 40
Antivirus Status 41
Operating System 18
OS Architecture 19
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
$mon.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 = $mon.MachineID
$mon.ReportResults
This method will take the current value of FireActions and Details and report the result as though the monitor had finished. This is a way for a monitor to report multiple individual errors, similarly to how some other monitors have a "report each event separately" check box.
Example:
$mon.ReportResults()
$mon.SendMail
This method sends an email message to the recipient that you choose.
Example:
$mon.SendMail("[email protected]", "[email protected]", "Subject of message", "Body of email message")
$mon.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 monitor is running on should be targeted.
Example:
$mon.SetComputerCustomPropByID(0, "DEVICEID", "BSQL") StartSleep
The PowerShell cmdlet takes two parameters. The first parameter specifies timer in seconds (s) or milliseconds (m) and the second is an integer that specifies period of time.
Example:
StartSleep s 10
SSH
SSH is a little different than the others. In this case, your script will be sent to the remote computer/device to run. The resulting terminal output is scanned for the special keywords below, and they will be 'executed' in the monitoring service when the script finishes. The keywords have to start in the very first column to be recognized.
PA_Details
This is a string value. This value is passed to any attached actions as the details for the action (ie the content of an email notification for example). This particular value can span multiple lines. The value is terminated when a ") is seen.
Example:
PA_Details("Alert! Can't contact remote system") PA_FireActions
This is a boolean value. If the value is set to true, actions attached to the monitor will fire. If it is false, they will not fire. The value defaults to false.
PA_RecordStat
This 'function' will record a statistic returned from the script to the database. It is equivalent to GetStatID and RecordStat in the other languages above.
The first parameter is a string value. The string value should be a useful name to you, such as the name of the thing you're probing with the script. The second value is a numeric value that will be stored.