Hitachi

JP1 Version 12 JP1/Automatic Operation Service Template Reference


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

Cautionary notes

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 stdoutPattern1property 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

[Figure]

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

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

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.