4.2.9 Terminal command plug-in

Function

This plug-in allows you to execute a specified command on an operation target device connected to by a terminal connect plug-in.

The commands specified in the terminal command plug-in are executed with the privileges of the user authenticated by the terminal connect plug-in. To execute a command with administrator privileges, the terminal command plug-in must execute the command that elevates the user to administrator privileges.

Prerequisites for execution

The protocol specified in the protocol property of the terminal connect plug-in is used to communicate with the JP1/AO server. For details, see the description of the protocol property in 4.2.8 Terminal connect plug-in.
For details about the operation target devices that can be used as connection destinations, see A.1(3) Operation target devices usable as connection destinations.
A connection must have been established with the operation target device by a terminal connect plug-in.

Cautionary notes

The plug-in waits for standard output for the length of time specified in the readWaitTime property. If the time specified in readWaitTime elapses after output to standard output has ceased, plug-in execution ends in an error. Make sure that the value of the readWaitTime property is appropriate before using the plug-in. Any information output after the plug-in has timed out is discarded.
If the value output to standard output matches the regular expression pattern specified in the promptPattern property, the plug-in terminates immediately.
If the command outputs information one page at a time, the system assumes that standard output has ceased. If the time period specified in the readWaitTime property then passes, the plug-in ends with an error. Make sure that the command executed by the terminal command plug-in is not configured to output results one page at a time.
Echoed command lines are also output to standard output. When needed, configure the command to not echo back.
If execution of a task is stopped during plug-in execution, the status of the task becomes Failed or Completed when the processing of the terminal command plug-in has finished. The session and token are then discarded. The status of steps and tasks after plug-in execution has finished depends on the return code of the step and the condition for executing subsequent steps. You can set Subsequent-step Execution Condition in the Create Step dialog box or the Edit Step dialog box.
If you forcibly terminate a task during plug-in execution, reading from standard output and prompt detection are canceled and the task enters Failed status. The session and token are then discarded. In this case, a return code of 80 appears for the step in the Flow area of the Tasks window. The return code output to the task log depends on the timing with which the task was forcibly terminated.
When a task is forcibly terminated during plug-in execution, the execution results of the command or script specified in the commandLine property are outside the scope of product support.
If the status of the subsequent step of the terminal connect plug-in is Failed, the Telnet or SSH connection is terminated. For this reason, if you use the Retry the Task From the Failed Step or Retry the Task From the Step After the Failed Step command to retry the task, the processing of the terminal command plug-in fails. This does not apply when retrying a repeated execution plug-in to which the terminal connect plug-in is subordinate.
The standard output and standard error output of the terminal command plug-in is output as the standard output of the JP1/AO step. The size of the standard output and standard error output is the total number of bytes received by JP1/AO. If the Telnet server or SSH server is configured to replace the linefeed character LF with CR+LF, allow two bytes for each linefeed character. The results of processing whose total standard output and standard error output exceeds 100 KB is outside the scope of product support. Make sure that the total standard output and standard error output does not exceed 100 KB.
If you intend to specify non-ASCII characters in the commandLine property, see A.4 Prerequisites for executing command lines containing non-ASCII characters in UNIX.
Interactive commands and script that seek user input and commands that do not end automatically using a GUI display or the like cannot be executed.
Depending on the OS specifications of the operation target device, if a command line that exceeds the console width is specified for the commandLine property, the command line character string may be split and entered. At this time, since the prompt is displayed before the command execution is completed, the part may not be terminated correctly. In that case, it can be avoided by expanding the console width. If the operation target device is Linux, the console width can be expanded by executing the following command.
```
stty cols [ConsoleWidth]
```
For the [ConsoleWidth], specify a value greater than or equal to "number of prompt characters + number of command line characters + 10". The extended console width is valid until the connection with an operation target device is terminated using the terminal disconnect plug-in, or the session and token are then discarded.

Version

02.00.00

Tag

Terminal

Return codes

Return code	Description
0 to 63	If standard output and standard error output match the regular expression pattern specified in the `returnCodePattern` property, the plug-in returns the return code specified in the `returnCode` property. However, if the output does not match the pattern, the plug-in returns the return code specified in the `defaultReturnCode` property. Therefore, the meaning of the return code depends on the service template that is using the plug-in.
65	The connection with the JP1/AO server failed. For example, the JP1/AO server might have stopped while the plug-in was being executed.
66	The following user is mapped to the JP1 user: A user who does not belong to the Administrators group. A user other than the built-in Administrator who belongs to the Administrators group, in an environment with UAC enabled.
68	There is no information about the target job execution ID.
69	An environment variable of the task-processing engine could not be acquired.
70	The connection with the operation target device was lost.
80	Task execution has stopped.
81	The plug-in was called in an invalid status.
82	The request message from the task-processing engine could not be correctly parsed.
83	The environment of the JP1/AO server is corrupted.
84	Information about the specified plug-in could not be obtained.
86	The specified property value is invalid. Alternatively, an input property has an invalid token.
87	Standard output and standard error output have timed out.
88	The total standard output and standard error output has exceeded 100 KB.
127	Another error has occurred.

Property list

The following table describes the properties.

Property key	Property name	Description	Default value	I/O type	Required
`token`	Token	Specify the value of the `token` property of the terminal connect plug-in.	--	Input	R
`commandLine`	Command Line	Specify the absolute path of the command or script to execute on the operation target device, using no more than 1,024 characters. In the command line, specify characters that can be used in commands in the operating systems of the JP1/AO server and the operation target device. Special characters that represent environment variables in the command line are not escaped. To handle a special character as a character string, escape the character with a percent sign (`%`) in Windows, and a backslash (`\`) in UNIX. If you need to enter the superuser password in the command line to give the user administrator privileges, specify the `reserved.terminal.suPassword` reserved property. The `reserved.terminal.account`, `reserved.terminal.password`, and `reserved.terminal.suPassword` reserved properties reference token-related authentication information set for the terminal connect plug-in. The specific authentication information the properties reference depends on the setting of the `credentialType` property of the terminal connect plug-in. If `destination` is specified for the `credentialType` property: The reserved properties reference the authentication information defined in the connection destination. If `property` is specified for the `credentialType` property: The reserved properties reference the authentication information specified in the `credentialType` property of the terminal connect plug-in.	--	Input	O
`charSet` ^#1	Character Set	Specify the character set to use when writing to the standard input of the operation target device and reading from standard output and standard error output. Specify the same character set as that of the user who logs in to the operation target. The names of character sets are not case sensitive. You can specify the following character sets: `EUC-JP` `eucjp` `ibm-943C` `ISO-8859-1` `MS932` `PCK` `Shift_JIS` `UTF-8` `windows-31j`	--	Input	O
`lineEnd`	Newline Character	Specify the newline character to append to the value set in the `commandLine` property. You can specify the following: `CR` `LF` `CRLF` To use `0x0D` as the newline character, specify `CR`. To use `0x0A`, specify `LF`, and to use `0x0D0A`, specify `CRLF`.	`CR`	Input	O
`promptPattern`	Prompt Pattern	Specify the regular expression pattern to use to detect prompts in standard output and standard error output, using no more than 1,024 characters. This property is used to detect when the operation target device is ready to execute another command. Specify the pattern in a PCRE-compliant format. When the output matches the specified regular expression pattern, the plug-in ends immediately. If the output does not match the pattern, the plug-in ends in an error when the time set in the `readWaitTime` property has elapsed since the last output to standard output or standard error output.	--	Input	R
`readWaitTime`	Standard Output Wait Time	When executing a command, specify how long to wait after output to standard output or standard error output until the next output. Specify the timeout time in a range from 1 to 86,400,000 (in milliseconds).	60000	Input	O
`stdoutPattern1`	Standard Output Pattern 1	Specify the regular expression pattern of the standard output and standard error output to output to the `stdoutProperty1` property, using a maximum of 1,024 characters. Specify the regular expression pattern in a PCRE-compliant format.^#3 If you use more than 1,024 characters, the 1,025th and subsequent characters are discarded.	--	Input	O
`stdoutProperty1`	Standard Output Property 1	The character string extracted by the `stdoutPattern1`property is output to this property.	--	Output	O
`stdoutPattern2`	Standard Output Pattern 2	Specify the regular expression pattern of the standard output and standard error output to output to the `stdoutProperty2` property, using a maximum of 1,024 characters. Specify the regular expression pattern in a PCRE-compliant format.^#3 If you use more than 1,024 characters, the 1,025th and subsequent characters are discarded.	--	Input	O
`stdoutProperty2`	Standard Output Property 2	The character string extracted by the `stdoutPattern2` property is output to this property.	--	Output	O
`stdoutPattern3`	Standard Output Pattern 3	Specify the regular expression pattern of the standard output and standard error output to output to the `stdoutProperty3` property, using a maximum of 1,024 characters. Specify the regular expression pattern in a PCRE-compliant format.^#3 If you use more than 1,024 characters, the 1,025th and subsequent characters are discarded.	--	Input	O
`stdoutProperty3`	Standard Output Property 3	The character string extracted by the `stdoutPattern3` property is output to this property.	--	Output	O
`defaultReturnCode`	Default Return Code	Specify the value to return as the return code when standard output and standard error output do not match the regular expression pattern specified in the `returnCodePattern` property. Specify a value in the range from 0 to 63.	0	Input	O
`outputCondition`^#2	Condition for outputting standard output properties	Specify the condition for outputting values to the stdoutProperty1, stdoutProperty2, and stdoutProperty3 properties. You can specify either of the following values: always Values are always output to the stdoutProperty1, stdoutProperty2, and stdoutProperty3 properties. Null characters are output if the standard output and standard error output do not match the stdoutPattern1, stdoutPattern2, and stdoutPattern3 properties. patternMatch Values are output to the stdoutProperty1, stdoutProperty2, and stdoutProperty3 properties only if the standard output and standard error output match the stdoutPattern1, stdoutPattern2, and stdoutPattern3 properties. If the standard output and standard error output do not match the stdoutPattern1, stdoutPattern2, and stdoutPattern3 properties, no values are output. In this case, values are not updated even if the service properties are mapped to the stdoutProperty1, stdoutProperty2, and stdoutProperty3 properties.	always	Input	R
`returnCodePattern`	Return Code Pattern	Specify the regular expression pattern for standard output and standard error output, using a maximum of 1,024 characters. Specify the regular expression pattern in a PCRE-compliant format. If standard output and standard error output match the specified pattern, the plug-in returns the value specified in the `returnCode` property.	--	Input	O
`returnCode`	Return Code	Specify the return code to be returned by the plug-in when standard output and standard error output match the pattern set in the `returnCodePattern` property. You can specify a value in the range from 0 to 63. If you omit this property, the plug-in returns the value specified in the `defaultReturnCode` property.	--	Input	O

#1

You can also set the character set in the terminal.charset property of the connection-destination property file (connection-destination-name.properties). If the charSet property and the terminal.charset property in the connection-destination property file (connection-destination-name.properties) are both set, the value in the charSet property applies. If neither is specified, UTF-8 is set.

#2

This property is not available for plug-ins of versions earlier than 02.00.00. For versions earlier than 02.00.00, the system behaves as if patternMatch is specified. When plug-ins are updated to their latest versions, the value of this property will be reset to the default value (always). Reconfigure this property if necessary.

#3

The parts grouped by parentheses are extracted by the regular expression.
If you specify multiple groups in the regular expression, only values that match the first group are stored in the output property of the plug-in.
If the regular expression applies to multiple value ranges, only the first range of values is stored in the output property of the plug-in. Multiple value ranges cannot be stored in an output property.
If you specify "(.*)", you can extract the character string from the beginning to the line feed of the character string including the line feed, such as the execution result of any command.

Example of using the stdoutPattern1, stdoutPattern2, and stdoutPattern3 properties, and the stdoutProperty1, stdoutProperty2, and stdoutProperty3 properties

You can compare the standard output and the standard error output to the values of the stdoutPattern1, stdoutPattern2, and stdoutPattern3 properties, and then store the results in the stdoutProperty1, stdoutProperty2, and stdoutProperty3 properties. The following figure shows the data flow when specifying aaabbb(.*) in stdoutPattern1.

Figure 4‒4: Example of using the stdoutPattern and stdoutProperty properties

As defined in stdoutPattern1, for the standard output aaabbbccc, the value after aaabbb (in this case ccc) is extracted. The extracted value is stored in the stdoutProperty1 property.

You can use the outputCondition property to specify whether values are to be output to the stdoutProperty1, stdoutProperty2, and stdoutProperty3 properties in the following case: the standard output does not match the regular expressions specified for the stdoutPattern1, stdoutPattern2, and stdoutPattern3 properties and, as a result, the values cannot be extracted.

Related topics

Organization of this subsection

(1) Example of using the terminal command plug-in

(1) Example of using the terminal command plug-in

Example of terminating a terminal command plug-in with an error when an error is output to standard output

The table below describes an example of a terminal command plug-in that terminates with an error when it acquires error-related information from standard output. Set the plug-in property as follows:

Property key	Example of specified value	Meaning of specified value
`commandLine`	`configServer arg0 arg1 arg2`	Executes the specified command or script.
`promptPattern`	`^\[prompt\]`	If the contents of standard output matches `[prompt]`, the plug-in terminates and determines the return value.
`stdoutPattern1`	`^Message:(.*)`	The character string following `Message:` in standard output is stored in the `stdoutProperty1` property.
`stdoutPattern2`	`^Error:(.*)`	The character string following `Error:` in standard output is stored in the `stdoutProperty2` property.
`stdoutPattern3`	`^ReturnCode:(.*)`	The character string following `ReturnCode:` in standard output is stored in the `stdoutProperty3` property.
`defaultReturnCode`	0	If the contents of standard output do not match the value specified in the `returnCodePattern` property, return code 0 is returned.
`returnCodePattern`	`^Error:`	If the contents of standard output match `Error:`, the plug-in returns the return code specified in the `returnCode` property.
`returnCode`	1	If the contents of standard output matches the value specified in the `returnCodePattern` property, the plug-in returns code 1.

The following describes the operation of a plug-in with the above properties when it encounters the following standard output.

[Figure]

The contents of standard output match the value specified in the promptPattern property, so the terminal command plug-in determines which return code to return. Because standard output matches the value specified in the returnCodePattern property, the plug-in returns code (1), the value specified in the returnCode property.

The character strings extracted by the properties stdoutPattern1 to stdoutPattern3 are stored as follows in the properties stdoutPrpoerty1 to stdoutProperty3

stdoutProperty1: command failed
stdoutProperty2: Permission Denied
stdoutProperty3: 128

Example of sending a GET request to an HTTP server

The following describes how to configure a plug-in that issues a request like the one below to an HTTP server and verifies the response.

[Figure]

To issue a GET request to an HTTP server, specify each line of the request method and request header in the commandLine property of a terminal command plug-in.

Because the last line of the request needs to be blank, you need to execute the terminal command plug-in five times. The following table describes examples of the values to set in the properties of each instance of the plug-in.

Order of execution	Value specified in commandLine	Value specified in lineEnd^#1	Value specified in promptPattern
First	GET /index.html HTTP/1.1	CRLF	.*^#2
Second	Host: ServerA	CRLF	.*^#2
Third	User-Agent: JP1/AO	CRLF	.*^#2
Fourth	Accept-Charset: UTF-8	CRLF	.*^#2
Fifth	--	CRLF	</HTML>^#3

Legend:: --: This instance adds a blank line. Do not specify a value.

#1: Because HTTP server requests use [CR]+[LF] as delimit characters, specify CRLF.

#2: In the promptPattern property of the first to fourth terminal command plug-ins, you can specify regular expression patterns that also match blank characters.

#3: Because standard output continues after you execute the terminal command plug-ins, specify a regular expression that detects the end of standard output by the terminal command plug-ins in the promptPattern property.

The following describes the operation of a plug-in with the above properties when it encounters the following standard output.

[Figure]

Because the contents of standard output match the value specified in the promptPattern property, the terminal command plug-in determines the return code.

If standard output matches the value specified in the returnCodePattern property, the return code specified in the returnCode property is returned as the return code of the plug-in.

If standard output does not match the value specified in the returnCodePattern property, the plug-in returns the return code specified in the defaultReturnCode property.

To Page Top