This help page is for version 5.2. The latest available help is for version 9.4.

Execute Script Monitor

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 ActiveX/COM 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.

Go to example scripts below

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

ComputerName	This read-only 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 right-clicking 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("ftpSvr1-myObject") 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: StoreValue "LastState", "1\|15\|OK"
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
SendMail	This method sends an email message to the recipient that you choose. Example: SendMail "to_address@host.com", "from_address@host.com", "Subject of message", "Body of email message"
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 read-only 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 right-clicking 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("ftpSvr1-myObject"); 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: StoreValue("LastState", "1\|15\|OK");
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
SendMail	This method sends an email message to the recipient that you choose. Example: SendMail("to_address@host.com", "from_address@host.com", "Subject of message", "Body of email message");
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 read-only 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 right-clicking 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	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: $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("ftpSvr1-myObject") 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.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.SendMail	This method sends an email message to the recipient that you choose. Example: $mon.SendMail("to_address@host.com", "from_address@host.com", "Subject of message", "Body of email message")
Start-Sleep	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: Start-Sleep -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 be 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 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). 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. Example: PA_FireActions(true)
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. Example: PA_RecordStat("Scans_Per_Second", 45.6)
PA_SendMail	This method sends an email message to the recipient that you choose. Example: PA_SendMail("to_address@host.com", "from_address@host.com", "Subject of message", "Body of email message")

Standard Configuration Options

Like all monitors, this monitor has standard buttons on the right for Adding Actions, setting Advanced Options and setting the Monitor Schedule.

Example VBScripts

Check a database value
Check files in a directory
Check the size of a specific file and record to a database
Check if the newest file is older than 6 hours old
Launch a program and check the result code
Check for text in a file

Check a database value

Option Explicit
Dim objconnection
Dim objrecordset
Dim strDetails

Const adOpenStatic = 3
Const adLockOptimistic = 3

FireActions = False

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

objconnection.Open _
"Provider=SQLOLEDB;Data Source=<data_base_server>;" & _
"Initial Catalog=<database_name>;" & _
"User ID=<username>;Password=<password>;"

objrecordset.Open "SELECT COUNT(*) FROM <database_name>", _
objconnection, adOpenStatic, adLockOptimistic

If objrecordset.RecordCount >= 1 Then
   objrecordset.MoveFirst
   'ensure there are at least 1000 rows
   If objrecordset.Fields(0) < 1000 Then
      FireActions = True
      strDetails = "There are only " & objrecordset.Fields(0) & " rows in the table!"
   End If
Else
   strDetails = "CODE RED !!!! No rows found!"
   FireActions = True
End If

Details = strDetails

Check files in a directory

dim highCount
highCount = 1000
Set fso = CreateObject("Scripting.FileSystemObject")
Set oSrcFolder = fso.GetFolder("\\server\dir\tocheck")
fileCount = oSrcFolder.Files.Count

if fileCount > highCount then
FireActions = True
else
FireActions = False
end if

Check the size of a specific file and record to a database

FileToCheck = "C:\Files\Backup\dump.db"

Set objFSO = CreateObject("Scripting.FileSystemObject")

If objFSO.FileExists(FileToCheck) Then
   Set objFile = objFSO.GetFile(FileToCheck)

   statID = GetStatID(FileToCheck)
   RecordStat statID, objFile.Size

   If objFile.Size < 1000 Then
      FireActions = True
      Details = FileToCheck & " is too small!"
   Else
      FireActions = False
   End If
Else
   FireActions = True
   Details = FileToCheck & " does not exist!"
End If

Check if the newest file is older than 6 hours old (to ensure new files are being created)

DirToCheck = "C:\Logs"
Dim fNewest
set oFolder=createobject("scripting.filesystemobject").getfolder(DirToCheck)
For Each aFile In oFolder.Files
   If fNewest = "" Then
      Set fNewest = aFile
   Else
      If fNewest.DateCreated < aFile.DateCreated Then
         Set fNewest = aFile
      End If
   End If
Next

if fNewest.DateCreated < (DateAdd("h",-6,Now())) then
   FireActions = True
   Details = "NEWEST LOG FILE older than 6 hours (latest file " & fNewest.DateCreated & ")"
else
   FireActions = False
end if

Launch a program and check the result code

Dim objShell
Set objShell = CreateObject("WScript.Shell")
'Spaces in the path below can cause trouble for the Run method
exitCode = objShell.Run("C:\Test\App.exe", 1, True)
Set objShell = Nothing

if (exitCode = 0) then 'assuming 0 means OK in this case
    FireActions = false
    Details = "Everything is OK"
Else
    FireActions = true
    Details = "Test app returned " + exitCode
End If

Check for text in a file

Option Explicit
Dim oFSO, sFile, oFile, sText
Set oFSO = CreateObject("Scripting.FileSystemObject")
sFile = "\\machine\share\textfile.txt"
If oFSO.FileExists(sFile) Then
    Set oFile = oFSO.OpenTextFile(sFile, 1)
    Do While Not oFile.AtEndOfStream
        sText = oFile.ReadLine
        If Trim(sText) = "ERROR" Then
            FireActions = True
        Else
            FireActions = False
        End If
    Loop
    oFile.Close
Else
    FireActions = True
End If

Thanks goes out to Seth Johnson at Williams for this

Example PowerShell

Check files in a directory

Check files in a directory

$mon.FireActions = $false
$mon.Details = ""
$highCount = 1000
$folder = "C:\Temp"
$files = Get-ChildItem $folder -Force

if ($files.Count -gt $highCount)
{
$mon.FireActions = $true
$mon.Details = "File Count is " + $files.Count
}

Your Script

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

	PA Server Monitor Help Map