IBM Director Software Development Kit overview

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

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.

How IBM Director works

IBM Director is a server-centric systems and application management product that was designed with extensibility in mind. In order to better understand how to Extend IBM Director with the SDK, let us quickly review the makeup of Director. At a high level, the IBM Director product is composed of three main components:
  1.  The IBM Director Server
  2.  The IBM Director Console
  3.  The IBM Director Agent 

IBM Director Server

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. 

IBM Director Console

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.

IBM Director Agent

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.

Extending IBM Director

All three IBM Director components support extensions. Extending IBM Director with the SDK generally requires these steps: 
  1. Program the new function. This will involve writing Java and sometimes C++ code. Your code will either subclass existing IBM Director classes or implement IBM Director Interfaces.
  2. Compile the code.
  3. Copy the Code to the IBM Director system. You might need to copy files to the IBM Director Server machine, the IBM Director Agent and the IBM Director Console.
  4. Update IBM Director configuration files to tell IBM Director where your code is and how IBM Director should use it. These files will generally be on the IBM Director Server and IBM Director Agent.
  5. Restart the appropriate IBM Director Servers, Consoles and Clients.
To create your own IBM Director extensions, you need to know what areas can be extended. The following items describe the extensibility points.

The user's view

The main console

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

  1. At the top is the menu area and toolbar
  2. In the center is a pane showing the group contents. Usually this area shows managed objects. Managed objects usually represent some kind of agent. A IBM Director Client machine is called a Native Managed Object.
  3. On the left is a pane displaying the groups. Groups are collections of similar managed objects. A managed object can be a member of more than one group.
  4. On the right is the list of tasks. Tasks are operations that can be performed. Usually, tasks are performed on managed objects or a set of managed objects (such as a group)

On the main console, with the SDK you can:

  1. Add a task. You can configure your task to be displayed in the Task Pane or the Toolbar or in menus. There are many options for placing tasks in menus; tasks can be added to the main Task Menu, the menus for groups, the menus for managed objects.
  2. Add a child task. Child tasks are no different than any other task except that they are displayed under its parent task in the tree view of the Task Pane.
  3. Add a new group NOTE: The term Filter is synonymous with Group in the SDK.

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:

  1. To operate on a single managed object.
  2. To operate on a group of managed objects.
  3. To operate independent of managed objects

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

 

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.
  1. [MassConfig][Conflict]
  2. [MassConfig][Overwritten]

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.

Inventory

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

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.

 

Extension information

 

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 programmer's view

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.

Terms from the programmer's view diagram

Server

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.

Console

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.

Agent

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.

Hello Director

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:

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:

  1. buildView() : In this method we return a JPanel containing the "Hello Director" text and a Cancel button.
  2. getFrameSize() :  In this method, we return the initial size of the JPanel.
  3. actionPerformed() : Since the only possible action is the Cancel button, we call TWGTaskFrame.consoleCancel() to close our GUI panel. 

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:

  1. Created a TWGExt file to tell IBM Director about a new extension.
  2. Created a HelloExtension class. In this class we created a new Task using the name of our Task properties file.
  3. In the properties file, we specified how the console should display the new task and gave the name of a class. containing the GUI code.
  4. We wrote our GUI code by extending TWGTaskFrame. Inside the buildView() method, we built our panel.