HP

HP Systems Insight Manager Technical Reference Guide

English
  Tools that Extend Management  |  Creating New Command Line Tools  |  Command Line Tools Reference   

Command Line Tools Reference

»Table of Contents
»Index
»Notices
»Introduction
»Product Overview
»Getting Started
»Discovery and Identification
»Users and Authorizations
»Networking and Security
»Monitoring Systems, Clusters, and Events
»Storage Integration
»Managing with Tasks
»Tools that Extend Management
»Cluster Monitor
»Command Line Tools
»Creating New Command Line Tools
»New Command Line Tool
»New Copy a File Tool
»New X Window Tool
Command Line Tools Reference
»Examples of Using Parameter Strings in Command Line Tools
»Custom Commands
»Configuring DMI Access
»Configuring SNMP Access
»Device Ping
»Disk Thresholds
»License Manager
»Management Processor Tools
»Managing MIBs
»Installing OpenSSH
»PMP Tools
»Removing and Restoring Tools
»Replicate Agent Settings
»RPM Package Manager
»Server Migration Pack
»System Management Homepage
»System Page
»Version Control
»Virtual Machine Management Pack
»WBEM Based Tools
»Available MSA Tools
»Partner Applications
»Reporting
»Administering Systems and Events
»Troubleshooting
»Reference Information
»Printable version
»Glossary
»Using Help
» Tool Types
» Parameterized Strings
» Tool Filtering
» Version Numbers
» Other Requirements
» Document Type Definition
» Related Procedures
» Related Topic

Tool Types

There are five basic types of HP Systems Insight Manager (HP SIM) tools, single-system aware (SSA) tools, multiple-system aware (MSA) tools, and Web-launch aware (WLA) tools.

SSA tools are executed on a target system and are only aware of the target system environment. When executing an SSA tool, therefore, the distributed task facility (DTF) sends the tool information to each HP SIM agent to execute the tool. An example of an SSA tool would be a tool that wraps a common UNIX command, such as ls, cat, or cp.

MSA tools are executed on a central system, sometimes the central management server (CMS), and know how to handle a list of target systems. An example of an MSA tool would be a tool that wraps the functionality of Ignite-UX on HP-UX systems.

WLA tools are tools that are generally executed in a browser and are specified by a universal resource location (URL).

Parameterized Strings

To create tools properly, the tool developer must understand how URLs and command lines are formed. Using parameterized strings, tool developers can greatly enhance the options available in creating tool definition files (TDEFs).

Parameterized strings are strings which contain replacement fields, similar to the format strings used in the popular printf() function in the standard C library. These fields can be replaced by values entered by the user at runtime (as defined by the tool parameters attribute), by some standard task properties supplied by the Task Controller, values related to the selected target systems or system groups, or by property values retrieved from a global tool properties file. This allows a very specific URL or command line to be generated.

Parameterized Strings Substitution Table

The following parameters provide substitution of global attribute values:

ParameterDescription
%t Task ID for the task being executed
%uName of the user running this tool
%eName of the user to execute this tool as
%sManagement server hostname of the core CMS running the tool
%#(where # is a positive integer) Substitute the value input by the user for the parameter referenced by the number (#) provided, as a list index position (one-based... %1, %2, %3, and so on)
%ySOAP logon token, for use with SOAP single sign-on Web applications

The following parameters provide substitution of the current selected target:

ParameterDescription
%fThe database name of the target system (or system group, if the %x toggle was in the string).
%nNetwork name (hostname, IP address, IPX address, or system name in that order).
%aNetwork address (IP address, or IPX address, in that order).
%lLink name in format specified by System Link Configuration setting (name, IP address, or full DNS name).
%pIP address of WBEM proxy, if any, for this target, in the form <ip address>:<port#></port#></ip>.
%gDatabase GUID of the target system (or system group, if the %x toggle was in the string).
%bSystem type of the target system.
%cSystem sub-type of the target system
%r% (rt[.attribute]%)Substitutes the related system that has the relationship type as specified in the parameter "rt." If the [.attribute] is specified, then one of the named system attributes would be returned for the related system. In addition, the common attributes such as Network name (.a) also work. For example, to get the server's management processor's IP address, use %r{MgmtProcToServer.a%} to get the contact use %r{MgmtProcToServer.Contact%}. If the related systems attribute is omitted then for each system, the network name and IP address is returned. The network name and IP address is returned in the form "network name|ip address" if more than one system is returned, then they are comma-delimited. Note that the relationship type "MgmtProcToServer" can be used to return related system information for all management processor relationship types.
%(attribute]%)The value of the named attribute of the target system.

The following parameters provide repetition to support multiple selected target systems:

ParameterDescription
%( ... %)Repeated pattern (only repeats if a current selection exists). If a current target selection does not exist, the text between the delimiters is removed on expansion. This allows the text to be optional and dependent upon the target selection list.
%iSelection index (one-based).
%zDo not substitute anything, but increment the selection index to the next integer and the referenced target system to the next target in the selected target list.
%⇚< ... >lEncrypted text (encrypt after all other parameters have been substituted).
%%Enables you to retain a % in the command/URL after substitution.

Tool Filtering

Tool filtering is a facility enabling the tool writer to control whether the tool should be executed on a selected system. Most tools are platform dependent in that their successful execution depends on commands that are provided on some platforms but not on others. For example, the bdf tool depends on the bdf command, which is provided on HP-UX platforms, but is not available under that name on Linux platforms. A tool should only be visible in the Tools menu when there is at least one discovered system that passes the filter requirements. A discovered system must pass the filter requirements and is then executed only if all the filter requirements are passed. To do this, the tool specifies in a system filter expression the system attributes that must be possessed by all systems it can run on.

The system attributes required for a tool to run are specified by system filter expressions having the form:

				
<system-filter name="attribute-name" operator="eq" 
   value="attribute-value" />
      or
<system-filter name="attribute-name" operator="ge" 
   value="attribute-value" />
      or
<system-filter name="attribute-name" operator="lt" 
   value="attribute-value" />
      or
<system-filter name="attribute-name" operator="ct" 
   value="attribute-value" />
      or
<system-filter name="attribute-name" operator="neq" 
   value="attribute-value" />
      or
<system-filter name="attribute-name" operator="nct" 
  value="attribute-value" />
			

The eq operator the system on which the tool can run must have exactly the attribute value specified. It applies to any attribute name allowed in a system filter expression. The ge operator specifies that a system on which the tool can run on must have at least the attribute value specified. The lt and ge operators can only be used with revision attributes, specifically OSRevision in the OS type filter and all of the attributes of the Protocol type filter. The value of these attributes can be numeric or can be character strings. The ct operator specifies that a system on which the tool can run on must have an attribute that contains the value specified. The neq operator specifies that a system on which the tool can run on must not have the exact attribute value specified. It applies to any attribute name allowed in a system filter expression. The nct operator specifies that a system on which the tool can run on must have the attribute that does not contain the value specified. For systems, the numeric valued attributes the filter expression can specify include the OSRevision and Protocol Support attributes, whose values are version numbers. The values permitted for version numbers and how they are compared is described in the Version Numbers in the following section. The attribute-name is one of the values listed in the tables in the following section, or a protocol name from the ProtocolSupport attribute of a system. The attribute-value is one of the possible system attribute values for attribute-name.

Attribute values are based on the Distributed Task Force (DMTF) Common Information Model (CIM). Usually these values are defined during the system identification process, which uses WBEM and SNMP to determine system attributes. For this release, valid OSName values are HP-UX and Linux. For an OSName value of HP-UX, the OSRevision attribute values have the leading alphabetic field removed (for example B.11.11 is stored as 11.11).

A system filter expression is used as part of an include filter expression. There are three types of include filter expressions, each allowing a different category of attribute names on which to be filtered.

CategoryFilter TypeAttribute Names Allowed
Operating SystemosOSName, OSVendor, OS Revision
HardwarehardwareDeviceType, DeviceSubType, Model
Protocol SupportprotocolAny protocol name, except HTTP
OtherotherCan be any predefined system attribute or any custom-system attribute.

An include filter includes one or more system filter expressions using the attributes names allowed for it. For example, an os filter could consist of:

				
<include-filter type="os">
	      <system-filter name="OSName"     
		    operator="eq" value="LINUX"  />
	      <system-filter name="OSVendor"   
            operator="eq" value="RedHat" />
	      <system-filter name="OSRevision" 
            operator="ge" value="7.2"	  />
</include-filter>
			

The include filter need not include all attributes allowed. If more than one attribute is included, the conditions are logically and'ed together. An attribute cannot appear in an include filter more than once, except that an attribute having a version number value can appear twice if one operator is lt and the other operator is ge. For example:

				
<include-filter type="protocol">
	      <system-filter name="WBEM" 
            operator="lt" value="2.6" />
          <system-filter name="WBEM" 
            operator="ge" value="2.4" />
</include-filter>
			

This would specify that the tool should be shown for any collection of systems supporting the WBEM protocol version 2.4 or higher, but less than 2.6.

If a tool contains more than one include filter of different types, the conditions of the filters are logically AND'd together. A tool with both Operating System and Hardware dependencies could use the filter:

				
<include-filter type="os">
	      <system-filter name="OSName"     
	        operator="eq" value="LINUX"  />
 </include-filter>
 <include-filter type="hardware">
	      <system-filter name="DeviceSubType" 
	        operator="eq" value="HPVectra" />
 </include-filter>
			

If a tool contains more than one include filter of the same type, the conditions of the filters are logically or'ed together. A tool available on two different operating systems could specify:

				
<include-filter type="os">
	      <system-filter name="OSName"     
	        operator="eq" value="LINUX"  />
</include-filter>
<include-filter type="os">
	      <system-filter name="OSName"     
	        operator="eq" value="HPUX"	 />
</include-filter>
			

This tool could be launched on any collection of systems using Linux or HP-UX.

Tool filtering depends on the attributes being filtered having a value defined on the systems selected. For the "os" filter type, if any attributes being filtered on are not defined for a system, the system is assumed to have the value required by the filter. Thus a system with none of the os attributes specified by a tool filter will be assumed capable of running the tool. For the hardware filter type, the above statement is true in the case of the Model attribute. But for the DeviceType and DeviceSubType attributes, the tool filter will apply only for known values on the selected systems. The protocol filter type requires that the protocol must exist on the system before the operators can be applied. This means that the neq and nct operators also depend on the system to have that protocol. The other filter also works like the protocol filter such that the attribute being filtered upon must exist on the system before the operators can be applied. If a tool uses the other and/or protocol filters, then at least one system must contain the filterable attributes for the tool to be displayed in the GUI.

Version Numbers

The OSRevision and Protocol Support system attributes have values that are interpreted as version numbers if possible. A version number is a series of non-negative decimal numbers separated by period (.) characters. When comparing version numbers, the following rules are used:

  • The leftmost numbers in the series are most significant, so 1.0 is greater than 0.1.

  • Leading zeroes on the numbers are disregarded, so 003 is equal to 3.

  • Two adjacent period characters are interpreted as if they delimited the number zero, so 1.0.3 is equal to 1..3

  • A beginning period character is interpreted as if proceeded by a zero, so .9 is equal to 0.9.

  • Trailing zero numbers are disregarded, so 1.0.0 is equal to 1.

Other Requirements

SSA command tools must contain an execute statement (execStmt) or a file copy statement (copyStmt), or both. If only the execute statement is specified, no files are copied prior to executing the command. If only a file copy statement is specified, after the file(s) are copied, no command is executed. If they are both specified, the files are copied first and then the command is executed.

MSA command tools must specify a command and the system on which the command will execute.

Tool names must be at least one character in length, and no more than 256 characters in length. The first character of the name must be alphabetic. Characters after the first can be letters, digits, spaces, or any of the characters - . ( ) or _.

Web launch aware tools must specify a main URL.

When specifying file copy pairs, the destination file paths for each file copy pair within a singe tool definition must be unique. Specifying the same destination file path for multiple source file paths results in a file parsing error.

An error occurs when running a tool that copies a file if the file does not exist or is unreadable. The source file path is not checked at the time the tool is created or modified, but must exist at the time the tool is executed.

When the log element is set to true, standard out and standard error output from the execution of the tool is logged in the central management server (CMS) log file /var/opt/mx/logs/mx.log. When it is set to false, only summary task log information, such as start and end times and task status is logged.

Document Type Definition

The Document Type Definition (DTD) file defines the constraints for an XML file. These constraints include the valid element tags, attributes, and the cardinality of elements in an XML file. The tool DTD file is named toollist.dtd and is included in the following paragraph. Note that due to manpage formatting, the DTD contents might not appear the same as in the file.

				
<?xml version="1.0" encoding="UTF-8" ?>

<!-- The tool-list element can contain zero or more of 
      ssa-command-tool elements, msa-command-tool elements,
      web-launch-tool elements, automation-tool elements or
      app-launch-tool elements.-->
      
<!ELEMENT tool-list ( ssa-command-tool |
      msa-command-tool |
      web-launch-tool  |
      automation-tool  |
      app-launch-tool )* >

<!-- The ssa-command-tool element specifies a single-system aware
      tool. The ssa-command-tool element can optionally specify a
      category element, a description element, a comment element, an
      owner element, a default-target element, an execute-as-user
      element, a job-display-handler element, a toolbox-enabled
      element, zero or more toolbox elements, zero or more
      include-filter elements, or zero or more env-variable elements.
      (NOTE: The role-enabled and role elements are deprecated
      elements and should not be used with this product. These
      are provided for backward compatibility with previous
      products. The toolbox-enabled element and the toolbox
      element should be used in their stead.)
      If more than one of these elements are specified, the element
      must appear in the order as listed in this definition. The
      ssa-command-tool element must contain an ssa-block element. The
      ssa-block element must appear after the previously described
      optional elements, if any of the optional elements are
      specified. Following the ssa-block element, one can specify zero
      or more attribute elements.-->
	  
 <!ELEMENT ssa-command-tool (category?, description?, comment?,
      owner?, default-target?, execute-as-user?,
      job-display-handler?,
      toolbox-enabled?, toolbox*,
      role-enabled?, role*,
      include-filter*, env-variable*,
      ssa-block, attribute* ) >

<!-- In addition to the previously described elements, the
      ssa-command-tool element specifies the following attributes. The
      name attribute specifies the tool name and must be specified in
      the ssa-command-tool element. The visible attribute specifies
      whether the tool is visible for running. By default tools are
      visible. The max-targets attribute specifies the maximum number
      of targets against which a tool can run. The revision attribute
      allows a tool author to specify a revision for the tool. Note
      that this is for information only. The job-log attribute
      specifies whether the results of the command will be kept in this
      system's job log. This attribute applies only to tools when they
      are run as scheduled tasks, not when they are run as "run now"
      tasks. When job-log="true" the job and target status for the tool
      will be kept for a relatively lengthy system-defined period in
      the database after the job completes. When job-log="false" only
      the last completed copy of the job and target status for the task
      will be kept in the cache for a much shorter period of time, and
      will not be written to the database.	 Job logging is enabled by
      default. The schedulable attribute specifies whether the tool can
      be run as a schedulable task. When scheduled="false" the tool can
      only run as a "run now" task.  Tools are scheduled by default.
      The GUID attribute specifies a globally unique identifier (GUID)
      for the tool. Because the system generates a GUID for a tool
      during the add operation, this field should only be specified
      during a modify operation. The accepts-targets attribute specifies
      whether the tool accepts targets for execution. The
      accepts-targets attribute is true by default. -->

<!ATTLIST ssa-command-tool name	     CDATA   #REQUIRED
      visible     (true | false) "true"
      max-targets NMTOKEN #IMPLIED
      revision    CDATA   #IMPLIED
      job-log     (true | false) "true"
      schedulable (true | false) "true"
      guid	     NMTOKEN #IMPLIED
      accepts-targets (true|false) "true" >

<!-- The ssa-block specifies the elements specific to a single-system
      aware tool. The ssa-block can specify a command or copy-block or
      both. Only one command should be specified but up to 16 multiple
      copy-blocks can be specified. After the command and/or
      copy-blocks, one can specify the parameters for the command
      and/or copy-block. -->
  
<!ELEMENT ssa-block (( command | copy-block )+, parameter*) >

<!-- The copy-block specifies a source file path and a destination
      file path for a copy operation. -->

<!ELEMENT copy-block ( source, destination )+ >

<!-- The source element specifies the source file path for a copy
      operation. -->

<!ELEMENT source (#PCDATA) >

<!-- The destination element specifies the destination file path for a
      copy operation. -->
     
<!ELEMENT destination (#PCDATA) >

<!-- The msa-command-tool element specifies a multiple-system aware
      tool. The msa-command-tool element can optionally specify a
      category element, a description element, a comment element, an
      owner element, a default-target element, an execute-as-user
      element, a job-display-handler element, a toolbox-enabled
      element, zero or more toolbox elements, zero or more
      include-filter elements, or zero or more env-variable elements.
      (NOTE: The role-enabled and role elements are deprecated
      elements and should not be used with this product. These
      are provided for backward compatibility with previous
      products. The toolbox-enabled element and the toolbox
      element should be used in their stead.)
      If more than one of these elements are specified, the element
      must appear in the order as listed in this definition. The
      msa-command-tool element must contain an msa-block element. The
      msa-block element must appear after the previously described
      optional elements, if any of the optional elements are
      specified. Following the msa-block element, one can specify zero
      or more attribute elements.-->
      
<!ELEMENT msa-command-tool (category?, description?, comment?, owner?,
      default-target?, execute-as-user?,
      job-display-handler?,
      toolbox-enabled?, toolbox*,
      role-enabled?, role*,
      include-filter*, env-variable*,
      msa-block, attribute* ) >

<!-- In addition to the previously described elements, the
      msa-command-tool element specifies the following attributes. The
      name attribute specifies the tool name and must be specified in
      the msa-command-tool element. The visible attribute specifies
      whether the tool is visible for running. By default tools are
      visible. The max-targets attribute specifies the maximum number
      of targets against which a tool can run.  The revision attribute
      allows a tool author to specify a revision for the tool. Note
      that this is for information only. The job-log attribute
      specifies whether the results of the command will be kept in this
      systems job log. When job-log="true" the job and target status
      for the tool will be kept for a relatively lengthy system-defined
      period in the database after the job completes. When
      job-log="false" only the last completed copy of the job and
      target status for the tool will be kept in the cache for a much
      shorter period of time, and will not be written to the database.
      Job logging is enabled by default. The schedulable attribute
      specifies whether the tool can be run as a scheduled task. When
      schedulable="false" the tool can only run as a "run now" task.
      Tools are schedulable by default.  The guid attribute specifies a
      globally unique identifier (GUID) for the tool. Because the
      system generates a GUID for a tool during the add operation, this
      field should only be specified during a modify operation.  The
      accepts-targets attribute specifies whether the tool
      accepts targets for execution. The accepts-targets attribute is
      true by default. -->

<!ATTLIST msa-command-tool name	     CDATA   #REQUIRED
      visible     (true | false) "true"
      max-targets NMTOKEN #IMPLIED
      revision    CDATA   #IMPLIED
      job-log     (true | false) "true"
      schedulable (true | false) "true"
      guid	     NMTOKEN #IMPLIED
      accepts-targets (true|false) "true" >

<!-- The msa-block specifies the elements specific to a
      multiple-system aware (MSA) tool. The msa-block can specify an
      MSA command, the parameters for the command and an execution system
      on which the command executes. -->
      
<!ELEMENT msa-block ( command, parameter*, execution-system ) >

<!-- The command element specifies the command for an SSA or an MSA
      tool. If the command accepts parameters, it must be specified as
      a parameterized string. -->
     
<!ELEMENT command ( #PCDATA ) >

<!-- The command element can have two attributes. The command-type
      attribute specifies whether the command is an x-window, stdout,
      restart, launch, or an unknown command type. The default command
      type is stdout. The log attribute specifies whether the results
      of the command will be output to this system's audit log. When
      log="true" the stdout and stderr results of the command will be
      output to the system's audit log. Command output is not logged
      by default. -->
      
<!ATTLIST command command-type (x-window |
      stdout   |
      restart  |
      launch   |
      unknown) "stdout"
      log (true | false) "false" >

<!-- The execution-system element specifies the system on which an MSA
      tool will execute. -->
      
<!ELEMENT execution-system ( #PCDATA ) >

<!-- The web-launch-tool element specifies a web launch tool. The
      web-launch-tool element can optionally specify a category
      element, a description element, a comment element, an owner
      element, a default-target element, an execute-as-user element, a
      job-display-handler element, a toolbox-enabled element, zero or
      more toolbox elements,  zero or more include-filter elements, or
      zero or more env-variable elements.
      (NOTE: The role-enabled and role elements are deprecated
      elements and should not be used with this product. These
      are provided for backward compatibility with previous
      products. The toolbox-enabled element and the toolbox
      element should be used in their stead.)
      If more than one of these elements are specified, the element
      must appear in the order as listed in this definition. The
      web-launch-tool element must contain a web-block element. The
      web-block element must appear after the previously described
      optional elements, if any of the optional elements are
      specified. Following the web-block element, one can specify zero
      or more attribute elements.-->
      
<!ELEMENT web-launch-tool (category?, description?, comment?, owner?,
      default-target?, execute-as-user?,
      job-display-handler?,
      toolbox-enabled?, toolbox*,
      role-enabled?, role*,
      include-filter*, web-block, attribute* ) >

<!-- In addition to the previously described elements, the
      web-launch-tool element specifies the following attributes. The
      name attribute specifies the tool name and must be specified in
      the web-launch-tool element. The visible attribute specifies
      whether the tool is visible for running. By default tools are
      visible. The max-targets attribute specifies the maximum number
      of targets against which a tool can run.  The revision attribute
      allows a tool author to specified a revision for the tool. Note
      that this is for information only. The job-log attribute
      specifies whether the results of the command will be kept in this
      systems job log. When job-log="true" the job and target status
      for the tool will be kept for a relatively lengthy system-defined
      period in the database after the job completes. When
      job-log="false" only the last completed copy of the job and
      target status for the tool will be kept in the cache for a much
      shorter period of time, and will not be written to the database.
      Job logging is enabled by default.  The schedulable attribute
      specifies whether the tool can be run as a scheduled task. When
      schedulable="false" the tool can only run as a "run now" task.
      Tools are schedulable by default. The guid attribute specifies a
      globally unique identifier (GUID) for the tool. Because the
      system generates a GUID for a tool during the add operation, this
      field should only be specified during a modify operation. -->

<!ATTLIST web-launch-tool name	    CDATA #REQUIRED
      visible	    (true | false) "true"
      max-targets NMTOKEN #IMPLIED
      revision    NMTOKEN #IMPLIED
      job-log	    (true | false) "true"
      schedulable (true | false) "true"
      guid	    NMTOKEN #IMPLIED >

<!-- The web-block specifies the elements specific to a web launch
      tool. The web-block must specify a main-url element. Optionally,
      the web-block can specify a side-url element, a status-url
      element, and a current-url element. Additionally, the web-block
      can specify the parameters for the URLs. Finally, the web-block
      can optionally specify a target format to describe how targets
      are passed to a web launch aware tool. -->
      
 <!ELEMENT web-block (main-url, (side-url?, status-url?, current-url?),
      parameter*, target-format? ) >

<!-- In addition to the above elements, the web-block element has one
      attribute. The accepts-targets attribute specifies whether the
      web launch tool accepts targets for execution. The
      accepts-targets attribute is true by default. -->
      
<!ATTLIST web-block accepts-targets (true|false) "true">

<!-- The main-url specifies the URL to launch the tool. If the URL
      accepts parameters, the URL must be specified as a parameterized
      string. -->
      
<!ELEMENT main-url ( #PCDATA ) >

 <!-- The status-url specifies a URL at which one might find the status
      of this web launch tool during execution. -->
      
<!ELEMENT status-url ( #PCDATA ) >

<!-- The current-url specifies the current URL. -->

<!ELEMENT current-url ( #PCDATA ) >

<!-- The side-url specifies a set-aside URL. -->

<!ELEMENT side-url ( #PCDATA ) >

<!-- The target-format defines the format of targets in a web launch
      tool and is specified as a parameterized string.-->
      
<!ELEMENT target-format ( #PCDATA ) >

<!-- The automation tool performs an action on the CMS which
      involves accessing the target systems. The automation-tool element
      can optionally specify a category element, a menu-category
      element, a description element, a comment element, an owner
      element, a default-target element, an execute-as-user element, a
      job-display-handler element, a default-parameter element, a
      role-enabled element, zero or more  role elements,  zero or more
      include-filter elements, or zero or more env-variable elements.
      If more than one of these elements are specified, the element
      must appear in the order as listed in this definition. The
      automation-tool element must contain an automation-block element.
      The automation-block element must appear after the previously
      described optional elements, if any of the optional elements are
      specified. Following the automation-block element, one can
      specify zero or more attribute elements. -->
      
<!ELEMENT automation-tool (category?, description?, comment?, owner?,
      default-target?, execute-as-user?,
      job-display-handler?,
      toolbox-enabled?, toolbox*,
      role-enabled?, role*,
      include-filter*, automation-block,
      attribute* ) >

<!-- In addition to the previously described elements, the
      automation-tool element specifies the following attributes. The
      name attribute specifies the tool name and must be specified in
      the automation-tool element. The visible attribute specifies
      whether the tool is visible for running. By default tools are
      visible. The max-targets attribute specifies the maximum number
      of targets against which a tool can run. The revision attribute
      allows a tool author to specify a revision for the tool. Note
      that this is for information only.  The job-log attribute
      specifies whether the results of the command will be kept in this
      systems job log. When job-log="true" the job and target status
      for the tool will be kept for a relatively lengthy system-defined
      period in the database after the job completes. When
      job-log="false" only the last completed copy of the job and
      target status for the tool will be kept in the cache for a much
      shorter period of time, and will not be written to the database.
      Job logging is enabled by default. The schedulable attribute
      specifies whether the tool can be run as a scheduled task. When
      schedulable="false" the tool can only run as a "run now" task.
      Tools are schedulable by default.  The guid attribute specifies a
      globally unique identifier (GUID) for the tool. Because the
      system generates a GUID for a tool during the add operation, this
      field should only be specified during a modify operation. The
      accepts-targets attribute specifies whether the tool
      accepts targets for execution. The accepts-targets attribute is
      true by default. -->
      
!ATTLIST automation-tool	 name	     CDATA   #REQUIRED
      visible     (true | false) "true"
      max-targets NMTOKEN #IMPLIED
      revision    CDATA   #IMPLIED
      job-log     (true | false) "true"
      schedulable (true | false) "true"
      guid	     NMTOKEN #IMPLIED
      accepts-targets (true|false) "true" >

<!-- The automation-block specifies the elements specific to an
      automation tool. The automation-block must specify a
      message-id. -->
      
<!ELEMENT automation-block (message-id) >

<!-- The message-id is the internal string representation of the message
      sent by the Automation engine to cause the tool to run. -->
      
<!ELEMENT message-id ( #PCDATA ) >

<!-- The app-launch-tool element specifies an application launch
      tool. The app-launch-tool element can optionally specify a
      category element, a menu-category element, a description element,
      a comment element, an owner element, a default-target element, an
      execute-as-user element, a job-display-handler element, a
      default-parameter element, a role-enabled element, zero or more
      role elements,  zero or more include-filter elements, or zero or
      more env-variable elements. If more than one of these elements
      are specified, the element must appear in the order as listed in
      this definition. The app-launch-tool element must contain an
      app-launch-block element. The app-launch-block element must
      appear after the previously described optional elements, if any
      of the optional elements are specified. Following the
      app-launch-block element, one can specify zero or more attribute
      elements. -->

<!ELEMENT app-launch-tool (category?, description?, comment?, owner?,
      default-target?, execute-as-user?,
      job-display-handler?,
      role-enabled?, role*,
      toolbox-enabled?, toolbox*,
      include-filter*,  env-variable*,
      app-launch-block, attribute* ) >

<!-- In addition to the previously described elements, the
      app-launch-tool element specifies the following attributes. The
      name attribute specifies the tool name and must be specified in
      the app-launch-tool element. The visible attribute specifies
      whether the tool is visible for running. By default tools are
      visible. The max-targets attribute specifies the maximum number
      of targets against which a tool can run. The revision attribute
      allows a tool author to specify a revision for the tool. Note
      that this is for information only.  The job-log attribute
      specifies whether the results of the command will be kept in this
      systems job log. When job-log="true" the job and target status
      the tool will be kept for a relatively lengthy system-defined
      period in the database after the job completes. When
      job-log="false" only the last completed copy of the job and
      target status for the tool will be kept in the cache for a much
      shorter period of time, and will not be written to the database.
      Job logging is enabled by default. The schedulable attribute
      specifies whether the tool can be run as a scheduled task. When
      schedulable="false" the tool can only run as a "run now" task.
      Tools are schedulable by default.  The guid attribute specifies a
      globally unique identifier (GUID) for the tool. Because the
      system generates a GUID for a tool during the add operation, this
      field should only be specified during a modify operation. The
      accepts-targets attribute specifies whether the tool
      accepts targets for execution. The accepts-targets attribute is
      true by default. -->

<!ATTLIST app-launch-tool	 name	     CDATA   #REQUIRED
      visible     (true | false) "true"
      max-targets NMTOKEN #IMPLIED
      revision    CDATA   #IMPLIED
      job-log     (true | false) "true"
      schedulable (true | false) "true"
      guid	     NMTOKEN #IMPLIED
      accepts-targets (true|false) "true" >

<!-- The app-launch-block specifies the elements specific to an
      application launch tool. The app-launch-block specifies a
      required command element. -->
      
<!ELEMENT app-launch-block (command, app-parameters?) >

<!-- In addition to the previously described elements, the
      app-launch-block element specifies the following attribute. The
      alert-driven attribute specifies whether the alert list or the
      system list is used to determine the target systems to run the tool
      on. -->

<!ATTLIST app-launch-block alert-driven (true | false) "false" >

<!-- The app-parameters element is an application parameters
      definition string whose value is a string -->
      
<!ELEMENT app-parameters ( #PCDATA ) >

<!-- The env-variable element is an environment variable definition
      string whose value is a string -->
      
<!ELEMENT env-variable ( #PCDATA ) >

<!-- In addition to the previously described elements, the
      env-variable element specifies the following attribute. The
      name attribute specifies the name of the environment variable.-->
      
<!ATTLIST env-variable name CDATA #REQUIRED >

<!-- The owner element specifies the tool owner. When the owner field
      is specified, the tool is only associated with the All Tools toolbox.
      When the owner field is not specified, tool is enabled in all
      of its associated toolboxes. When a limited-rights user adds or
      modifies a tool, the owner field contains the name of the
      limited-rights user. Only a full-rights user can add or modify a
      tool without the owner specified. -->
      
<!ELEMENT owner ( #PCDATA ) >

 !-- The comment field specifies additional information about the
      tool. It is usually more verbose that the description. -->

<!ELEMENT comment ( #PCDATA ) >

<!-- The parameter element specifies the first to the tenth parameter
      of a tool. -->
     
<!ELEMENT parameter EMPTY >

<!-- The parameter element has three attributes. The index attributes
      specifies which argument in a parameterized string this parameter
      substitutes. Parameters can be indexed from 1 to 10 with a
      default index of 1. Tools cannot contain parameters with
      duplicate indexes. If more than one parameter in a tool
      definition contains the same index, only the first parameter added
      to the tool with the duplicate index remains in the tool. The
      prompt attribute provides information about the parameter that
      can be displayed in a GUI for assistance. The required attribute
      specifies whether this parameter must be specified when the tool
      is executed. By default, parameters are not required.  The private
      attribute specifies whether this parameter is encoded and stored
      securely.  By default, parameters are not private. -->
<!ATTLIST parameter index	 (1|2|3|4|5|6|7|8|9|10) "1"
     prompt CDATA #REQUIRED
      required (true|false) "false"
      private (true|false) "false" >

<!-- The toolbox-enabled element specifies whether the toolboxes
      associated with a tool are enabled. -->

<!ELEMENT toolbox-enabled EMPTY >

<!-- The toolbox-enabled element has one attribute. The value
      attribute specifies whether the tool within the toolboxes is enabled.
      This allows a full-rights user to explicitly disable the tools in
      a toolbox though the tool is always enabled in the All Tools
      toolbox.  By default, the tool is enabled in all the toolboxes that
      it is in.  If a tool is disabled within a toolbox, it cannot be
      executed. -->
      
<!ATTLIST toolbox-enabled value (true|false) "true">

<!-- The role-enabled element specifies whether the roles associated
      with a tool are enabled. This is an obsolete element. The
      toolbox-enabled element should be used instead.-->
      
<!ELEMENT role-enabled EMPTY >

<!-- See description of toolbox-enabled element attributes. -->

<!ATTLIST role-enabled value (true|false) "true">

<!-- The default-target element specifies a target on which the tool
      can run if no targets are specified at run time. One can specify
      a system, &cms2; to run on the &cms2; by default, or ALL to run on all
      authorized systems by default. -->
      
<!ELEMENT default-target ( #PCDATA ) >

<!-- The category element specifies the category with which to
      associate the tool. By default, tools are associated with the
      "Local Tools" category. -->

<!ELEMENT category ( #PCDATA ) >

<!-- The description element specifies a simple description of the
      tool. To specify more verbose information such as how to run the
      tool, use the comment element. -->

<!ELEMENT description ( #PCDATA ) >

<!-- For SSA and MSA command tools, the execute-as-user element
      specifies the user name that the tool runs as or under whose
      account the tool runs on the target systems. For Web-launch
      tools the execute-as-user is passed to the URL for its use. -->

<!ELEMENT execute-as-user ( #PCDATA ) >

<!-- The job display hander element specifies the fully-qualified
      name of a class implementing the JobDisplayHander interface,
      used to display the results of a job created by running this
      tool. -->

<!ELEMENT job-display-handler ( #PCDATA ) >

<!-- The toolbox element specifies a toolbox to associate with the
      tool. To run a tool the user must be authorized with one of the
      specified toolboxes. -->

<!ELEMENT toolbox EMPTY >

<!-- The toolbox element has one attribute to specify the toolbox
      name. -->

<!ATTLIST toolbox toolbox-name CDATA #REQUIRED >

<!-- The role element specifies a role to associate with the tool. To
      run a tool the user must be authorized with one of the specified
      roles. This element is obsolete. The toolbox element should be
      used instead. -->

<!ELEMENT role EMPTY >

<!-- See the toolbox element attribute description. -->

<!ATTLIST role role-name CDATA #REQUIRED >

<!-- The include-filter element specifies system attributes against
      which to filter a tool for execution. A specified include-filter
      element must contain one or more system-filter elements. When
      filtering a tool each include-filter block is OR'd together to
      get the final filter result. Each system-filter element within an
      include-filter block is AND'd together. -->
      
<!ELEMENT include-filter (system-filter)+ >

<!-- The include-filter elements has one attribute. The type attribute
      specifies the type of include filter to execute. Four types are
      currently recognized.  Three of them are os (operating system), 
      hardware, protocol filtering. The fourth type is called other which 
      will allow all other system attributes to be filtered upon.-->

<!ATTLIST include-filter type (os | hardware | protocol | other) "os" >

<!-- The system-filter element is an empty element that contains
      attributes used to specify the system attributes against which to
      filter a tool for execution. -->
      
<!ELEMENT system-filter EMPTY >

<!-- The system-filter element is specified with three attributes. The
      name attribute specifies the system attribute name to filter
      against. The operator attribute specifies whether to filter
      against an equal value, a less than value, a greater than or
      equal value, a contains value, a not equals value or a not
      contains value. The operator name is case-insensitive. The
      value attribute specifies the value of the system attribute to
      filter against. -->
      
<!ATTLIST system-filter name CDATA #REQUIRED
      operator (EQ | GE | LT | CT | NEQ | NCT |
      eq | ge | lt | ct | neq | nct |
      Eq | Ge | Lt | Ct | Neq | Nct |
      eQ | gE | lT | cT | nEQ | nCT ) "EQ"
      value CDATA #REQUIRED >

<!-- The attribute element specifies the name value pairs that
      comprise client attributes. The client attribute name is
      specified using the name attribute and the client attribute value
      is specified as the PCDATA of the element. -->

<!ELEMENT attribute ( #PCDATA ) >

<!ATTLIST attribute name CDATA #REQUIRED >
			

Related Procedures

» Creating New Command Line Tools - New Command Line Tool
» Creating New Command Line Tools - New Copy a File Tool
» Tools that Extend Management - Removing and Restoring Tools
» Custom Commands - New Web Launch Tool
» Creating New Command Line Tools - New X Window Tool

Related Topic

» Tools that Extend Management - Command Line Tools