Creating IBM Director event actions

This topic describes how to extend IBM Director to support new event actions.

Subtopics

Related topics

Related sample code

Understanding event actions

An event action is the what-to-do part of an event action plan. By creating new event actions, you can customize your environment to execute the specific actions needed to respond to specific events that occur on your network. Most events are generated by IBM Director components that monitor system and network resources. Because each generated event is associated with a monitored device, each event action plan must be associated with the same device to be activated.

Typically, an event action sends a notification of an event's occurrence or starts some type of automated recovery procedure, if needed, as a result of the corresponding event. For example, IBM Director provides the ability to display information on an event in the ticker tape area of the Management Console and enables you to start a program on the system associated with an event.

Refer to the IBM Director User's Guide and to the IBM Director online help for more information on using the event actions supplied with IBM Director.

How IBM Director processes event actions

The IBM Director Event Manager (event manager) is a subcomponent of the IBM Director server that handles all event traffic. It manages the repository of event related objects like events, event filters, event actions, and event action plans. In addition, it is the control point for the execution of all event actions contained in event action plans on the server.

The event manager discovers each available event action during server startup. Event actions included as part of IBM Director are loaded automatically. The event actions you create are loaded through the knowledge gained when the event manager reads the event action extension files.

These files specify Java classes that have implemented either the TWGEventHandler interface, or the interface of it's subclass, TWGRefreshableEventHandler. Either way, a single instance of each class that has implemented one of these interfaces is created.

Note:  In this section, an instance of a class that has implemented the TWGEventHandler or the TWGRefreshableEventHandler. interface is referred to as the event handler. In the following paragraphs, "event handler" is used to describe the interactions between the event manager and individual instances of the classes that have implemented this interface.

During discovery, the event manager uses the GetInfo() method to query information about an event handler, including what function it performs (title) and what input parameters are needed to configure it. Each input parameter contains information describing its purpose, style of GUI component (for example, text box or spinner), and default values.

An event handler can specify whether it should remain resident at all times or have an instance created for each invocation. Keeping an event action resident consumes system memory; therefore, allowing an event action to be loaded and unloaded uses memory more efficiently. However, some event actions rely on asynchronous command replies to post completion messages in the event action history log. These actions must remain loaded to receive the replies. The Add Event to Event Log event action is an example of a non-persistent action. Send an AlphaNumeric Page is an example of a persistent event action.

Note:  The first time an event action's title and list of parameters are discovered, they are stored as persistent data in a twgaction.ini file, located in the classes\data subdirectory. If you change the information associated with the title or parameters, restarting the IBM Director Server does not alter this information. The twgaction.ini file must be deleted and the server must be restarted for changes to take effect.

The event manager uses the information gathered during discovery to create the list of available event actions shown in IBM Director's Event Action Plan Builder window. If an action can be customized, that is, if it can accept one or more input parameters, the event action editor creates a dialog based on the sum of the input parameters defined during GetInfo() processing.

When you select the event action, the dialog is displayed to receive the user parameters. When you then save the information using the Save or Save As options, the provided information is imbedded into the appropriate parameter object and passed to the event handler through the ValidateParm() method. The ValidateParm() method is called once for each parameter defined by the action. This permits the event handler to respond with a unique error message to each incorrect input it receives. If the event handler validates all input parameters, the event manager saves the parameters which makes them available for association with event action plans.

Note:  Because a given event action has multiple representations in the Event Action Plan Builder, only one instance of the event handler class exists at a given time in the server. For example, if the user creates two instances of the Send a Numeric Page action, one to page Bob and one to page Jane, the event server maintains both versions of the event action. At execution time, the event action component in the IBM Director Server engine is passed the parameters containing the variables informing whether to page Bob or Jane.

With the customized event action parameters now stored on the IBM Director Server, the corresponding event handler is not called again until an event triggers and an associated event action plan dictates that it should be invoked. When this occurs, the event manager calls the event handler's ProcessEvent() method and passes both the customized parameter list and the event that triggered. The event handler is then required to process the data as quickly as possible and return. This process is repeated for each event that triggers.

Creating event actions: basic steps

At a high level, you must perform the following steps to add a new event action to the IBM Director Server:

  1. Create a Java class on the server that implements IBM Director's TWGEventHandler or TWGRefreshableEventHandler interfaces.
  2. Create an event action extension file that tells the IBM Director Event Manager to load your new action (a Java class that implements the TWGEventHandler or the TWGRefreshableEventHandler interface) in the classes\extensions subdirectory.

Implementing the TWGEventHandler interface

The TWGEventHandler interface supports five methods.

GetInfo(TWGActionInfo)
The event manager uses the GetInfo() method to query the event handler for its properties. These properties include: title, a list of customizable parameters, and various operational control settings. The TWGActionInfo object is used as a container for passing the information back and forth. This method is always the first method called and can be called many times over the life of the object. This method is also used for prerequisite checking. Event handlers that return FALSE to this call are signaling that it can not be run in this environment.
Init()
The event manager calls the Init() method after GetInfo() but before any other calls on the interface. Init() enables the event handler to do any special initialization that might be required.

For example, the Send an SNMP Trap to an IP Host action uses the Init() call to load a data file containing the rules associated with converting IBM Director events to SNMP Traps. Consequently, the data has to be read from the disk only once to execute the action.

The Init() method can be called only once during the life of the object. An event handler that wants to code empty bodies for Init() should always return TRUE.

Term()
The Term() method is used to facilitate any special cleanup that might be needed before the destruction of the event handler object. Like the Init() method, the Term() method is called only once during the life of an object. An event handler that wants to code empty bodies for Term() should always return TRUE.
ValidateParm(TWGActionParm)
The event manager calls the ValidateParm() method when a user attempts to save the parameters of a customized action. ValidateParm() is called n times (where n is the number of input parameters supplied in an action) when the user selects the Save or Save As buttons through the Customize Action dialog. Each invocation of this method includes one of the TWGActionParm objects, created by the event handler during the GetInfo() call, with the user's information now filled in. The event manager uses these calls to request that the action verify the data supplied by the user during customization. The user input can then be declared incorrect and a message describing the reason for the error can be passed back to the dialog. This process attempts to eliminate as many run-time errors as possible by validating user input before the action is requested to actually use the data.
ProcessEvent(TWGEvent, TWGActionInfo)
The ProcessEvent() method is where the real work typically takes place. The event manager calls ProcessEvent() when an event triggers an active event action plan. An active event action plan is one that has been associated with a managed system or group of managed systems. When this occurs, the saved parameters and the actual event that triggered the event action are passed to the event handler. Using these parameters, the event handler attempts to perform the advertised function.

Note:  Event manager processing depends on a timely return from the ProcessEvent() call. Consequently, most event handlers use asynchronous calls to other threads to do most of the work, especially when communication with another system in the network is required.

Implementing the TWGRefreshableEventHandler interface

The TWGRefreshableEventHandler interface adds one additional method to those supported by the TWGEventHandler interface:

RefreshInfo(TWGActionInfo)
The event manager uses the RefreshInfo() method to notify the event handler of an impending create or edit action. It is intended to allow the event handler to reset dynamic parameters in advance of the create or edit action.

Classes used to customize an event action

Use the following classes to create the Customize Action dialogs needed to receive user input. Refer to the IBM Director User's Guide or the online helps for examples of the Customize Action dialogs.

TWGActionParmTextBox
Use when the desired GUI component is a simple text box.
TWGActionParmTextArea
Use when the desired GUI component is a multi-line text window.
TWGActionParmLongSpinner
Use when the desired GUI component is a simple spinner of long values.
TWGActionParmStringSpinner
Use when the desired GUI component is a rotating list of strings.
TWGActionParmDropDown
Use when the desired GUI component is a single select combination box of strings.
TWGActionParmMultiSelList
Use when the desired GUI component is a multi-select combination box of strings.

Supporting event data substitution

Event data substitution is the replacement of specifically defined keywords within user text imbedded in TWGActionParmTextBox and TWGActionParmTextArea objects. If the user specifies an event data substitution keyword, for example, &severity, in the Customize Action dialog presented to receive user input, the corresponding data is extracted from the event that triggered the action and inserted into the text of the event action at the point where the keyword is specified. To support this feature in your event handler, use the TWGEvent.expandString method.

Creating an event action extension file

An event action extension file is a property file that must be in the classes\extensions subdirectory relative to the directory in which the IBM Director Server is installed. Event action extension files are identified by the unique ALTExt file extension. Within the property file, use the following keywords to describe the action (event handler).
Property name Property value
event.action.classname A string that identifies the name of the class that implements the TWGEventHandler or the TWGRefreshableEventHandler interface. The name specified must be fully qualified, including package name, and relative to the IBM Director classes directory or updated classpath. Refer to the Event Action Extension File for an example of the contents of an extension file.
event.action.iconname A string that identifies the name of the GIF file that contains the 16-pixel image to be used as the action's icon on the IBM Director console. The name specified must be fully qualified and relative to the IBM Director classes directory. At load time, the name given for this property will be suffixed with 16.gif.
event.action.helpfilename A string that identifies the name of the HTML file that contains the help text for the action. Your help text should describe the purpose of the action and completely describe each input parameter (field) presented in the dialog. The English version of the HTML file must be placed in the classes\doc\tivoli\events subdirectory relative to where IBM Director Server is installed. You can also create a national languages version of the file and place that file into the appropriate language subdirectory relative to where is installed: classes\doc\lang\tivoli\events, where lang corresponds to the two-letter language prefix (for example, gr = German).

SMTP event action extension file

The following sample demonstrates the format of an extension file:


# Event action extension definition file
#
event.action.classname=com.tivoli.twg.itech.TWGSMTPActionHandler
event.action.iconname=com.tivoli.twg.itech.images.semail
event.action.helpfilename=dlg_cstmz_actn_snd_email.html

Supporting event action history

Event action history is the primary means for providing feedback to users about the success or failure of an action. Event actions support event action history in two ways:

To capture asynchronous updates, your event handler should use the TWGActionLogManager and TWGActionEndInfo classes. Each time an event handler's ProcessEvent() method is called, a unique key is assigned by the event manager and placed into the TWGActionInfo object. The event handler then uses the key to post success or failure messages in the action history log. A free text area is available for additional information that the event handler wants to convey.

Creating event action help

Each event action within IBM Director Server has a corresponding HTML file that describes its purpose and individual action parameters. Refer to the event.action.helpfile property of the event action extension file for more information.

National Language Support

All of the classes described in this document use a similar technique for supporting national language translation. Each attribute of an event action, including the title, parameter labels and sublabels, help files, and messages, are encoded to provide a Java style of national language support. Each string can be coded as a resource bundle and keyword pair, allowing the event manager to load at run-time the appropriate string relative to the desired locale.

In addition, the Customize Action dialog (Advanced => Language) supports the setting of a preferred language, allowing you to indicate what language is preferred at the ultimate target of the action. This setting can be determined using the TWGActionInfo.getTargetLocale() method.