As you may already know, Lithium actions are based on action scripts. This allows for you to customise Lithium, and the way in which it reacts to your network and any incident that is raised.

An explanation on Lithium Actions and how to set up an Action can be found here.

The best place to look for information on what kind of service monitoring scripts are currently available (and for hints on modifying scripts) are the Lithium Forums.

This document isn't intended to be a tutorial on How to write Perl scripts. Instead, it is a guide to explain the structure of the action scripts used by Lithium, and how to customise Lithium to do what you want it to.

If you have played around with Service Monitoring Scripts, you will notice a few similarities in the structure of the scripts.

Anatomy of an Action Script

Each script is broken down into 7 sections: Use Modules , Script Configuration Variables , Command Processing , Handling of an Incident Report , Handling of an incident reminder (re-run), Handling of incident cleared , and Standard funcitons .

 Out of all the sections in the script, the only parts that require any modification are: Use modules, Configuration Variables, and the handling of each type of report: Report, Remind and Clear. Everything else should not be modified.

All code and examples used in this document are taken from the email_alert.pl script that is installed with Lithium.

Use Modules

For those of you not familiar with Perl scripts, the very first line of the script:

#! /usr/bin/perl

Instructs the script where to find your Perl interpreter.  This line is required and doesn't need to be changed.

The next group of lines beginning  with the word "use", indicates to Perl which modules this script uses. Because the transfer of Configuration variables is all done via XML, the "XML::Simple" module is required for ALL action scripts.

So the beginning of each Service monitoring script should look like:

The modules your scripts require will obviously depend on what you need the script to do. Lithium installs all required modules from the Comprehensive Perl Archive Network (http://www.cpan.org ). The CPAN website is a good place to begin your search for any module you may require.

You don't need to worry about manually installing any Perl modules onto your Lithium server. When you Upload a script via the Script Management window of Lithium (or click the Repair button), Lithium parses over the script and ensures all required Modules are installed and up to date.

Script Configuration Variables

This section is where you declare the variables that your script will use, eg. Mail server address, List of email addresses.

Because Core communicates these variables to Console via XML, the variables are structured in a similar structure inside the script.

For the generic SMTP email script the  %xmlstruct  hash has the following basic structure:

Script	XML Equivilent	Console Screenshot
%xmlstruct = (  'desc' => "Generic SMTP Email Notification Script", 'version' => '1.0',   'config_variable'=>[ { 'name' => 'sender', 'desc'=>'Senders Email Address' }, { 'name' => 'mailhost', 'required' => '1', 'desc' => 'SMTP Server' }, { 'name' => 'replyto', 'desc' => 'ReplyTo: Address' }, { 'name' => 'recipients', 'required' => '1', 'desc' => 'Recipients (comma-separated)' } ] );	<xmlstruct> <desc>Generic SMTP Email Notification Script</desc> <version>1.0</version>  <config_variable>  <name>Sender</name> <desc>Senders Email Address</desc> </config_variable>  <config_variable>  <name>mailhost</name> <required>1</required>  <desc>SMTP Server</desc> </config_variable>    <config_variable>  <name>replyto</name> <desc>ReplyTo: Address</desc> </config_variable>  <config_variable>  <name>recipients</name> <required>1</required>  <desc>Recipients (comma-separated)</desc> </config_variable> </xmlstruct>

 Note, that the console expects to see all of the Key-Value Pairs listed above.

Key	Description
version	The version number of this script
desc	A short description of what the script does
config_variables	A List of variables unique to this script eg. test_account, test_password

 Because each script will require a different set of variables to complete it's task you are provided with the config_variables list.

 Each variable you want your script to use, needs to be in the same format as the test_account and test_password variables in the imap_check.pl script. If we want to mark a config variable as being required, we simply add a 'required' value to the variable  and set it to 1. See the 'mailhost' config variable in the above code for this.

In this example, Console will now indicate that the mailhost variable is required, and won't let the end user configure a service without it.

We will explain how to access these variables in the section on Handling Incident Reports.

Command Processing

This section of the script handles how the script runs depending on the command line arguments passed to it when it is run. There is nothing that needs to be changed in this section.

For those that are interested, each script can be run in one of 4 modes: Info, Report, Remind, and Clear.

Info:    This is the mode that Console runs to gather all the information about this script (description and config variables). When run in Info mode, the script simply prints the XML config structure to stdout. Console reads this output and interprets the information into Config variables.

Report:     Whenever an Action is first triggered, Lithium will run the script in Report mode. Actions can be configured to be triggered either manually or automatically (after x amount of seconds).

Remind:    Actions can also be set to remind after a set amount of time (in minutes). When an Action is run in Remind mode, you may wish to handle it differently than you would for the first report.

Clear:    The clear mode is automatically run whenever an incident is cleared. 

As mentioned above, you don't need to change anything in this section. It just provides a good view of the different modes that a script can be run.  

Handling of an Incident Report

The logic for each script is contained in the next three sections: Handling of an Incident Report, Handling of an incident reminder (re-run), Handling of incident cleared.

The only difference between these different subs (sections) is when they are called, as explained above. Because all of these subs are essentially structured the same, we'll just work through the reportIncident() sub. 

This is the sub where all of the logic of your script is found. The beginning of this sub contains some general housekeeping required to access all of the variables passed to the script.

1.  # 1 Parameter: Filename for the XML  2.    my ($filename) = @_; 3. 4.    # Retrieve action from ARGV 5.    %action = &getAction(); 6.   7.    # Extract Variables from XML and store in %variables Hash 8.    %variables = &getVariables($filename); 9.    10.   # Set variables from XML 11.   my @recipients = split (/[,;]/, %variables->{recipients}->{value}); 12.   my $replyto = %variables->{replyto}->{value}; 13.   my $mailhost = %variables->{mailhost}->{value}; 14.   my $sender = %variables->{sender}->{value};

Remember that the lines beginning with a # are comments, so in the above example lines 1, 4, 7 and 10 are all comments.

Console sends all the required variables to a script via a temporary file, the filename of this file is passed directly to this sub. Line 2 stores this in the $filename variable.

The next step is to store all of the action variables (entity, customer etc) locally. Line 5 calls the getAction() function and stores the results in th %actions hash.  

After we've grabbed our action variables, we now need to store a local copy of the config variables from the temporary file. Line 5 calls the getVariables function and passes it the filename. This function returns a Hash of all the variables. We store this hash in %variables.

Now that we have retrieved the config variables, we need a nice easy method of accessing them. Lines 12 through to 14 handle accessing the multiple levels of %variables and stores each variable locally.

No, I didn't forget about line 11. Because we are accessing a comma-separated list of recipients, I'll talk about that line separately.

All (except for list of values) of your config variables can be accessed in this way. For those of you that would like a worded explanation (warning: This may confuse you more). Line 12 can be  literally interpreted as:

* Grab the value of the "value" key of the "replyto" hash in the "%variables" hash and store it in the $replyto local variable *

Don't say I didn't warn you. However if you were to replace, "replyto" with the name of the variable you are after you will have access to it in a local variable of the same name: See the differences between lines 12, 13 and 14. 

Now I said Line 11 was a special case. For our email script, we are willing to accept recipients as a comma-separated list, So we can't just retrieve and store it like the other variables.

Looking at this line more closely, you can see that we use the split() function and store the results in the local list, @recipients. In perl we use the split() function to split a string based on a regular expression.  In our case the string we want to split comes directly from %variables, in the same way any other variable is accessed. The regular expression we use to split the string is "/[,;]/",  this tells the split function to split the string each time it comes across either a comma, or a semi-colon. The results of all this splitting are then stored in @recipients.

Now that we have stored all of the config variables, we're ready to jump into the main logic of this script. Well, almost... We still need to know as much information as possible about the action itself. Things like:

• incident_id
• entity_address
• state
• customer
• site,device
• container
• object
• metric
• trigger
• run_count
• start_time
• end_time

4.    # Retrieve action from ARGV 5.    %action = &getAction();

 

$device = %action->{device};

One final note when running scripts, is that Lithium stores an Execution Log for each action. If you want to provide information to the execution log, you simply need to use the print command: Eg. You may wish to add the following line to the end of your reportIncident,  remindIncident and clearIncident  subroutines:

print "Script run sucessful\n"; 

Standard functions.

These are the functions (subroutines)  that each script needs to perform it's basic tasks. There is no need to make any changes to this section of your script. You would have come across these subs in your script already, these are:

• generateConfig: Used to provide the XML structure for config variables
• getVariables: Used to get the config variables out of the file (generated by Lithium) and stores them as a hash
  
•  getAction: Used to extract action information from the command line

 Additional Resources: 

• Lithium Forums: Lithium Action Scripts
  
• Comprehensive Perl Archive Network (CPAN): http://www.cpan.org
• Wikipedia; Regular Expressions: http://en.wikipedia.org/wiki/Regular_expression