Command-task (CMDTask) file format

CMDTask files are uncompiled Java™ properties files defining external application tasks for IBM Director.

CMDTask files are created using the External Application Launch Wizard; they can optionally be created or edited manually. This topic describes the CMDTask file format to assist advanced users and vendors who want to edit CMDTask files without using the wizard.

File location and naming conventions

The following requirements apply to all CMDTask files: When creating a parent task and child tasks, best practices dictate that you name all child CMDTask files with the same file name as the parent, except for an underscore and numeric digit that follow the file name and precede the extension. This convention is illustrated by the following listing of a parent CMDTask file and its three children:
MyExternalTask.CMDExt
  MyExternalTask_1.CMDExt
  MyExternalTask_2.CMDExt
  MyExternalTask_3.CMDExt
Note: Parent-child relationships of external application tasks are for display and organizational purposes in IBM Director Console, but do not create any functional links between tasks. All child tasks are sorted alphabetically by title under the specified parent task.

Parameters set in CMDTask files

CMDTask files are flat-text files in which each line is either a comment beginning with the number sign (#) or a parameter definition in the form parameter_name=value. For example,
# This line is a comment. The following line sets the Title parameter.
Title=Telnet to Managed System
Notes:
  1. Both parameter names and values are case sensitive.
  2. If the same parameter is specified more than once, the last parameter value in the file is used by IBM Director.
  3. ISO 8859-1 character encoding must be used.
  4. Characters that cannot be represented directly in the ISO 8859-1 character set can be specified with valid ISO 8859-1 Unicode escape sequences.

Be careful when editing CMDTask files, because no error-checking is performed. Parameter names that do not exactly match expected parameters are ignored.

Table 1 lists the parameters which can be set in a CMDTask file.

Table 1. CMDTask parameters
Parameter name Description Allowed values
Client.0.Class The fully-qualified Java class name of an allowed target type for the external application task. A valid class name for a managed-object type in IBM Director. See Managed-object classes for the Client.0.Class parameter for a list of valid class names.
CMDTaskNumericVersion
CAUTION:
This parameter is set by the External Application Launch Wizard and should not be manually edited. It is described here for informational purposes only.

The raw numeric IBM Director version number.

A nine-digit number specifying a valid IBM Director version code.
CMDTaskVersion
CAUTION:
This parameter is set by the External Application Launch Wizard and should not be manually edited. It is described here for informational purposes only.
The human-readable IBM Director version number.
A text string specifying a valid IBM Director version.
CommandString.Unix A command string to be executed on a UNIX® or Linux® management console. See Command string notes for important information about specifying command strings in CMDTask files. A valid command line for an external application.
CommandString.Windows A command string to be executed on a Windows® management console. See Command string notes for important information about specifying command strings in CMDTask files. A valid command line for an external application.
CommandString A command string to be executed on a UNIX, Linux, or Windows management console. See Command string notes for important information about specifying command strings in CMDTask files. A valid command line for an external application.
Cwd The path name of the working directory in which the external application task should be started on a UNIX, Linux, or Windows management console. Specify this parameter only if the command needs to start in a specific directory. See Command string notes for important information about specifying directories in CMDTask files. A valid directory on the management console.
Cwd.Unix The path name of the working directory in which the external application task should be started on a UNIX or Linux management console. Specify this parameter only if the command needs to start in a specific directory. See Command string notes for important information about specifying directories in CMDTask files. A valid directory on the management console.
Cwd.Windows The path name of the working directory in which the external application task should be started on a Windows management console. Specify this parameter only if the command needs to start in a specific directory. See Command string notes for important information about specifying directories in CMDTask files. A valid directory on the management console.
Icon.Large The path and file name of a GIF file that will be used for the task's large display icon in IBM Director Console.
Notes:
  1. The specified path can be absolute or relative (starting in the classes directory under the IBM Director Server installation directory). Relative path names should start with a forward slash (/).
  2. The specified GIF file must have a height and width of 32 pixels.
  3. If you will be using an instance of IBM Director Console installed on another system than the management server, see Configuring remote instances of IBM Director Console for external application tasks.
The absolute or relative path and file name of a 32 x 32-pixel GIF file on the management console.
Icon.Small The path and file name of a GIF file that will be used for the task's small display icon in IBM Director Console.
Notes:
  1. The specified path can be absolute or relative (starting in the classes directory under the IBM Director Server installation directory). Relative path names should start with a forward slash (/).
  2. The specified GIF file must have a height and width of 16 pixels.
  3. If you will be using an instance of IBM Director Console installed on another system than the management server, see Configuring remote instances of IBM Director Console for external application tasks.
The absolute or relative path and file name of a 16 x 16-pixel GIF file on the management console.
ParentTaskFilename The base file name of an external application task specified as the parent of the current task.
Note: This parameter should only be used when manually creating CMDTask files. The External Application Launch Wizard removes this parameter if it is found, and instead sets the ParentTaskID parameter to the task ID of the parent task, which can be either an external application task or a native IBM Director task.
The base file name (that is, without the .CMDExt extension) of the parent task for the current task.
ParentTaskID
CAUTION:
This parameter is set by the External Application Launch Wizard and should not be manually edited. It is described here for informational purposes only.
The unique identifier of the external application task's parent task in IBM Director Console. If omitted, this parameter assumes the default value of CmdTask, which places the external application task under the External Application Launch task in IBM Director Console.
Note: There is a limitation in IBM Director 5.10 which prevents a child task from being subordinate to a parent task if the child task name is not alphabetically greater than that of the parent task. See File location and naming conventions for additional information and a suggested workaround.
A text string specifying the internal IBM Director task ID of the parent task for the current task.
ParentTaskTitle Deprecated. Use ParentTaskID to specify the parent task. Parameter is ignored.
ResourceBundle A Java resource bundle that defines national-language titles to appear in IBM Director Console. If the ResourceBundle parameter is specified, the Title parameter is interpreted as the title key for the resource bundle. If not, the Title parameter value is used as title text. Full class name of a Java resource bundle.
ShellRequired A flag that indicates whether or not you want to start a persistent shell in which to start the external application. The shell is started using one of the following commands:
Windows
start cmd.exe /k
UNIX or Linux
bash –c
If this parameter is omitted or set to false, the command string is issued without starting a persistent shell. If this parameter is set to true, any command output to the shell is displayed in a command window that you can scroll and later close.
true or false.
Targeted A flag that specifies whether the external application task can be started as a targeted task, an untargeted task, or both.

Set this parameter to none for untargeted tasks, one for targeted tasks, or none|one for tasks that can be started either way.

If this parameter is omitted, the value is assumed to be one.
One of the following values:
  • none
  • one
  • none|one
Timeout The number of seconds that IBM Director Console will wait after the external application task is completed. During the timeout period, IBM Director Console displays a busy status. If this parameter is omitted, it is assumed to be 5 seconds. A whole number in the range 1 - 60.
Title Either a text string used as the task title or a title key for a Java resource bundle that defines national-language titles that will appear in IBM Director Console. It is recommended that you set this parameter. If not set, the base file name of the CMDTask file is used. Any text string or title key for a Java resource bundle that defines national-language titles.

Managed-object classes for the Client.0.Class parameter

Managed-object classes are used to specify targets for the external application task with the Client.0.Class parameter. Valid managed-object classes include those listed in Table 2.
Note: The information provided in this table is for reference only, and may not include third-party managed-object classes or classes supported in future versions of IBM Director. It is recommended that users create CMDTask files using the External Application Launch Wizard, which obtains managed-object class information dynamically from IBM Director Server.
Table 2. IBM Director classes for managed object types
Managed object type Class
All Managed Objects com.tivoli.twg.engine.TWGManagedObject
BladeCenter™ Chassis com.ibm.sysmgt.chassis.bcchassis.BCChassisManagedObject
Chassis com.ibm.sysmgt.chassis.ChassisManagedObject
Clusters com.tivoli.twg.engine.cluster.TWGClusterManagedObject
Level 0: Agentless Systems com.tivoli.twg.tier.TieredManagedObject
Level 1: IBM Director Core Services Systems com.tivoli.twg.tier.DummyTieredManagedObject
Level 2: IBM Director Agents com.tivoli.twg.engine.TWGNativeManagedObject
Logical Platforms com.ibm.sysmgt.platform.LogicalPlatform
Physical Platforms com.ibm.sysmgt.platform.PhysicalPlatform
Platforms com.ibm.sysmgt.platform.Platform
Racks com.ibm.sysmgt.nfrack.NFRackManagedObject
Remote I/O Enclosures com.ibm.sysmgt.spm.server.rioe.RIOEnclosure
RMON Devices com.tivoli.twg.rmon.TWGRMONDevice
Scalable Partitions com.ibm.sysmgt.spm.server.partition.Partition
Scalable Systems com.ibm.sysmgt.spm.server.complex.Complex
SMI-S Storage Devices com.ibm.sysmgt.storage.smis.SmisManagedObject
SNMP Devices com.tivoli.twg.snmp.TWGSNMPDevice
SNMP Printers com.tivoli.twg.snmp.printer.SNMPPrinter
Storage Devices com.ibm.sysmgt.storage.StorageManagedObject
Windows Clusters com.tivoli.twg.mscs.MSCSManagedObject

Command string notes

Sample CMDTask file: Telnet to managed system (Telnet.CMDExt)

# This CMDTask file creates a command task to open a Telnet session
# and hold the window open while the user types their user ID 
# and password.

# Parameters for all operating systems:
Title= Telnet Command
Targeted=one
ShellRequired=true

# Parameters for UNIX or Linux:
CommandString.Unix = xterm –hold –e telnet  $CMDTASK_IP_ADDRESS0
#                          -hold gives you an error message if telnet fails

# Parameters for Windows:
CommandString.Windows = telnet  %CMDTASK_IP_ADDRESS0%

Sample CMDTask file: Map a managed system to a Windows network drive (NetUse.CMDExt)

# This CMDTask file creates a Windows network drive connection
# to the targeted system using the next available drive letter.

# Parameters for all operating systems:
Title= Net Use Command
Targeted=one
ShellRequired=false

# Parameters for UNIX or Linux:
CommandString.Unix = 
# Empty command string specified; no action occurs

# Parameters for Windows:
CommandString.Windows = net use * \\\\%CMDTASK_COMPUTERNAME%\\c$ /u:userid pwd
# note: \\ for each \
Related concepts
External application tasks