4.2.1 General command plug-in
Function
This plug-in enables a specified command to be executed on the operation target device.
If you have pre-set authentication information in the Connection Destinations view, you can execute commands by specifying the following information in the general command plug-in:
-
The device on which to execute the command (destinationHost property)
-
Command to be executed (commandLine property)
-
Command arguments (commandLineParameter property)
For the command to be executed on the operation target device, specify characters that can be used in commands in the operating systems of the JP1/AO server and the operation target device. For example, if the JP1/AO server and the operation target device both run the Japanese version of Windows, characters in the MS932 character set can be specified.
If the operation target device is running Windows, the command is executed by the user account set in the authentication information. If the operation target device is running UNIX, the command is executed with root user privileges or the privileges of the connection user, depending on the value of the elevatePrivileges property. The following execution directory is used at command execution:
-
When the connection destination is running Windows: Admin$\Hitachi\CMALib\JP1AO\home
Admin$ is the directory specified in the windir environment variable.
-
When the connection destination is running UNIX and true is specified for the elevatePrivileges property: The home directory of the root user
-
When the connection destination is running UNIX and false is specified for the elevatePrivileges property: The home directory of the connection user
For details about how version 01.50.00 of the plug-in differs from previous versions, see A.1 Functional differences between basic plug-ins by version.
Prerequisites for execution
-
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.
-
Certain commands must be installed on the operating system of the operation target device before you use the general command plug-in. For details, see the release notes.
-
To use the general command plug-in when the operation target device is running Windows, administrative sharing must be enabled. For details, see the Job Management Partner 1/Automatic Operation Overview and System Design Guide.
Cautionary notes
-
The locale and character set at the time of execution depend on the OS of the operation target device. For details, see Locale set for operation target devices during plug-in execution and Character set used for communication by JP1/AO during plug-in execution in the Job Management Partner 1/Automatic Operation Service Template Development Guide.
-
If the execution of a task is stopped while the plug-in is executing, the status of the task becomes Failed or Completed when the processing of the general command plug-in finishes. 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 a Subsequent-step Execution Condition in the Create Step dialog box or the Edit Step dialog box.
-
If you forcibly terminate a task while the plug-in is executing, the process tree being executed on the operation target device is immediately forcibly terminated and the status of the task becomes Failed or Completed. A return code of -1 appears for the step in the Task Details dialog box. The return code output to the task log depends on the timing with which the task was forcibly terminated.
-
When you forcibly terminate a task while the plug-in is executing, the execution results of the command or script specified in the commandLine property are outside the scope of product support.
-
The execution method differs depending on the OS of the operation target device. The command is executed by WMI in Windows, and SSH in UNIX. Therefore, the SSH server must be set up on UNIX-based operation target devices.
-
The port number used by SSH can be set in connection-destination property file (connection-destination-name.properties) or the property file (config_user.properties).
-
When the operation target device is running Windows, user profiles are not inherited. This means a plug-in can produce different execution results from a command or script executed on the desktop.
To avoid this issue, do not reference settings in user profiles, such as user environment variables, registry entries, and Internet Explorer settings, when executing a plug-in. If a command or script references an element of a user profile, the command or script might not behave as expected. For example, when you execute a command or script that references Internet Explorer proxy settings, the command or script might fail with a communication error. This might occur in scenarios such as implementing a Windows Update using a script.
-
If the operation target device is running UNIX, and you need to specify non-ASCII characters in the commandLine or commandLineParameter property, see A.5 Prerequisites for executing command lines containing non-ASCII characters in UNIX.
Version
01.50.00
Category
Hitachi/Basic
Return codes
Return code |
Description |
---|---|
-1 |
The task was forcibly terminated while the plug-in was executing. -1 appears as the return code of the step in the Task Details dialog box. |
0 to 63 |
The return code (0 to 63) of the command or script is returned as the return code of the plug-in. The meaning of the command or script depends on the command or script. |
64 |
If the return code of the specified command or script is 64 or higher, 64 is returned as the return code of 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:
|
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 failed. |
71 |
Command execution failed. |
72 |
The execution status of the command could not be acquired. |
76 |
The connection timed out. |
77 |
The host name of the operation target device could not be resolved. |
78 |
Authentication with the operation target device failed for one of the following reasons:
|
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. |
127 |
Another error has occurred. |
Property list
The following table describes the properties.
Property key |
Property name |
Description |
Default value |
I/O type |
Required |
---|---|---|---|---|---|
destinationHost |
Destination Host |
Specify the IPv4 address, IPv6 address, or host name of the operation target device. The host name should be within 1,024 characters. The JP1/AO server and the operation target device must be connected by a network. Note that multiple IP addresses or host names cannot be specified. |
-- |
Input |
R |
credentialType |
Credentials Type |
As the authentication type to use during command or script execution, specify either of the following:
|
-- |
Input |
R |
account |
User ID |
Specify the user ID to use to log in to the operation target device, using a maximum of 256 characters. You can also specify a domain user in either of the following formats:
|
-- |
Input |
O |
password |
Password |
Specify the password to use to log in to the operation target device, using a maximum of 256 characters. You can omit this property when the operation target device is running UNIX and true is specified for the publicKeyAuthentication property. |
-- |
Input |
O |
suPassword |
Root Password |
If the OS of the operation target device is UNIX, specify the root password using a maximum of 256 characters. If the OS is Windows, this property does not need to be specified. You can also omit this property when the operation target device is running Windows, or when false is specified for the elevatePrivileges property. |
-- |
Input |
O |
publicKeyAuthentication |
SSH public key authentication setting |
If the OS of the operation target device is UNIX, specify either of the following depending on whether you want to use public key authentication. The values are not case sensitive. If you do not specify a value, false is assumed. You can omit this property when the operation target device is running Windows.
|
false |
Input |
O |
elevatePrivileges |
Elevate Privileges |
If the OS of the operation target device is UNIX, specify either of the following depending on whether you want to elevate the user to root privileges. The values are not case sensitive. If you do not specify a value, true is assumed. You can omit this property when the operation target device is running Windows.
|
false |
Input |
O |
commandLine # |
Command Line |
Specify the absolute path of the command or script to be executed on the operation target device, using a maximum of 256 characters. In the command line, specify characters that can be entered in command lines 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. The command or script is executed subject to the privileges of the following user:
|
-- |
Input |
R |
commandLineParameter # |
Command-line Parameters |
Specify the arguments of the command or script using a maximum of 1,024 characters. As the command line parameters, specify characters that can be entered in command lines in the OSs 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. You can also specify an environment variable as the value of a command line parameter. The specification format depends on the OS of the operation target device.
|
-- |
Input |
O |
stdoutProperty1 |
Standard Output Property 1 |
The character string extracted by the stdoutPattern1 property is output to this property. |
-- |
Output |
O |
stdoutPattern1 |
Standard Output Pattern 1 |
Specify the regular expression pattern of the standard output to output to the stdoutProperty1 property, using a maximum of 1,024 characters. Specify the regular expression pattern in a PCRE-compliant format. If you specify the key of a service property in the stdoutProperty1 property but do not specify the stdoutPattern1 property, the entire standard output and standard error output of the command or script specified in the commandLine property is assigned to the service property. |
-- |
Input |
O |
stdoutProperty2 |
Standard Output Property 2 |
The character string extracted by the stdoutPattern2 property is output to this property. |
-- |
Output |
O |
stdoutPattern2 |
Standard Output Pattern 2 |
Specify the regular expression pattern of the standard output to output to the stdoutProperty2 property, using a maximum of 1,024 characters. Specify the regular expression pattern in a PCRE-compliant format. If you specify the key of a service property in the stdoutProperty2 property but do not specify the stdoutPattern2 property, the entire standard output and standard error output of the command or script specified in the commandLine property is assigned to the service property. |
-- |
Input |
O |
stdoutProperty3 |
Standard Output Property 3 |
The character string extracted by the stdoutPattern3 property is output to this property. |
-- |
Output |
O |
stdoutPattern3 |
Standard Output Pattern 3 |
Specify the regular expression pattern of the standard output to output to the stdoutProperty3 property, using a maximum of 1,024 characters. Specify the regular expression pattern in a PCRE-compliant format. If you specify the key of a service property in the stdoutProperty3 property but do not specify the stdoutPattern3 property, the entire standard output and standard error output of the command or script specified in the commandLine property is assigned to the service property. |
-- |
Input |
O |
- #
-
-
The standard output or standard error output of the commands or scripts specified in these properties are output as the standard output of the step in JP1/AO. However, processing for which the total standard output and standard error output of the command or script exceeds 100 KB is outside the scope of product support. Execute the command or script in advance to make sure that the total standard output and standard error output does not exceed 100 KB.
-
If the operation target device is running Windows, the content specified in the commandLine and commandLineParameter properties are made into a batch file and executed on the operation target device. Therefore, the result of this action might differ from the result if the same command and script were executed from the command prompt.
-
If the operation target device is running UNIX, linefeed codes in standard output and standard error output are changed as follows:
-
CR(0x0d) is changed to LF(0x0a).
-
CR+LF(0x0d0a) is changed to LF+LF(0x0a0a).
In addition, if the character string at the end of the standard output and standard error output is not a linefeed code (CR, LF, or CR+LF), LF(0x0a) is added to the end.
-
-
Usage example of stdoutPattern and stdoutProperty properties
By using the stdoutPattern property, you can extract the value output to standard output and store it in the stdoutProperty property. The following figure shows the data flow when specifying aaabbb(.*) in stdoutPattern1.
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.
Specifying the SSH port number
You can specify a port number when using SSH to connect to the operation target device. The following table describes how to specify the port number and the priority of each method.
Priority |
Set in |
Property key |
Default value |
---|---|---|---|
1 |
Connection-destination property file (connection-destination-name.properties) |
ssh.port |
-- |
2 |
Property file (config_user.properties) |
ssh.port.number |
22 |
- Legend:
-
--: No value is set.
Related topics
-
Prerequisites for connection destinations in the Job Management Partner 1/Automatic Operation Overview and System Design Guide
-
Properties file (config_user.properties) and Connection-destination property file (connection-destination-name.properties) in the Job Management Partner 1/Automatic Operation Configuration Guide