Object types, request types, report types, workflows, and validations all use commands to access the execution layer. To simplify command execution, PPM provides a predefined set of special commands. Users can also create their own special commands.
Special commands are commands with variable parameters and are used in object types, request types, report types, workflows, and validation command steps. Workflows use special commands in their workflow step sources. These command steps perform various functions, such as copying files between environments and establishing connections to environments for remote command execution. PPM features two types of special commands:
System special commands are shipped with the PPM. System special commands are read-only and have the naming convention
User-defined special commands have the naming convention
This section provides information about how to create, edit, and use special commands in PPM.
Special commands are added to command steps directly in the entity windows (for object types, request types, report types, validations and workflows). For example, Figure 3-1. RCS File Migration object type shows an example of an object type that was generated using a combination of special commands.
Most special commands have parameters to override standard behavior. The Parameters tab displays these. Nearly all parameters are optional.
If a parameter is not passed to a special command and the default value for the parameter is a custom token, the entity using the command must contain a field with that token.
For example, the
ksc_copy_server_server special command is used in an object type. The parameter
FILENAME is not specified and defaults to
[P.P_FILENAME] because it is not explicitly passed.
ksc_copy_server_server equivalent to:
[P.P_FILENAME] is the default token for the parameter
FILENAME. The command execution engine evaluates the token
[P.P_FILENAME] so it must be defined for the entity (the specific object type, report type or request type).
To override the default token, pass in another value for the parameter. A few examples are:
ksc_copy_server_server FILENAME="document.txt" ksc_copy_server_server FILENAME="[P.DOCUMENT_NAME]"
This method of passing parameters is explained in more detail in the section entitled About the Special Command Builder
Note: Custom tokens are defined for specific object types, request types, and report types, and are referenced using the
The command steps in a special command define the system-level executions that must be performed to realize the command function. Command steps can be UNIX commands, third-party application commands, or special commands. Special commands are reusable routines defined in PPM.
PPM also supplies several system special commands that you can use to perform common events such as connecting to environments or copying files.
You can use special commands within other special commands, but only within a command step. However, a special command cannot refer to itself.
Depending on the context in which commands are executed, you may need to run a different set of commands. For example, one command may update a Web page, while another may set up an account on the Sales Automation application.
To achieve this flexibility, you use conditional commands. You can use the Condition field for an object command to specify the conditions under which the associated command steps are to be executed.
Conditions are evaluated as Boolean expressions. If the expression evaluates to TRUE, the command is executed. If it evaluates to FALSE, the command is skipped and the next command is evaluated to see if it should be run. If no condition is specified, the command is always executed.
The syntax of a condition is identical to the WHERE clause of a SQL statement, which allows flexibility when evaluating scenarios. Table 3-1. Example conditions provides some example conditions.
Note: In conditional commands, you must use single quotes to enclose strings.
A condition can include a token. For information on how to include tokens in conditions, see Use tokens for more information.
To see a list of the special commands on your PPM instance:
Log on to PPM.
From the menu bar, select Open > Administration > Open Workbench.
The PPM Workbench opens.
From the shortcut bar, select Configuration > Special Commands.
The Special Command Workbench window opens.
The Special Command Workbench window lists descriptions of all the special commands and indicates the status (enabled or not) of each.
Tip: You can also use the Special Command Details report to view a list of special commands on your PPM instance. For information on how to access and run this report, see Use the special command details report to list special commands.
The Special Command Builder (Figure 3-2. Special Command Builder) helps you format command steps quickly and correctly. After you select a special command and specify its parameters, the Special Command Builder populates the Command field with a line of text that you can use as a command step.
For information about how to use the Special Command Builder, see Use the Special Command Builder.