Script Alerts

SiteScope has the ability to automatically execute scripts or batch files when an error or warning status is detected. This is done using the SiteScope Script Alert. The script or batch file that is called can execute any system command or programs in other languages that can be called from a command line entry. You can use this to create recovery scripts to automatically respond to critical conditions or failures. This might include rebooting a server or copying files.

Working with Script Alerts

In working with Script Alerts it is important to understand the different components that are involved and the role that they play. The three most important are:

the Script Alert instance itself
the monitor or monitors that are assigned to trigger the alert
the script to be executed by the alert

The alert message template and resulting alert message file may also need to be considered depending what the script needs to do.

The Script Alert instance and the monitor or monitors that trigger the alert are handled as with any other alert or monitor in SiteScope. For example, you may create a monitor to watch a Web server running on a remote Unix server. You can create a Script Alert associated with that monitor that will execute a script to reboot the Web server process if the monitor reports an error.

Creating the script to be called or executed by the Script Alert is the other key step in using this automation capability in SiteScope. The specific commands and actions taken by the script are up to you. The script file should be written as a plain text file compatible with the operating system under which your SiteScope service is running. To run a script on the machine where SiteScope is running the script file must be saved in the <SiteScope install path>/SiteScope/scripts directory on the SiteScope machine where the Script Alert is defined. To run a script on a remote machine, you must save the script in a directory called /scripts in the directory tree that SiteScope has permissions to execute scripts in on the remote machine.

The current execution directory when a script is run is SiteScope\classes\ not the SiteScope\scripts\ directory. This is to say that for commands executed by the script itself, the relative execution directory is SiteScope\classes\. You should use full pathnames for any other file system commands or programs called by your script so you will not need to worry about the current directory. Also, the server system environment variables may not have been set up for the script execution, which is another reason you should use full pathnames for executables called by the script. If a script works when you run it from the command line, but not from SiteScope then this is something to check out.

Passing Data to a Script

SiteScope passes a number of parameters to the script as command line arguments. You can use this option to pass data to a script that can be used to modify a script's action. This adds versatility to the Script Alert.

By default, a SiteScope Script Alert passes seven command line arguments to a script. These are:

the pathname of the scripts directory
the name of the monitor that caused the alert
the current status of the monitor
the pathname to the Alert Message File
the id code of the monitor
the group the monitor is in
any additional parameters specified on the Parameters text box in the alert form

Two of these default arguments allows the script to access even more data. One is the Alert Message File and the other is the Parameters text box. The Alert Message File is a temporary text file created by SiteScope based on the alert template chosen for the Script Alert instance. Depending on the template you create or use, the Alert Message File may contain custom information as well as data specific to the monitor that triggered the alert. By passing the pathname to the Alert Message File to the script, you can have the script access this data.

You use the Parameters text box to specify individual monitor parameter data to be passed to the script. You can include multiple parameters by separating the parameters with spaces. This effectively allows you to increase the total number of parameters passed to the script at will. See the chapter on Template Properties in the SiteScope Reference Guide for more information on available parameters used for the different SiteScope monitors.

The pathname of the scripts directory can be useful in setting a execution path to another program as well as setting a directory path for any output written by the script.

Troubleshooting Scripts

The scripts are run with the permissions of the account used by the SiteScope service. Some scripts may need extra permissions and you will need to use the Services control panel to change the login account for SiteScope and then stop and start SiteScope. For example, scripts that restart services or reboot remote machines or scripts that copy protected files.

Since the script is run by the SiteScope service, anything done as part of your "login" will not have occurred in the script. For example, you can not rely on mapped drives, environment variables, or other login script items.

Since the script is run by the SiteScope service it can not receive any interactive input from a keyboard or other input device. Any script action or command that requires a user confirmation or input would cause the script to hang. Do not include any interactive commands requiring a user action as part of the script. Also, opening a win32 app (for example, Notepad) will also cause the script to hang because it will be waiting for the a user to exit or close the application before continuing with the script execution.

Creating a Script Alert Definition

Follow the steps below to create a SiteScope Script Alert definition.

Click the Alerts button on the SiteScope main navigation bar at the top of the SiteScope screen. The Alert Definitions page is displayed.
Click the Add link in the Alert Actions section below the Alert Definitions table. The Add Alert selection page is displayed.
Select the monitor status category that will trigger the alert. For example, select error for the alert to be triggered when any monitor to be associated with this alert reports an error condition.
Select the Script Alert in the Alert Type section and click the Define Alert button. The Define Script Alert page is displayed.
Select the monitors or groups that will trigger this alert using the Alert Subject(s) menu tree. Complete the Define Script Alert form as described in the section below. When the required selections are made, click the Add Script Alert button to create the alert definition.

Completing the Script Alert Form

Complete each section of the form as described below and then click the Add or Update button. Refer to the Advanced Topics section of the User Guide for information about writing recovery scripts.

Alert Subject(s)

Select the groups or monitors that will trigger this alert. You can select multiple groups and monitors by holding down the control key while making your selection. The choices include:

All Groups - Select All Groups if you want SiteScope to perform an action whenever any monitor on this installation returns the indicated status condition. For example, you would choose this option if you want SiteScope to page you whenever any monitor returns an error status.

[group name] - Select a specific group if you want SiteScope to perform an action whenever any monitor in the selected group returns the indicated status condition. For example, you would select the Network group if you wanted SiteScope to page you if any monitor in the Network group returned an error status.

[group name]: [monitor name] or [group name]:[subgroup name]: [monitor name] - Select a specific monitor if you want SiteScope to perform an action only if the selected monitor returns the indicated status condition. For example, you would choose this option if you wanted SiteScope to send you e-mail if one specific monitor returned a warning status.

Alternatively, you may select all groups or multiple groups and then define an alert filter rule in the Global and Group Alert Filtering section under the Advanced Options on the lower portion of the page.

Run Script

Complete this section to specify the script to be run including the server, the script filename, the template to use in passing a file to the script, and any additional monitor parameters to be passed to the script.

Server
Select the server on which the script should be run. On remote Unix servers, you will need to create and scripts subdirectory and copy the script file to the remote machine. The " scripts" directory must be included in the remote login account that allows remote scripts to be invoked by SiteScope.

Script
Select the script that you want SiteScope to run in response to the selected condition. You may create as many custom scripts as you need. If you choose to create your own scripts, you must place them in the <SiteScope install path>/SiteScope/scripts directory or the applicable scripts directory on a remote machine. SiteScope will list all files found in this directory on the selected server in the drop-down list.

Template
SiteScope creates a file containing information about the monitor that caused the error and passes the filename to your script as the fourth command line argument. Use the Template drop-down list to have SiteScope create the file using a different template. The template file includes SiteScope property variables which instruct SiteScope what data to include in the file. You can add your own custom templates into the SiteScope\templates.script directory. See the chapter on Template Properties in the SiteScope Reference Guide for more information on available parameters that can be used in templates.

Parameters
Specify any additional monitor parameters that you want to pass to your script. By default, the Script Alert always passes six parameters to a script as command line arguments. These are:

the pathname of the scripts directory
the name of the monitor that caused the alert
the current status of the monitor
the pathname to the alert message file
the id of the monitor
the group for the monitor

Parameters added into the Parameters text box are sent as the seventh, eighth, ninth, and so forth, command line arguments respectively. The parameters available to be passed to the script are dependent on the type of monitor that triggers the alert. A list of SiteScope parameters available from each kind of monitor are listed in the chapter on Template Properties in the SiteScope Reference Guide. The syntax to use for additional parameters is to surround the property name variable as shown in the properties list with < > brackets. For example, to pass the server name to the script, enter <_machine> in the Parameters text box. To pass more than one extra parameter, separate the parameters with a single space the same way the arguments would be added on the command line.

When

The number of times the alert conditions should be met before SiteScope executes the action you specified.

Always, after the condition has occurred at least N times - After the condition occurs at least N times, SiteScope executes the action every time the alert conditions are met. Type the minimum number of times the alert conditions must be met in the text box.
Once, after condition occurs exactly N times - SiteScope executes the action once, after the conditions are met for the Nth time. Type the number of times the alert conditions must be met in the text box.
Initial alert X and repeat every Y times afterwards - Executes the alert action after the condition occurs X consecutive times and then repeats the alert every consecutive Y occurrences thereafter. For example,if X was set to 3, and Y was set to 4, then the action would be triggered on the 3rd, 7th, 11th, and so forth, occurrences of the condition. Choose this option by selecting the applicable radio button, entering the multiple (E) and the minimum number of times (N) the alert conditions must be met in the text input boxes provided.
Note: This feature was modified in SiteScope version 5.5. Alert parameters set for this option in prior versions are transposed to this new format when upgrading to version 5.5 and may result in a change in the originally intended behavior.
Once, after N errors in this group - SiteScope executes the action only after any monitor in the group has been in error exactly N consecutive times. Type the number of errors in the text box.
Once, when all monitors of group are in error - SiteScope executes the action the first time all monitors in the group are in error.

Advanced Options

The Advanced Options section presents a number of options for disabling the alert and define a filter for conditions that should trigger the alert.

Disable Alerts

Use the Disable Alerts alerts section to manually control suppression of this alert. This can be useful when the the systems being monitored are off-line for maintenance or if the recipient of the alerts is unavailable for a period of time.

Enable Alert: This check box cancels any disable conditions and makes the alert active. Select this radio button to override any disable action on the alert.
Disable alert permanently: Select this radio button to prevent SiteScope from executing the alert action, even if the conditions are met. Note: This permanently disables the alert action until this radio button is cleared.
Disable alerts for the next time period: Select this radio button to immediately prevent SiteScope from executing the alert action for the time period entered, even if the conditions are met. The alerts are re-enabled when the time period expires. This is useful for temporarily turning off alerts immediately.
Disable on a one-time schedule from time1 to time2: Select this radio button to prevent SiteScope from executing the alert action for the time period indicated, even if the conditions are met. The alerts are disabled at the beginning of the time period and re-enabled after the time period expires. This is useful for temporarily turning off alerts during scheduled maintenance.

Global and Group Alert Filtering

You can use the Global and Group Alert Filtering option to define alerts for a large number of monitors and then apply a filter so that only certain monitors within the selected list will actually trigger the alert. See Using SiteScope Alerts for more information.

Name Match: This option lets you suppress the alert for all associated monitors except those with a specific text appearing as part of their name. Enter all or part of the monitor name string you want to use as a filter criteria. For example, entering the string URL: will limit this alert to monitors whose name contains the string "URL:". The match is case sensitive. You can enter a regular expression in this text box to match a status string pattern
Status Match: This option lets you suppress the alert for all associated monitors except those returning a specific status text. Enter a string that you expect to appear in the status text for the monitor you want to trigger this alert. For example, if you type timeout in this box, an alert will only be triggered by a monitor associated with this alert which also has a status of "timeout." This match is case sensitive. You can enter a regular expression in this text box to match a status string pattern
Monitor Type: You can usethis option to select a specific monitor type match for the alert. Select the monitor type within the set of monitors associated with this alert that should actually trigger the alert. Select Any Monitor to trigger the alert action for any monitor type associated with this alert.