IBM Director is a management product for systems. IBM Director solves the problem of managing today's PC and LAN networks, and addresses real system management issues, enabling administrators to focus on managing their primary business. More information on IBM Director can be found in the IBM Director User's Guide. Although IBM Director is designed to meet the system management needs of most companies, your organization might require a customized solution that is not provided by the IBM Director product directly out-of-the-box. Towards this end, the IBM Director Software Development Kit (SDK) enables you to customize and enhance IBM Director to meet your needs.
Before you start with the IBM Director SDK, you should become familiar with the basic operation of IBM Director. The IBM Website is a good starting point. From there, you can read the Systems Management Guide PDF and you can download the product. It is a good idea to download the IBM Director product because you will need it later to test your code.
The IBM Director Server is the heart of the IBM Director product. This is where all of the management application data, the server engine, and the management application logic reside. It is written in Java with some native C++ programming. IBM Director provides the basic functionality such as:
The IBM Director Server can manage many Director Client systems. Since a Director Server system also contains a IBM Director Client, it is possible for another IBM Director Server to manage it.
The IBM Director Console is the graphical user interface (GUI) from which administrative tasks are performed. The IBM Director administrator uses this as the primary interface to various IBM Director tasks.
Several IBM Director Consoles can log in to the same Director Server. Alternatively, a user can start two IBM Director Consoles on a single machine and log into different Director Servers with each Console.
A IBM Director Console is automatically installed on the IBM Director Server system.
The IBM Director Server manages systems and devices in your network. The agent provides all of the code and interfaces necessary for the system to be managed by Director.
NOTE: the terms agent and client are used interchangeably in the IBM Director SDK.
With the IBM Director SDK, you can extend IBM Director functionality in several areas. Let's start by examining the user interface and identifying areas for extensibility. Prior to reading this, you should familiarize yourself with the Director Console operation using the IBM Director User's Guide.
Here is a snapshot of the main console.
You can see four main areas on the console
On the main console, with the SDK you can:
Tasks can be either interactive or non-interactive. Interactive tasks create a GUI, below is a screen capture of the Hardware Status GUI. Note that you can use the SDK to implement new Hardware Status categories and fire Hardware Status Events.
A non-interactive task can be either scheduled or executed immediately as in the following screen capture:
The new tasks can be configured to operate in one of three ways:
The task can be configured to be triggered by drag-drop operations or to be triggered by menu items. The following screen captures show menu possibilities. You can configure your task to appear in some or all of these menus.
The Main Menu
The Managed Object Menu
You can also change the way information is displayed in the center pane of the main console using Associations:
Associations will help you organize managed objects to make them more useable.
Events are notifications of significant failures, or conditions on managed objects. IBM Director users can create Event Action Plans to trigger automatic actions when specific events are received. Events are identified and grouped into hierarchies by their event type. The event type is a string containing a "family name" followed by a list of "qualifiers" You can create new types of events, which can be processed by users with Event Action Plans.
The first step in creating events is to inform the IBM Director Server of the events that your code can send. The process of informing IBM Director about possible events is called publishing; it will allow the user to create Event Action Plans. Publishing also allows support for multilingual events. For example, the following is a snapshot of the Event Filter Builder. It shows two different MassConfig events which have been published.
In these events "MassConfig" is the family and "Conflict" and "Overwritten" are qualifiers.
Once you have published the events, you can create and send the events to the IBM Director Server. Your events can add additional information in an arbitrary number of Event Detail fields. Here's an example of the data in a IBM Director Event. In this event, you can see that the event type is "CIM.Director_Agent_Events.Fan". Every event contains an "Event Text" field; this event contains text indicating that fan 1 is normal. Events are also organized into Severities, this one is Normal. "Target" and "Classname" are event details; every event detail has a name and a value.
In addition to creating events, you can create new Event Actions. Users can incorporate the actions into Event Action Plans. This snapshot of the Event Action Plan Builder shows Event Actions in the rightmost pane.
Additionally, if you create non-interactive tasks, then users can launch those tasks from Event Action Plans.
To collect inventory data, the Inventory component on the IBM Director Server starts code on the agents to scan for inventory data. The agent code sends inventory data to the Server where it is written to an SQL database. Here is an example of the data in an inventory table. You can create new tables and add data to them. You can also create new queries which will be available to users on the IBM Director Console.
Managed Objects are the targets of Tasks. A IBM Director Client machine is represented by a special kind of Managed Object called a Native Managed Object. You might want to discover and create your own managed objects. For instance, the SNMP extension that comes with IBM Director discovers and creates SNMP Managed Objects to represent SNMP agents. Your new managed object can be displayed with a unique icon as below. The Icon in the center pane represents an SNMP Agent named usrtplsn. It was discovered and created by the IBM Director SNMP component using SDK APIs.
In configuration files, you can tell IBM Director what Extension Name, Vendor Name and Version you would like to display in the about box. The following screen capture shows the About Box.
The following diagram shows the major components of IBM Director and how those components fit together. The shaded areas indicate areas of the product that can be extended with the SDK.
Engine | This is the main IBM Director component. It has many jobs including loading and unloading your Extension code. |
IBM Director Extensions | Extensions are the main mechanism for adding new management functions to Director. |
Managed Objects | The systems being managed by the Director. |
Filters | Filters are used to organize Managed Objects into groups. |
Associations | Associations are another way to organize Managed Objects and other management data. |
Persistent Store | The persistent store saves the state of all Managed Objects, Extensions, Users, etc. |
SQL Database | In Director, the SQL Database is used for Inventory data. |
DataStores | DataStores are indexed files used to save your extension's data. |
Properties Files | Property Files are used in IBM Director for reading or writing data in keyword-value pairs. |
Inventory | This is the IBM Director component that handles collecting inventory data and writing it to the SQL Database. |
Inventory Extensions | You can create inventory extensions which will be called by the Inventory component to collect and store additional inventory data. |
Events | This IBM Director component processes IBM Director Events but it also provides support for multilingual events, and for Event Action Plans. |
Event Action Handlers | Event Action Handlers are invoked by the Events component when they are triggered in and Event Action Plan. |
Monitors | This IBM Director component allows IBM Director users to "watch" specific attributes on systems (such as "CPU Usage"). It also provides support for creating events if a threshold is exceeded and for recording. |
Monitor APIs | Monitor APIs allow you to create additional monitoring functions. |
Transport | This is a IBM Director component that provides functions for multiprotocol networking support. |
Main Console | This is the IBM Director code that presents the main console, establishes connectivity to the IBM Director Server and launches your SDK code. |
GUI Tasks | You can write code to display panels on the IBM Director Console and to allow your SDK functions to be launched. |
TCP/IP Link | Communication between the IBM Director Console and IBM Director Server is over TCP/IP. |
Subagent | The basic method of adding code to run on the IBM Director agent is by creating a subagent. |
Java Subagent | Subagents can be created using Java on both the Linux and Win32 platforms. |
Event Subscriber | There are two ways for your agent code to send events to the IBM Director Server. First, you can create the event and send it directly to the Server. Second, you can use the Event Subscriber, which will minimize network traffic by sending the event only to IBM Director Servers that are interested in the event. |
Event Source | An event source is the code that works with the Event Subscriber to create events. |
Monitors | This is the component that provides attribute data to the server Monitors component. |
Monitor DLL | You can provide your own attribute data by creating a Monitor DLL. |
Now let's look at a very simple "Hello Director" program. This program will create a new task named "Hello" and it will configure IBM Director to display an icon for the new task on the IBM Director Console. When the user double-clicks the new icon, a panel will be displayed with the message "Hello Director". Most of the code will be Java code running on the Director Console, but we will have to put some code and definition files on the Director Server.
First, we need to tell IBM Director that we wish to write an Extension, so we create a file named Hello.TWGExt and we place it in the classes\extensions directory. The TWGExt file-extension tells IBM Director that this file describes an extension. Here's the file:
Hello.TWGExt
# Hello extension definition file twg.extension.classname=com.BobCo.Hello.HelloExtension |
This file identifies a class named HelloExtension that will run on the Server. HelloExtension is a subclass of a IBM Director class named TWGExtension. Inside this extension, we will create a Task.
Here's the code:
HelloExtension.java
package com.BobCo.Hello; import com.tivoli.twg.engine.TWGExtension; import com.tivoli.twg.engine.TWGExtensionInitException; import com.tivoli.twg.engine.TWGExtensionTermException; import com.tivoli.twg.engine.TWGPersistentObjectSaveException; import com.tivoli.twg.engine.TWGTask; import com.tivoli.twg.engine.TWGTaskCreationException; import com.tivoli.twg.engine.TWGDefaultTask; public class HelloExtension extends TWGExtension { /* class HelloExtension */ public HelloExtension() { super(); } /* Second initialization method, intended to allow extension to create default instances of classes */ public void InitClassInstances() throws TWGExtensionInitException { System.out.println("HelloExtension.InitClassInstances()"); if (!TWGTask.isTaskID("BobCo|Hello")) { try { TWGDefaultTask testTask = new TWGDefaultTask("com/BobCo/hello/HelloTask.properties"); } catch (TWGTaskCreationException e) { e.printStackTrace (); System.out.println("TWGTaskCreationException "); throw new TWGExtensionInitException("Error creating Hello default task"); } } } } /* class HelloExtension */ |
Since we do not need a lot of Server function to write Hello, the task that we create is a TWGDefaultTask. Tasks will be described in more detail in the next chapter but for now just think of a task a "something the user might want to do." In the method InitClassInstances(), we check to see if the "BobCo|Hello" task already exists, and we create it if it does not. We pass a parameter to the task constructor; it is the task properties file. This properties file describes how the task will behave. The properties file com/BobCo/hello/HelloTask.properties is placed in the classes/com/BobCo/hello directory.
HelloTask.properties
# Hello Task # TaskID = BobCo|Hello Title = HelloTask Icon.Small = /com/BobCo/Hello/images/Hello.gif Icon.Small.Selected = /com/BobCo/Hello/images/Hello.gif GUI = class:com.BobCo.Hello.HelloConsole Subtask.0.ID = SayHello Subtask.0.label = HelloTaskTitle Subtask.0.Context = interactive:true | server:false | targeted:none Subtask.0.Actions = double-click |
Now let's go through the properties specified in this file:
The TaskID property allows us find the task
later, this value matches the call in our HelloExtension:
if (!TWGTask.isTaskID("BobCo|Hello"))
The Title and Icon Small properties tells the console what label and GIF to use when displaying the task on the console.
The GUI property tells the console what class to run on the IBM Director Console when the user runs our task.
The Subtask.0.* lines give more information about how
the task will behave on the console. The most important lines are:
Subtask.0.Context : interactive:true means that this task will
display a GUI panel. server:false means that we do not require any
special code to be running on the Server. targeted:none means that
this task does not apply to any particular IBM Director Agents, etc.
Subtask.0.Actions = double-click : this means that we want the user
to invoke our task by double-clicking on our Hello.gif icon.
With these three files installed on the IBM Director Server, we restart the IBM Director Server and log in to it with a Console. The Console will display the icon and title for the Hello task like this:
Notice that if you double-click on the HelloTask, we get a message that the GUI hasn't been installed on the Console. We'll do that next, click OK to clear the message. Now we write the code for the console which extends a class called TWGTaskFrame. Here it is:
HelloConsole.java
package com.BobCo.Hello; import java.awt.*; import javax.swing.*; import javax.swing.border.*; import java.awt.event.*; import com.tivoli.twg.console.TWGMainGUI; import com.tivoli.twg.console.TWGTaskFrame; import com.tivoli.twg.engine.*; import com.tivoli.twg.libs.*; public class HelloConsole extends TWGTaskFrame implements ActionListener { public HelloConsole() { super( true ); } /* Create the client pane and return it. */ public Container buildView( ) { // create the panel JPanel returnPanel = new JPanel( ); // create the text message and add it to the center returnPanel.setLayout(new BorderLayout()); returnPanel.add("Center", new JLabel("Hello Director")); // Create cancel button and add to a button panel at the bottom. JPanel buttonPane = new JPanel( ); JButton cancelBtn = new JButton( "Cancel" ); buttonPane.add( cancelBtn ); cancelBtn.addActionListener( this ); returnPanel.add( "South", buttonPane ); return( returnPanel ); } // end buildView /* Initial frame size */ public Dimension getFrameSize() { return new Dimension( 200, 240 ); } /* Action handler for button action.*/ public void actionPerformed( ActionEvent evt ) { consoleCancel(); } } |
We need to override three methods and implement a no argument constructor to finish our program:
Once this code is compiled and installed, we go to the console and run our completed task. Since we only changed console code it is only necessary to restart the IBM Director Console (not the Server). We specified Subtask.0.Actions=double-click, so we go to the console and double-click on the HelloTask. Our console code is started and the following panel is displayed:
We click the Cancel button and our hello panel goes away.
In summary, there are several ways to extend the IBM Director product using the SDK. The most basic way to add function to IBM Director is by creating Tasks. In the Hello, example we: