Copyright © Cloud Software Group, Inc. All Rights Reserved

External Command

Activity

The External Command activity allows you to execute an operating system command. This activity waits for the command to complete before transitioning to the next activity. Optionally, the command output and any errors can be included in this activity’s output schema, written to a file, or both.

Long-Running Commands

If you want to execute long-running commands (such as daemons), it may not be practical to execute the command directly. Because the specified command must terminate before control is passed to the next activity, the process instance must run until the external command completes. To avoid this problem, you may want to create a script that runs the desired commands in the background.

The syntax of executing commands as background processes differs by operating system. For example, on UNIX, to run a command in the background, you append the ampersand character (&) to the command. On Microsoft Windows, you use the START command in a batch file to run a command in a different process.

After creating a script to run commands in the background, specify the script as the command to run in the External Command activity. The script runs the desired command and returns the process ID of the process it started. The return code of the script is stored in the returnCode item of the External Command activity’s output.

If you want to start a long-running command in the background and then later terminate the background process, you should store the process ID returned by the script in a file or database table. Another process instance can then read the process ID and kill the process with the appropriate operating system command when necessary.

Configuration

The Configuration tab has the following fields.

Field	Global Var?	Description
Name	No	The name to appear as the label for the activity in the process definition.
Description	No	Short description of the activity.
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). You can specify a global variable for this configuration field. This allows you to easily specify different commands on different operating systems. For example, you may specify %%EXTERNAL_COMMAND%% as the value for this field. On MS Windows, the value of the global variable may be the following:   cmd /c dir On UNIX, the global variable may have the following value:   ls If the command to execute is not located in one of the directories specified in the PATH environment variable (on UNIX or Windows), you can specify the full path for the executable command or you can use the environment input element to specify the environment for the command.
Make Output Available as Activity Output	Yes	When checked, this field specifies that the output sent to standard output and standard error by the command should be available in the output schema of this activity. For commands that produce a large amount of output, it is recommended to uncheck this field and write the output to a file. This saves memory and allows you to use other activities, such as Read File and Parse Data, to handle the output file more efficiently.
Remove Parameter Quotes	Yes	When checked, this field specifies that the quotes surrounding the parameters should be removed. The quotes will be removed even if the parameter contains space(s). By default, the check box is not selected.
Output Filename	Yes	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	Yes	Controls whether the command output and errors are split into multiple strings. This field can have the following values: • None — The activity produces a single string containing the command’s output or errors. Line end characters are included in this string. • At Operating System Line End — The 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.

Input

See TIBCO ActiveMatrix BusinessWorks Process Design for more information about mapping and transforming input data.

The input for the activity is the following.

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 Configuration tab.
input	string	An input string to supply to the command’s standard input. This schema item accomplishes the same goal as entering the command from a command prompt and then typing in input without specifying a carriage return. For example, on UNIX, typing sed into a command prompt allows you to enter more text as input into the sed command. Use &crlf; in the string for this item to specify a carriage return (that is, &crlf; simulates pressing the Enter key).
environment	string	The environment variable settings used for running the command. This element is specified as a comma-separated list of <name>=<value> pairs where <name> is the name of the environment variable and <value> is the value of the environment variable. If no value is specified for this element, the command is run with the environment variable settings that are specified in the login scripts for the user account used to execute the TIBCO ActiveMatrix BusinessWorks process engine. If a value is specified, the value of this element replaces any environment settings for the user account used to run the TIBCO ActiveMatrix BusinessWorks 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 workingDirectory is not specified, the command process inherits its working directory from the process engine.
token	string	Command output can be split into multiple strings based on the token specified in this element. This field is only available when At Specified Token is chosen in the Line Split field on the Configuration tab. The following escape sequences are supported in this element: • \r — newline carriage return character • \n — newline character • \t — tab character • \\ — backslash character For example, \r\n signifies to split at a carriage return/linefeed, \\ signifies to split when a backslash is encountered.

Output

The output for the activity is the following.

Output Item	Datatype	Description
returnCode	integer	The numeric return code returned by the command. Typically, a value of 0 in this element signifies the command executed successfully. 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 only available if the Make Output Available as Activity Output field is checked on the Configuration tab. This element can be repeating 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 the "Make Output Available as Activity Output" field is checked on the Configuration tab. This element can be repeating if the Line Split configuration setting causes the command’s errors to be split into several lines.

Error Output

The Error Output tab lists the possible exceptions that can be thrown by this activity. See TIBCO ActiveMatrix BusinessWorks Error Codes for more information about error codes and corrective action to take.

Exception	Thrown When...
InvalidInputException	There is an error in the activity’s configuration or input mapping that is preventing the command from being executed.
CommandExecutionError	The command could not be executed.
FileIOError	There was an error when attempting to write the output to a file. Make sure the user that is running the TIBCO ActiveMatrix BusinessWorks engine has permission to write to the output file.

Copyright © Cloud Software Group, Inc. All Rights Reserved