External Command

External Command is a synchronous activity that executes the command on the operating system. This activity waits for the command to complete before transition to the next activity. Optionally, the command output and errors can be included in this activity's output schema, written to a file, or both.

General

The General tab has the following fields.

Field Literal Value/Process Property/Module Property Description
Name None The name to be displayed as a label for the activity in a process.
Command To Execute Yes The command line to execute. You can also specify any input and command-line arguments to the command in this field.

You cannot specify more than one command by piping output from one command to another (for example, ls | more is not allowed).

Provide Command Output None Selecting this check box specifies that the output sent to the standard output and standard error by command is available in the output schema of this activity.
Caution: Do not select the check box for the commands that produce a large amount of output. Instead, write the output to a file. This saves memory and you can use other activities, such as Read File and Parse Data, to handle the output file more efficiently.
Remove Parameter Quotes Yes If this check box is selected, the quotes surrounding the parameters are removed. The quotes are removed even if the parameter contains space(s).

By default, this check box is clear.

Output Filename Yes The name and location of the file for storing any output or errors produced by the command. If this field is blank, no output file is created.
Output Line Splitting None Controls whether the command output and errors are split into multiple strings.

Select any one from the following available options:

  • None: This activity produces a single string containing the command’s output or errors. This string includes line end characters.
  • At Operating System Line End: This activity produces a repeating string element with one string element per output line. The lines are split by default on the carriage return/line feed character, depending on the operating system. The line end characters are not included in the output.
  • At Specified Token: The lines are split wherever the specified token occurs. The token is specified as an activity input element, and the token is not included in the output.

Description

Provide a short description of the activity.

Input

The following is input for this activity.

Input Item Datatype Description
command string The command to execute, including any input or command-line arguments.

Specifying this input item overrides the command specified on the General tab.

input string An input string to supply to the command’s standard input.

This schema item attains the same result as entering the command from a command prompt and then typing the input without specifying a carriage return.

outputFile string The file containing the output produced by the command for sending it to stdout.
environment string The environment variable settings used to run the command. This element is specified as a comma-separated list of <name>=<value> pairs where:
  • <name> is the name of the environment variable
  • <value> is the value of the environment variable

If no value is specified for this element, the command is executed with the environment variable settings specified in the login scripts, for the user account used to execute the process engine.

If a value is specified, the value of this element replaces any environment settings for the user account used to run the process engine.

That is, the user environment is ignored and this element’s value is used instead.

workingDirectory string The working directory for the command process.

If not specified, the command process inherits its working directory from the process engine.

Output

The following is the output for the activity.

Output Item Datatype Description
returnCode integer The numeric return code returned by the command.

Typically, a value of 0 (zero) in this element signifies a successful command execution.

A non-zero value usually indicates termination of the command due to an error.

output string Any output produced by the command and sent to stdout. This output item is available only when you select the Provide Command Output check box on the General tab.

This is a repeating element, if the line split configuration setting causes the command’s output to be split into several lines.

error string Any errors produced by the command and sent to stderr. This element is only available if you select the Provide Command Output check box on the General tab.

This is a repeating element, if the line split configuration setting causes the command’s output to be split into several lines.

Fault

The Fault tab lists the possible exceptions generated by this activity. For more information about error codes and the corrective actions to take, see the TIBCO ActiveMatrix BusinessWorks™ Error Codes guide.

Fault Generated When..
CommandExecutionError The command could not be executed.
FileIOError There was an error when attempting to write the output to a file.

Ensure that the user running the ActiveMatrix BusinessWorks™ engine, has the write permission to the output file.

InvalidInputException An error in the activity’s configuration or input mapping prevents the command from being executed.