Writing Recovery Scripts for the Script Alert

SiteScope has the ability to execute scripts or batch files when an error or warning status is detected. This is normally done by creating a Script Alert that will act as a trigger for the script. The script or batch file can execute any system command or call other programs written in any language. You can use this to create recovery scripts to automatically respond to critical conditions or failures.

The Script alert file that SiteScope is to execute must be located in the <SiteScope install path>/SiteScope/scripts directory or in the <SiteScope user home>/scripts directory on a remote Unix machine (for remote scripts). For example, if SiteScope is installed in the directory C:\SiteScope and your script is called actionTest.bat, SiteScope will try to execute the following command line in response to Script Alerts you have created: C:\SiteScope\scripts\actionTest.bat C:\SiteScope\scripts monitor_name good...

where C:\SiteScope\scripts is the first command line parameter, monitor_name is the second command line parameter, and so forth,

Note: While the local script executed by the Script ALert must reside in the <SiteScope install path>/SiteScope/scripts directory, the execution path is the <SiteScope install path>/SiteScope/classes directory. You should use full pathnames for any file system commands or programs called by the script to avoid problems with defining the current execution directory.

The action taken by a script is determined by the creator of the script. SiteScope passes several command line arguments to each script called by a Script Alert. You can use this to have program scripts take action based on information sent from SiteScope. By default, SiteScope passes the following parameters to each Script alert as command line arguments:

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 for the monitor
any additional parameters specified in the Parameters text box on the Script Alert form

These command line arguments can be accessed by the target script using the normal command line variable conventions of %1, %2, %3, and so forth, for Windows NT systems and $1, $2, $3, and so forth, for Unix scripts (depending on the scripting shell or language used). Note that the first six parameters shown above (that is, %1 through %6) are passed by default to each script. If you want to pass other parameters than these, the property variables or parameters must be added to the Script Alert form in the Parameters text box to make them available to the script. The first variable or text entered in the Parameters text box will then be accessible as %7 by the script. The second parameter is accessed as %8 and so forth.

An example using Perl to access Script Alert parameters:

        print "pathname to scripts directory: $ARGV[0]\n";
        print "name of monitor causing alert: $ARGV[1]\n";
        print "current status monitor: $ARGV[2]\n";
        print "pathname to alert message file: $ARGV[3]\n";
        print "id code of monitor: $ARGV[4]\n";
        print "group for the monitor: $ARGV[5]\n";

An example Batch File in Microsoft Windows NT:

        echo pathname to scripts directory: %1
        echo name of monitor causing alert: %2
        echo current status monitor: %3
        echo pathname to alert message file: %4
        echo id code of monitor: %5
        echo group for the monitor: %6

Passing Data from SiteScope to a Script

Besides the seven default parameters, there are two other mechanisms for passing parameters and data to scripts. One is to use the additional parameters text box in the Script Alert form. The other is to access the Alert Message File.

The simplest way to send additional custom parameters and data to script is to use the Parameters box on the Script Alert form. The seventh default parameter passed to the script, any additional parameters specified on the alert form, allows you to specify one or more custom parameters to be sent to the script. These parameters are specified in the Parameters text box on the Add Script Alert page. These parameters could be hard coded and multiple parameters are separated by spaces. For example, assume you want to pass the four text strings shown below to a script. To do this you enter them in the Parameters text box as follows:

These would then become the seventh through tenth command line parameters sent to the script. The following batch file script would print the default parameters as well as the additional custom parameters entered in the Parameters text box of the Alert form:

An example of Batch File accessing additional custom parameters:

        echo pathname to scripts directory: %1
        echo name of monitor causing alert: %2
        echo current status monitor: %3
        echo pathname to alert message file: %4
        echo id code of monitor: %5
        echo group for the monitor: %6
        echo seventh parameter(customA): %7
        echo eighth parameter(customB): %8
        echo ninth parameter:(customC) %9
        echo tenth parameter(customD): %10

The other method for passing data and SiteScope monitor parameters to a script is to use the Alert Message File. This is a file that is created by SiteScope using the alert template specified in the Script Alert form. You can create your own custom alert templates and pass custom text strings or any of the SiteScope parameters available. See the chapter on Template Properties in the SiteScope Reference Guide for more information on available SiteScope parameters. See the chapter on Custom Alert Templates in the SiteScope Reference Guide for more information about modifying alert templates.

The following shows the NTEventLog template included with SiteScope. The parameters marked with < > brackets are replaced with the applicable values to and written to the Alert Message File each time the applicable Script Alert is triggered.

The NTEventLog script alert template

Type:       <eventType>
Event Time:     <eventTime>
Source:     <eventSource>
ID:         <eventID>
Category:   <eventCategory>
Machine:    <eventMachine>
Message:    <eventMessage>

Monitor:  <name>
Group:    <group>
Sample #: <sample>
Time:     <time>

<mainParameters>
<mainStateProperties>

In order to use this data in a script, your script will need to access the Alert Message File at the pathname location specified by the fourth default command line parameter (see the list above). Then the script will have to parse the content of the Alert Message File to extract the data you want to use in your script.

For more examples of how to write recovery scripts, look at the script files in the <SiteScope install path>/SiteScope/scripts directory. The actionTest.bat example is a template you can use to create your own script. The perlTest.pl example shows how to call a Perl script. The restartIIS.bat, restartService.bat, and restartServer.bat scripts implement common recovery actions.

For the Unix environment, the examples scripts are called actionTest.sh and perlTest.pl