Creating IBM Director groups and associations

IBM Director uses the concept of groups to allow users to organize the systems they manage into workable sets. Groups are essentially collections of managed objects that have been placed into the group either manually (using the Static Group Editor) or automatically (using the Dynamic Group Editor). Tasks applied to a group are performed on all of the members of the group.

The concept of associations is used to allow the presentation of a group of systems in a logical manner, one that displays the relationship between a system and the others in the group. The Group Contents window will display a group of systems in a hierarchical order defined by any association selected.

This topic describes how to extend IBM Director to include and display new predefined groups and new association categories. If you are extending IBM Director to include any of the following items, read this topic before you begin:

Subtopics

Related topics

Related sample code

Understanding how IBM Director presents systems and system attributes

In the IBM Director Management Console, the contents and presentation of systems and system attributes are controlled by the selection and activation of instances of two server object types: TWGFilter and TWGAssociation. For a given console, the selection of these instances is controlled using the groups window and the associations menu selection. Each group in the groups window corresponds to a TWGFilter instance and each item in the pull-down list of associations corresponds to a TWGAssociation instance.

The TWGFilter instance selected allows a subset of all TWGManagedObject instances in the server to be selected.

Note:  TWGManagedObject is an abstract base class: all instances are actually instances of subclasses.

TWGFilters do not create TWGManagedObjects, they simply determine, for each TWGManagedObject, whether the TWGManagedObject matches the specific criteria of the TWGFilter.

TWGFilters supported by IBM Director

The IBM Director Server supports 3 types of TWGFilter instances:

Class filters select on the basis of the class of each TWGManagedObject. Class filter instances are automatically created for each specific TWGManagedObject subclass that has one or more instances defined in the server. That is, when the first instance of a given TWGManagedObject subclass is created, such as the first TWGSNMPDevice instance, a class filter instance that matches on instances of TWGSNMPDevice (including subclasses) is created, if one does not already exist. Class filters cannot be edited or deleted by users.

Static filters base their selection on a list of TWGManagedObject object IDs. Only a fixed set of TWGManagedObjects are selected, based on the specific TWGManagedObject object IDs selected when the TWGFilter instance is created or last updated by the user.

Dynamic (functional) filters base their selection on the successful matching of a logical combination of one or more database queries. Only TWGManagedObjects that have attributes in the IBM Director database and satisfy the logical combination of queries defined for the filter are selected. Most attributes are provided by the IBM Director inventory task. Refer to Defining Default Dynamic Filters  for more information on the creation and function of dynamic filters.

How the TWGFilter object works

The following steps describe how TWGFilter functions for all types of filters:

  1. When first selected, the TWGFilter is supplied a list of all existing TWGManagedObject instances. It evaluates this list and returns the subset of TWGManagedObject that matches its criteria.

    All objects that match are passed as added objects to the active TWGAssociation instance for evaluation.

  2. If one or more new TWGManagedObject instances are created, the TWGFilter is given a list of the new instances to evaluate. Instances that match are then added to the previously created TWGManagedObjectSet. New objects that match are passed as added objects to the active TWGAssociation instance for evaluation.
  3. If one or more TWGManagedObject instances are modified or updated, for example, because of an inventory refresh or operating system change, the TWGFilter is given a list of the changed instances to evaluate. Instances that still match are kept in the TWGManagedObjectSet, and any that no longer match are removed. Existing objects that still match are passed as changed objects to the active TWGAssociation instance for evaluation.
  4. Deleted TWGManagedObject instances are not passed to the active TWGFilter or TWGAssociation instances. The deleted objects are automatically removed from the TWGManagedObjectSet maintained by the active TWGFilter and from TWGRelationships maintained by the active TWGAssociation.

Understanding the active states of TWGFilter and TWGAssociation

The TWGManagedObjectSet created and maintained by the active TWGFilter for each console is used:

The active TWGAssociation instance is responsible for creating and maintaining a set of relationships between the TWGManagedObject instances provided by the active TWGFilter. Each TWGAssociation instance, provided by a subclass of TWGAssociation, includes a function that receives notification of all added and changed TWGManagedObjects that were matched by the TWGFilter instance. If notified of an addition or change, the function generates or updates the TWGRelationship instances appropriate to the characteristics of the new or changed TWGManagedObjects. For example, one of the standard TWGAssociation instances provides relationships based on membership in network domains or workgroups. In this case, the TWGAssociation subclass generates and maintains a relationship instance ( TWGRelationship ) for each different network domain and Workgroup of which its TWGManagedObjects are members, and adds each matching TWGManagedObject to the appropriate relationship, if the object is a domain or workgroup member. Refer to the sample code for detailed information.

Understanding TWGRelationships

TWGRelationship instances can be thought of as folders or nodes in a tree hierarchy. Each TWGRelationship has zero or more objects below it (that is, contained within it) from a folder perspective. These objects, which can be TWGManagedObjects or other TWGRelationships (allowing a hierarchy), are referred to as down-links. A given TWGRelationship can have any number of down-links. TWGRelationship instances can also have zero or more up-links to other TWGRelationships. These links can be viewed as parents of the TWGRelationship.

Note:  A down-link from one relationship to another implies an up-link from that relationship to the first.

If any up-links are defined, exactly one of them must be marked as the primary up-link. The primary up-link presents a simple tree representation of a set of TWGRelationships, called a TWGRelationshipSet. For a given console, all of the TWGRelationship instances created by the active TWGAssociation are stored in a TWGRelationshipSet instance. When an update occurs that causes the TWGAssociation to be notified, the TWGAssociation is supplied with the TWGRelationshipSet containing any existing TWGRelationships, which it is then expected to update. These updates can include:

These updates are then sent, along with any other object updates, to the IBM Director Management Console, which uses them to update the Group Contents window.

Creating a new TWGAssociation

To implement a new TWGAssociation:

The following steps describe how to create a new TWGAssociation subclass and references the DomainWorkgroupAssociation sample code.

  1. Create the source file for the new TWGAssociation subclass. As shown in DomainWorkgroupAssociation.java, create a public class that extends com.tivoli.twg.engine.TWGAssociation.
  2. Define a public default constructor, that is, a constructor with no parameters. In the sample code, that is:

    'public DomainWorkgroupAssociation() ...'

    This constructor is used to instantiate the TWGAssociation subclass when it is first created and when it is restored. ( TWGAssociation Instances are persistent objects which are automatically restored.) For more information on persistent objects, refer to the TWGPersistentObject class.

  3. Define a unique ID string for identifying the TWGAssociation instance(s). By default, a TWGAssociation instance does not have an ID string; however, it is recommended that you assign each TWGAssociation instance a unique ID string that can be used for programmatic activation of the TWGAssociation. To define a unique ID string, create a 'public static String' variable (the sample defines DEFAULT_DOMAIN_ASSOC_ID), and assign it a distinctive ID using a naming convention. The string should use the following naming convention which follows Java package recommendations:

    'com.company_name.product_name.specific_name'

    For example, the sample code uses the ID com.BobCo.domain_workgroup. This ID is used in the extension initialization code when the instance of the subclass is created.

  4. Define a name string and menu sort weight for the TWGAssociation subclass. The name string, as opposed to the ID string, is a presentation label used in the IBM Director Management Console when the selection menu for Associations is generated.

    The name string has to be translated to support different languages. To support translation, TWGAssociation supports the following methods:

    'setName(String id, String resource_bundle)'
    'setName(String name)'

    The 'setName(String id, String resource_bundle)' method allows the name of the TWGAssociation instance to be specified as a Java ResourceBundle resource ID and as a ResourceBundle classname. Refer to the JDK V1.1 reference for information on using the java.util.ResourceBundle for language support. If translation text is not needed or is not available, the 'setName(String name)' method can be used to assign a literal string for the TWGAssociation's name. This string would be used for all languages.

    The menu sort weight is an integer constant used to determine the order of the TWGAssociations presented in the Associations menu of the IBM Director Management Console. The TWGAssociations are ordered from lowest to highest sort weight. Equally weighted TWGAssociations are ordered alphabetically by name. The sort weight for a TWGAssociation defaults to 0, but can be set with the setMenuWeight(int) method. Sort weights below zero are reserved for TWGAssociations supplied with Director.

  5. Declare and implement the evaluateNewAndChangedObjects() method:

    'public void evaluateNewAndChangedObjects(TWGRelationshipSet rel, IntValueSet add_set, IntValueSet chg_set, TWGManagedObjectSet mos)'

    This method is the evaluation method for the TWGAssociation subclass. All notifications for updates to the TWGManagedObjectSets that the TWGAssociation instance evaluates are issued by invoking this method. The specific implementation of the method is particular to the given subclass, but most need to perform the following functions:

    1. Check for the root TWGRelationship in the TWGRelationshipSet, and create one if it is not found. All other TWGRelationships that the method creates need to be down-linked from the root relationship unless they are down-linked from another TWGRelationship. The root TWGRelationship is not displayed by the IBM Director Management Console. Therefore the name of the root TWGRelationship instance is not important.
    2. Evaluate the appropriate data functions for the new and changed TWGManagedObjects , that is from the add_set and chg_set.

      Often, as in the sample code, this evaluation includes querying the IBM Director database for records associated with the object ID of the TWGManagedObject. This data is then used to determine which TWGRelationships need to be created, if they do not exist already, and which TWGManagedObjects need to be down-linked from these TWGRelationships. In some cases, the data is used to determine which TWGManagedObjects are assigned to the is-a object for these relationships.

      Refer to the TWGRelationship class for more information.

    3. Create any TWGRelationship instances that need to be created. The TWGRelationships that are required often depend on the evaluation of the data from the TWGManagedObjects. Typically, the TWGRelationship instances are assigned ID strings that allow their existence to be determined quickly and, if not found, created when needed. In the sample code, each workgroup ID and domain ID returned for the TWGManagedObjects determine the need for a TWGRelationship instance for each distinct value. The ID string for these instances is DOM:domain_id or WG:workgroup_id, allowing the instances to be looked up quickly when a new or changed TWGManagedObject is processed, and for the appropriate instance to be created quickly when it is not found.
    4. Remove any of the changed TWGManagedObjects from TWGRelationships that are no longer appropriate for them. Objects from the add_set are guaranteed not to have been in existing TWGRelationships, but objects, if any, in the chg_set have been evaluated previously. In many cases, it is simpler to use the 'TWGRelationshipSet.removeAllLinksToManagedObject(TWGManagedObject mo)' method on each changed TWGManagedObject, instance. Remove all references to the changed TWGManagedObjects in the existing TWGRelationshipSet, then treat the changed objects like new objects by inserting them into any appropriate TWGRelationships). The sample code uses this technique.
    5. Using the 'TWGRelationship.AddDownLink(TWGManagedObject mo)' method on TWGRelationship instances, add any of the new or changed TWGManagedObjects into any appropriate TWGRelationships. Each TWGManagedObject can be a member of zero or more TWGRelationships, but the object can be a member of a given TWGRelationship only once. In addition to down-links, TWGManagedObjects can be tied to a given TWGRelationship using the 'TWGRelationship.setIsAObject(TWGManagedObject mo)' method. This link indicates that the TWGManagedObject represents the TWGRelationship, that is, the given TWGRelationship is a TWGManagedObject. This type of link is typically used in cases where the TWGRelationship corresponds to a physical managed object, for example, a server in a client-server relationship, as opposed to being a logical entity, for example, a workgroup. The relationships in the sample code are all logical relationships.
    6. Clean up and return. Evaluate the evaluateNewAndChangedObjects() method quickly and efficiently; this method can be called frequently, particularly when new systems are being discovered and inventoried. Also, changes to the TWGRelationship and TWGRelationshipSet instances must occur only during this method call; therefore all updates must be completed before the method returns.
  6. If necessary, implement subclasses of TWGRelationship to support your TWGAssociation. In the code sample, the names of the TWGRelationship instances include both language translatable strings and data variables (Domain 'domain_name' and Workgroup 'wg_name'). TWGRelationship, like TWGAssociation, supports both 'setName(String name_id, String resource_bundle)' and 'setName(String name)' name setting methods, but neither of these methods properly handles combinations of instance-specific data and translation text. To support these combinations, the sample creates an inner class named DomainRelationship that subclasses TWGRelationship. The subclass then replaces the 'getName(Locale)' method in TWGRelationship with an implementation that creates a translated name string using the MessageFormat class with a translated format string.
  7. Add code to a TWGExtension subclass to register the new TWGAssociation class and create any initial instance(s) of the class. You must register the new TWGAssociation subclass in the 'TWGExtension.InitClassRegistration()' method of a TWGExtension subclass. In the sample code, a trivial TWGExtension subclass, DomainWorkgroupAssociationExtension, includes the 'TWGExtension.RegisterClass(String cname)' method to perform the needed registration for the subclass.

    The registration can be part of the extension initialization for a larger set of extensions. If needed, the initial instances of the TWGAssociation subclass should be created from inside the 'TWGExtension.InitClassInstances()' method of the same TWGExtension subclass. The sample code includes a simple registration method, 'DomainWorkgroupAssociation.initializeDefault()', that is called by the extension to initialize the single instance needed for the DomainWorkgroupAssociation. This method uses the ID of the instance to check for its existence, and creates a new instance if the ID is not found.

  8. Define and install the extension registration file (TWGExt file) for the extension, restart the IBM Director Server, and start using the new TWGAssociation. If properly initialized, the new TWGAssociation's name should be displayed in the Associations pull-down menu of the IBM Director Management Console. Selecting the name should make the new association's instance active for the console, thereby causing its evaluateNewAndChangedObjects() method to be called for the initial population of TWGManagedObjects in the currently active Group. Additional calls to the evaluateNewAndChangedObjects() method are made as objects are added or changed.