Task properties

The following table describes the syntax of the properties and property values that are used to define IBM Director tasks. Refer to Creating IBM Director tasks and to IBM Director Interprocess Communication for information on creating extensions to IBM Director tasks.

Property name Property value
TaskID Specifies a string that identifies the task. This property is always required and must be unique.
ParentTaskID If this task is to be nested under a previously defined task in the tasks pane of the IBM Director Management Console, this value contains the TaskID of the parent task.
ResourceBundle Specifies the dotted notation name for the resource bundle that should be used to retrieve all translatable strings used for items such as menu labels.

Example:  BobCo's FileExplorer uses:
   ResourceBundle=com.BobCo.FileExplorer.BobCoResources

Title Specifies the key of the resource to retrieve from the resource bundle specified as ResourceBundle. This property is used as the label under the tasks icon in the Tasks pane of the IBM Director Management Console. If no resource bundle was specified or if no resource exists in the bundle associated with this key value, this value is used as the icon's label text. If this property is not specified, the task's icon is not be displayed in the Tasks pane of the IBM Director Management Console.
TaskUnrestricted If the task should be accessible by all users regardless of how the permissions are set, set this value to true.
GUI If any of this task's subtasks is interactive, this property's value must contain a class attribute and can optionally contain a parms attribute separated by a vertical bar. If none of the subtasks are interactive, omit the GUI property.

The GUI property value has the following attributes:
class Specifies the fully qualified name of the Java class providing the GUI for this task's interactive subtasks. It must include the full package and class name.
parms Specifies a parameter string passed to the GUI class when started. This attribute can be used to allow multiple tasks to be supported by the same GUI class.

Example:
   GUI=class:com.BobCo.FileExplorer.BobCoFileExplorerGUI | parms:your_string_goes_here

If no parameters are needed, omit the parms attribute.

helpTopicsMapping Specifies the full package name for the mapping file that should be used to associate help to components. This file contains unique help topic ids that are matched up to HTML file names. The format used is that of a Java property file and the filename extension is properties. The name provided is relative to the CLASSPATH. An interactive task console will associate a component in a panel to a help topic id (typically using TWGHelpContext). When help is requested (via the F1 key), IBM Director will look for any help topic id associated with the component having the focus. If one exists, IBM Director will then load the HTML file that is mapped to that help topic id based on the filename provided and the current locale for the task console.

Example:  BobCo's FileExplorer uses:
   helpTopicsMapping = /FileExplorerHelp

Server If any of this task's subtasks require a server portion, the Server property contains a series of attribute:value pairs separated by vertical bars. If a server task is not needed for any of the subtasks, omit the Server property.

The Server property value has the following attributes:
class Specifies the fully qualified name of the Java class that implements the server portion of the task. This attribute and exe are mutually exclusive. If sameJVM is true, the class specified here must implement TWGTaskServer; otherwise, this class must implement a main() method.
sameJVM If the class attribute is specified, this boolean value indicates whether a task activation will cause a new thread to be created in the core server engine's JVM (true), or a new JVM is to be started in a new process (false). The default value is false.
exe If the task has a native implementation, this attribute specifies the name of the Win32 executable that implements the server portion of the task. The exe and class attributes are mutually exclusive.
parms Specifies a parameter string passed to either a Java task or native task when it is launched in another process. This attribute can be used to allow multiple tasks to be supported by the same task class or native executable. If no parameters are necessary, omit this value.
auto-load Specifies a boolean value that indicates if the server task should be automatically loaded during the core server engine's initialization. If this value is false, this server task is started dynamically, as needed, to handle task activations. The default value is false.
synch Specifies a boolean value that indicates if the core server engine should wait during the start of initialization for this task to indicate that it is ready to continue. This attribute allows task servers to complete all necessary initialization before the engine starts updating topology information. The default value is false.

Example:
   Server = class:com.BobCo.FileExplorer.BobCoFileExplorerServer | sameJVM:false

The following properties define how a task communicates with the server engine through a ServiceNode.
ServiceNode If this task's server portion requires a service node to be active, the name of the service node is specified with this property. If this attribute is specified, task activation will not be complete until this service node is active.

Example:
   ServiceNode = BobCoFileExplorer

ServiceNode.Forward If this task's server portion wants subtask activations and deactivations or wants managed object lifecycle or status updates forwarded across the service node (specified as ServiceNode), then the command code to use and which values to forward are specified with this property. This property is only applicable if your server is started in a new JVM. The following attribute:value pairs are separated by a vertical bar:
command Specifies the command code to use when issuing the service node command to forward the subtask activation/deactivation and/or the managed object notifications
subtask Specifies a boolean value that indicates if subtask activations and deactivations should be forwarded over the service node. The default is false.
lifecycle Specifies a boolean value that indicates if managed object lifecycle notifications (that is, creations and deletions) should be forwarded over the service node. The default is false.
state Specifies a boolean value that indicates if managed object state change notifications (for example, online or offline) should be forwarded over the service node. The default is false.

Example:  To receive subtask activations using the service node command code 12561, specify:
   ServiceNode.Forward = command:12561 | subtask:true

ServiceNode.Forward.Class.x If either lifecycle or state is true for ServiceNode.Forward, then the managed object subclasses for which this task should receive notifications are specified using this property. The x is a 0-based index used to enumerate the classes during parsing of the properties if multiple classes are specified.

Example:  To receive notifications for native managed objects and SNMP devices, specify:
   ServiceNode.Forward.Class.0 = com.tivoli.twg.engine.TWGNativeManagedObject
   ServiceNode.Forward.Class.1 = com.tivoli.twg.snmp.TWGSNMPDevice

The following properties define the icons for a task.
Icon.Large Specifies the name of the icon file to use for this task when it is displayed in the Tasks pane of the IBM Director Management Console. As with all icons, if the task is to be displayed somewhere on the GUI and the appropriate icon has not been specified or cannot be loaded, the console uses a built-in icon as a default.

Example:
   Icon.Large = /com/BobCo/server/images/lrgTask.gif

Icon.Small Specifies the name of the icon file to use for this task when it is displayed in a tree view, like in the IBM Director scheduler's GUI.
Icon.Toolbar Specifies the name of the icon file to use for this task when it is displayed in the toolbar of the IBM Director Management Console.
Icon.Toolbar.Rollover Specifies the name of the icon file to use for this task when it is displayed in the toolbar of the IBM Director Management Console and the mouse cursor is over the icon.
TaskIconHidden By default, when a task is instantiated and has a specified Title, it is displayed in the Tasks pane of the IBM Director Management Console. If the task should not be displayed, set this value to true.
For each subtask defined for this task, five attributes are identified by the key Subtask.x.attr, where: x = 0, 1, 2, ..., n-1 and n = the number of subtasks, and where attr = ID, Menu, MenuLocation, Context, or Actions.
Subtask.x.attr The subtask identifier is a string that uniquely identifies this subtask for this task. This identifier is used during task activation to indicate which of the task's subtasks has been activated.
Subtask.x.Menu The subtask Menu property defines the label that is used to represent the subtask on the IBM Director Management Console. This property specifies multiple strings with a sorting factor for each string. Each string/sorting factor pair is separated by a vertical bar and represents one level of nesting in a pull-down or fly-out menu. The string is a key into the resource bundle for an NLS translated label.

If the resource bundle has not been defined, or if the key is not found in the resource bundle, then the key is used as the text. The sorting factor determines how the labels at each nesting level are sorted. A lower number places the item closer to the top of the menu's nesting level. Items at the same nesting level with the same sorting factor are sorted alphabetically. The console automatically adds a separator bar for each 200 units of sorting weight. Use the label weights as follows:
  0-199 Specifies common GUI actions, such as, New and Open, so that they always appear in the top section of the menu
200-399 Used by tasks shipped as part of Director
400-799 Used by tasks added as extensions to Director
800-999 Used by less commonly used functions that should always appear at the bottom of the menu
If a subtask does not need any labels defined, that is, it can only be activated through double-click or drag-drop, this attribute does not need to be specified for that subtask.

Example:  A single level menu would look like:
   Subtask.x.Menu=subtask0menu,450

A multi-level menu would look like:
Subtask.x.Menu=subtask0menu,450 | subtask0submenu,450
where subtask0menu and subtask0submenu are both keys for resources from the resource bundle.

Subtask.x.MenuLocation The subtask MenuLocation property defines where on the IBM Director Management Console the subtask label should be displayed. The choices are:
MainMenu Displays the label in the pull-down menu of the Management Console
TaskIcon Displays the label in the pop-up menu when a task is selected in the Tasks pane
ObjectIcon Displays the label in the pop-up menu when a managed object is selected in the Group Contents pane
FilterIcon Displays the label in the pop-up menu when a managed object filter (group) is selected in the Groups pane
If a subtask needs to be located on multiple menus, separate the location specifiers with a vertical bar.

Example:  To put the subtask's label on both the managed object icons and the task's icon, specify:
   Subtask.x.MenuLocation = ObjectIcon | TaskIcon

Subtask.x.Context The subtask Context is specified with a series of attribute:value tokens separated by a vertical bar. If the property is not specified or if any of the attributes are not specified, the default values are used.
interactive Indicates if the subtask is interactive:
false Non-interactive (default)
true GUI is launched
server Indicates if the subtask involves a server task:
false No server task (default)
true Server task is used
client Indicates if the subtask involves the client task(s) specified:
ignore No client task(s) needed (default)
check Check if client supports task(s)
start Automatically start the client task(s)
targeted Indicates if one or more managed objects must be selected to activate the subtask.
none Subtask is untargeted (default)
one Subtask is targeted at a single managed object. One managed object must be selected to activate the subtask.
multi Subtask is targeted at one or more managed objects. One or more managed objects must be selected to activate the subtask.

Example:  To specify an interactive subtask that requires the server task to run, specify:
   Subtask.x.Context = interactive:true | server:true

Subtask.x.Actions A subtask can be specified as the action for certain GUI operations. By default, a subtask is not activated for any GUI operations. To make a subtask a default action, use the Actions property to specify which GUI operations it should be attached to. Actions can be defined as follows:
double-click Specifies that the task icon can be double-clicked
toolbar Specifies that the task's toolbar icon can be clicked. This action must be followed by ,w where w is an integer from 0-799 that specifies the sorting factor weight for where to place this task's icon on the toolbar. As with menu weights, the console makes a new grouping every 200 units.

Example:  To place this task in the second group of icons on the toolbar, this attribute can be specified as:
   Subtask.x.Actions = toolbar,250

drag-drop A single managed object can be dragged and dropped on the task's icon
drag-drop-multi Multiple managed objects or a filter can be dragged and dropped on the task's icon
Only one subtask from a task can be attached to each action. If an action is not defined, performing that GUI action has no effect. If neither drag-drop nor drag-drop-multi are defined, the console shows the drag/drop target as not valid. If a subtask is to be specified for multiple GUI actions, separate each action with a vertical bar.

Example:
   Subtask.x.Actions = drag-drop | drag-drop-multi

If this task requires client task(s), the following properties specify the client task(s). For each managed object client class supported by this task, x = 0, 1, 2, 3..., n-1.
Client.x.Class Specifies the name of the TWGManagedObject subclass that represents the client in the server. Possible names are:

Example:
   Client.x.Class = com.tivoli.twg.engine.TWGNativeManagedObject

Client.x.Tasks The Client.x.Tasks property specifies the client task(s) that need to be started on the client when this task is activated. These client tasks are also referred to as agent services. This property is used in conjunction with the client attribute of the Subtask.x.Context property to control how the client is treated during task activation. It also works with the Client.x.Bind property to conditionally allow a task for a client based on the presence of the specified agent service(s).

If multiple client tasks are required, separate them with vertical bars.

Example:
   Client.x.Tasks = NativeMO.BobCoB

Client.x.Bind For subtasks that are specified using Subtask.x.MenuLocation = ObjectIcon, this attribute controls which managed objects the task applies to; that is, it specifies how the task should be bound to the client. Possible values are:
Class Bind the task to all managed objects of the specified class.
Class.soft Acts the same as Class but does not cause an exception if the specified managed object class has not yet been defined to the system.
Instance Binds the task only to instances of the specified managed object class if the instances have the specified client task(s).

Example:
   Client.x.Bind = Instance

Specifying Client.x.Bind = Instance forces a client to have a service specified by Client.x.Tasks before a managed object can be selected for a subtask.

Tasks can also be bound to managed object instances or classes by code running in the server engine's JVM by invoking either TWGManagedObject.addTask() for instance binding or TWGManagedObjectFactory.addTask() for class binding.