Creating New Plugin Actions

Creating plugin actions requires two components:

• XML configuration/definition
• The script itself

Before a plugin action is available to users, you need to create a configuration file defining the location of the script to call, and what parameters need to be passed to this script. The configuration file needs to be created under $TRAVERSE_HOME/plugin/actions directory. There are no restrictions on what the configuration file can be named. However, the file must have a *.xml extension, as only *.xml files are scanned for configuration information.

Note: <timeout> must be specified.

writeToFile.xml

Here is a sample configuration file.

<?xml version="1.0" standalone="yes"?>

<!--

	All plugin "script" action configuration should be enclosed in an

<ActionScriptConfig>.. </ActionScriptConfig> block

-->

<ActionScriptConfig>

	<!--

		This is the name of the script action that will appear in the drop-down

list within the action profile management page on the Web application. This

name should be unique. It should not match the name of any other existing

native or custom action.

-->

	<name>My Custom Script</name>

	<!--

		This is the script/batch file/application to be executed. Use only the

name of the script/application, and do not include the path. Traverse looks

for this script under the $TRAVERSE_HOME/plugin/actions directory.

	-->

	<rootScript>writeToFile.sh</rootScript>

	<!--

		The parameters to pass to the script when executing it. See below for a

list of variables that you can use as parameters. Parameters can be specified

in multiple lines. At execution time, they are concatenated into a single

line.

	-->

	<parameters>

		-d ${device_name}

		-t ${test_name}

		-s ${current_user_severity}

	</parameters>

	<!--

		When executed, should Traverse wait for the script it to terminate?

Possible values:true or false.

	-->

	<waitForTerminate>true</waitForTerminate>

	<!--

		If waitForTerminate is true, how long (in seconds) should Traverse wait

before aborting the script? If set to 0 or a negative value, the application

will wait indefinitely for the script to terminate.

	-->

	<timeout>10</timeout>

	<!--

		If true, the output from the script will be added to the device comment

on the Web application. Enabling this option automatically sets

waitForTerminate to true.

-->

	<addOutputToComment>false</addOutputToComment>

</ActionScriptConfig>

The following variables can be used in the parameters section of the configuration file:

* ${additional_duplicate_key}  

* ${department_name}

* ${recipient}

* ${device_serial_number}

* ${device_model}

* ${device_type}

* ${device_snmp_version}

* ${current_user_severity}

* ${current_sla_severity}

* ${action_item}

* ${action_class}

* ${action_profile}

* ${action_class}

* ${device_tag1}

* ${device_tag1_caption}

* ${timestamp}

* ${device_name}

* ${device_address}

* ${device_vendor}

* ${device_snmp_cid}

* ${device_location}

* ${current_shadow_severity}

* ${time_in_state}

* ${container_member_type}

* ${container_member_count_match}

* ${container_name}

* ${affected_containers}

* ${container_member_summary}

• $container_member_count_match gives the number of immediate children in the container having the same severity as the container.
• $affected_containers gives the parent containers impacted by the severity of the current containers (one per line).
• $container_member_summary includes details on the severity of the container's children.
• ${device_tag1} provides the value configured for tag1 for the device.
• ${device_tag1_caption} provides the description (caption) of tag1 as configured in the emerald.xml file.

The following additional variables are available for events triggered by polled test results only.

- ${test_name}

- ${test_user_warning_threshold}

- ${test_sla_threshold}

- ${test_sub_type}

- ${result_value}

* ${test_serial_number}

* ${test_user_critical_threshold}

* ${test_type}

* ${test_units}

* ${event_reason}

The following variables are specific to events triggered by Message Transformation (for syslogs, log files, traps, etc.):

- ${message}

- ${message_source}

- ${ruleset_description}

- ${original_message}

- ${message_type}

As a security precaution, the actual script must be in the plugin/actions directory. If the command line tool is in a different directory, you can either create a wrapper script/batch file that calls the real program, or create a symbolic link (UNIX only) to the real program into plugin/actions.

writeToFile.sh

Here is a sample script that corresponds to the sample configuration file provided above.

#!/bin/sh

time=`date '+%Y%m%d-%H:%M'`

echo "time:$time, device: $2, test: $4, severity: $6" \

>> /tmp/severity.log

The configuration file, and the script, need to be installed under plugin/actions directory on all hosts that are running Traverse application. Before the new action is available, the web application and DGE components must be restarted. Once the configuration file has been loaded, it show ups on the drop-down list in the action profile management page within the web application. To use the newly added plugin action, you first need to create an action profile that uses this script.

Creating an Action Profile

1. Create an action profile via Administration > Actions > Create An Action Profile (or update an existing profile).
2. From the Notify Using drop-down list, you should be able to select the script. The name displayed on the list will correspond the <name>...</name> parameter in the configuration file (My Custom Script).
3. The Message Recipient field can be left empty and the rest of the parameters set as you see fit.
4. Apply this action profile to various tests as required.

For example, if an action profile containing this sample action is assigned to a test called My Test for a device called My Device, when the action profile is triggered for warning severity, the DGE component executes this script as:

  $TRAVERSE_HOME/plugin/actions/writeToFile.sh -d "My Device" -t "My Test" -s "warning"

and waits 10 seconds for the process to complete. Upon successful execution /tmp/severity.log should have an entry that looks like this:

time:2002nnnn-hh:mm, device: My Device, test: My Test, severity: warning

You can use the same script for multiple actions, for example, using different parameters. To do this, create multiple plugin action configurations that correspond to the same script.