Custom Actions
Calling a Program or Script
The Program action is used to run a program or script that you have uploaded to the Virtual Traffic Manager. Programs and scripts are uploaded using the Catalogs > Extra Files > Action Programs page.
When this action is invoked, the Virtual Traffic Manager will execute the program in the background, passing it command line arguments that identify the event that triggered the action.
The Virtual Traffic Manager passes the following arguments to the program or script:
- Any command line arguments you have configured in the action (optional).
- An argument named “eventtype” that provides the name of the event handler that invoked the action that executed the program.
- The event description; this is in exactly the same format as the log line for the event that is written to the event log.
For example, if a TrafficScript rule raises an event named TestEvent, and this is caught by an event handler named “My Event Handler” which invokes a Program action, the program will be called as follows:
programname "--eventtype=My Event Handler" \
"INFO TrafficScript/TestEvent CustomEvent rules/<rulename> \
vservers/<vservername> <description>"Note that the script is given two arguments (linebreaks have been inserted for readability).
Sending a SOAP Message
A SOAP action sends a SOAP request to the proxy configured in the action. The SOAP message conforms to the WSDL specification in:
ZEUSHOME/zxtm/etc/wsdl/AlertCallback.wsdlYou can download this file from the Actions > Edit page when you edit a SOAP action. This specification is documented in the Virtual Traffic Manager Control API documentation.
The SOAP request uses the interface http://soap.zeus.com/zxtm/1.0/AlertCallback, and invokes the method eventOccurred, passing it the following arguments:
- The name of the Virtual Traffic Manager machine that raised the event (type xsd:string).
- The time of the event, in the xsd:dataTime format.1
- The severity of the event (of the enumeration type AlertCallback.Severity).
- The tag that identifies the event (of the enumeration type AlertCallback.Tag).
- An array of tags; this is empty and reserved for future use.
- An array of objects (type AlertCallback.ObjectArray); these objects (type AlertCallback.Object) describe the object that was responsible for raising the event (such as a node or rule).
Some events will reference multiple objects. For example, an event raised from a TrafficScript rule will contain three objects that identify the event name, the rule and the virtual server running the rule.
- A human-readable description of the event (type xsd:string). This is predefined for most events, but when an event is raised by the TrafficScript function event.emit(), the description contains the message provided by TrafficScript.
- Additional data provided by the action (type xsd:string).
- The name of the Event Handler that invoked the action.
The following Perl CGI script implements a simple SOAP consumer for the AlertCallback messages; this responder logs the details of the message to a local file. You can install this CGI script on a suitable Web server (equipped with Perl and the SOAP::Lite Perl modules), then configure a SOAP action, setting the proxy value to the URL of the CGI script:
#!/usr/bin/perl
package AlertCallback;
sub _addSerializerForEnum($;$)
{
my ( $xsdtype, $ns_prefix ) = @_;
$ns_prefix = "zeusns" unless $ns_prefix;
$func = "SOAP::Deserializer::as_${xsdtype}";
*$func = sub { return $_[1] };
}
BEGIN {
_addSerializerForEnum( "AlertCallback.Tag" );
_addSerializerForEnum( "AlertCallback.ObjectType" );
_addSerializerForEnum( "AlertCallback.Severity" );
}
sub eventOccurred($$$$$$$$)
{
my $self = shift;
my( $stm, $time, $severity, $tag, $tags, $objects, $desc, $additional, $handler ) = @_;
open LOG, ">>events.log" or die( "Couldn't open log events.log: $!" );
print LOG "$stm - $time - $severity: $tag [";
print LOG join ', ', map { "$_->{type}:$_->{name}" } @$objects;
print LOG "] $desc ($additional); Event handler: $handler\n";
close LOG;
}
package main;
use SOAP::Transport::HTTP;
SOAP::Transport::HTTP::CGI
-> dispatch_with( { "http://soap.zeus.com/zxtm/1.0/AlertCallback/" => 'AlertCallback' } )
-> handle;If your action is invoked by multiple different events, you may wish to determine the precise event based on the tag value in the SOAP message. You can do so by matching the description of the event in the event tree (when you configure a custom Event Type) with the description in the WSDL file to determine the value of the AlertCallback.Tag.