This topic describes how to extend IBM Director to support new 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.
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.
At a high level, you must perform the following steps to add a new event action to the IBM Director Server:
The TWGEventHandler interface supports five methods.
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.
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.
The TWGRefreshableEventHandler interface adds one additional method to those supported by the TWGEventHandler interface:
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.
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.
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). |
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
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.
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.
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.