Use special commands

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 ksc_command_name.

• User-defined special commands have the naming convention sc_command_name.

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.

Figure 3-1. RCS File Migration object type

Special Command Parameters

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

This makes ksc_copy_server_server equivalent to:

ksc_copy_server_server FILENAME="[P.P_FILENAME]"

because [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

Special Command Language

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.

Nesting Special Commands

You can use special commands within other special commands, but only within a command step. However, a special command cannot refer to itself.

Special Command Conditions

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.

Table 3-1. Example conditions

Condition	Evaluates to
BLANK	Command executes in all situations.
'[REQ.DEPARTMENT]' = 'SALES'	Command executes if the department for the request is named SALES.
'[REQ.PRIORITY]' = 'HIGH'	Command executes if the priority assigned to the request is HIGH.

A condition can include a token. For information on how to include tokens in conditions, see Use tokens for more information.

Using the PPM Workbench to List Special Commands

To see a list of the special commands on your PPM instance:

1. Log on to PPM.

2. From the menu bar, select Open > Administration > Open Workbench.

   The PPM Workbench opens.

3. From the shortcut bar, select Configuration > Special Commands.

   The Special Command Workbench window opens.

4. Click List.

   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.

About the Special Command Builder

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.

Figure 3-2. Special Command Builder

For information about how to use the Special Command Builder, see Use the Special Command Builder.