5.16.2 Manual execution of Response Action
- Description
-
Operate responseAction(manual).
You can execute the following action type "commands:
-
Execution of commands
-
Execution of REST API
-
Updating event status
-
- Execution permissions
-
-
JP1_Console_Admin
-
JP1_Console_Operator
-
- API version
-
v1
- Format
-
- Request line
POST /application/component/apiVersion/responseActions/manualExec httpVersion
- Request message body
{ "actionType":"Action type", "actionName":"Name of ResponseAction", "params":{"Parameters of ResponseAction"} }
Parameters of ResponseAction
-
When action type is set to "Remote command(cmd)"
"params":{ "host":"Execute Host name", "cmd":"Command", "envFile":" Environment variable file" }
-
When action type is "REST API (restapi)"
"params":{ "method":"REST API methods", "url":"URL of REST API", "headers":"REST API request header", "body":"REST API request body" }
-
When action type is "Event status updating (eventstatus)"
"params":{ "dealt":Event status, "eventSid":"JP1 Events SID,..." }
-
- Response message body
{ "actionSid":" ResponseAction SID", "warning":[ { "messageId":"Message ID when a warning occurs", "message":"Message when a warning occurs" }, : ] }
- Parameters
-
Here are the parameters that you specify for message body of the request:
Member name
Data type
Optional
Description
actionType
string
No
Specifies type of ResponseAction.
One of the following value can be specified: If any other value is specified, error is returned.
-
cmd
Execute remote command.
-
restapi
Execute REST API
-
eventstatus
Execute updating event status of an event.
actionName
string
Yes
Specifies name of ResponseAction.
The following value can be specified: If any other value is specified, error is returned.
-
1 to 50 bytes.
-
All characters except the control character "ASCII code 0x00 to 0x1F,0x7F to 0x9F".
params
object
No
Specifies ResponseAction content.
The parameters that you specify depend on type of ResponseAction.
-
For cmd
See For remote command (cmd) table below.
-
For restapi
See For REST API(restapi) table below.
-
For eventstatus
See For updating event status (eventstatus) table below.
-
For remote command (cmd)
Member name
Data type
Optional
Description
host
string
No
Specifies execute destination host name. Specify no more than 255 bytes. Otherwise, it is error.
cmd
string
No
Execute specifies OS command/parameter to be used. Specify no more than 4096 bytes. Otherwise, it is error.
envFile
string
Yes
Specify the absolute path of the file on the execution host that contains the environment variables to be read during command execution. Specify 255 bytes or less. Otherwise, it is error.
-
For REST API(restapi)
Member name
Data type
Optional
Description
method
string
No
Specifies the method of REST API to execute. You can specify the following methods: Otherwise, it is error.
-
GET
-
HEAD
-
POST
-
PUT
-
PATCH
-
DELETE
-
OPTIONS
-
TRACE
url
string
No
Specifies URL of REST API to execute. The following value can be specified: Otherwise, it is error.
-
Specify 2046 bytes or less.
-
The characters that can be used are one-byte alphanumeric characters and the following symbols according to RFC2396.
";", "/", "?", ":", "@", "&", "=", "+", "$", ",", "-", "_", ".", "!", "~", "*", "'", "(", ")", "%"
-
Specify "http://" or "https://" at the beginning.
headers
object
No
Specifies the header of REST API to execute. Specify no more than 65,536 bytes. Otherwise, it is error.
body
string
Yes
Specifies the body of REST API to execute. If you do not need a body, omit it. When specifying, specify a value less than 10MB. Otherwise, it is error.
-
-
For updating event status (eventstatus)
Member name
Data type
Optional
Description
dealt
string
No
Specifies value of event status. You can specify value as follows: Otherwise, it is error.
-
0:Unprocessed
-
1:Processed
-
2:Processing
-
3:Hold
eventSid
string
No
Specifies SID of JP1 events. If you specify more than one event SID, concatenate the event SID with ",".
You can specify up to 2,000 items. After that, it is error.
The number of bytes must be less than 1MB. After that, it is error.
-
-
- Status codes
-
The following table describes the status codes that are returned as a response to the request:
Status code
Message
Description
200
--
--
400
KAJY64004-E
The content of execute requirement of ResponseAction is invalid.
<Cause>
-
You are setting a value that cannot be set
-
Exceeded character limit
-
A parameter that cannot be omitted is omitted.
400
KAJY63321-E
JSON formatting of the request message body is invalid.
403
KAJY01000-E
You do not have execute permission for REST API.
500
KAJY63333-E
An unexpected error occurred in REST API processing.
500
KAJY64003-E
A error was returned from the destination ResponseAction execute control.
<Cause>
Execute of ResponseAction failed
500
KAJY64001-E
Execute destination cannot be obtained from the system configuration information. (There is no managed node of execute requesting host in the system configuration.)
Execute destination could not be obtained from the system configuration information. (JP1/IM agent management base managing execute requesting host could not be obtained.)
500
KAJY64000-E
The system configuration information is not accessible.
500
KAJY64002-E
Communication with the destination ResponseAction execute control is not possible.
<Cause>
-
Failed to communicate with ResponseAction execute control
500
KAJY00007-E
System error has occurred (out of disk, out of memory, etc.).
■About Warnings
If the acquisition of information from the non-executable action data table fails, the following message ID is output. The output destination is the warning object of the response when normal, and the warning object of extended information (extensions) when an error occurs.
Message ID
Description
KAJY63309-W
Cannot communicate with the response action result manage DB.
<Cause>
-
Failed to connect the DB.
KAJY63310-W
Write error occurred at the response action result manage DB.
<Cause>
-
Failed to operate reading DB.
-
- Return values
-
-
When the status code is 200
If warning information is added to the response returned from the action execution request API, the warning information shown in the following table is added to this REST API response and returned to the request source.
For the information to be returned, see ■About Warnings above.
Member name
Data type
Description
actionSid
string
Returns a unique ResponseAction SID within ResponseAction results-management DB.
warning
object[]
Object of the warning message.
messageId
string
Returns message ID of the warning that occurred.
message
string
Returns message of the warning that occurred.
-
When the status code is other than 200
In message body of the response, the exception object in the response format described in 5.2.6 Error response message when an Error occurs is returned. However, "returnCode" items are omitted.
If warning information has been added to the response returned from execute request API of ResponseAction, the warning information shown in the following table is added to the "extensions" (extended information) field of message body of the response during error and returned to the request source.
Member name
Data type
Description
extensions
object[]
An object of extended information.
Set the warning information that occurred.
messageId
string
Returns message ID of the warning that occurred.
message
string
Returns message of the warning that occurred.
-
- Examples
-
- Request:
-
-
The following shows an example of using API when the command is executed.
POST http://hostname:20703/im/api/v1/responseActions/manualExec HTTP/1.1 content-type: application/json ... (omitted) ... { "actionType":"cmd", "actionName":"act001", "params":{ "host":"HOST185", "cmd":"dir" } }
-
Here is an example of using API to execute a REST API using JP1 event-information:
POST http://hostname:20703/im/api/v1/responseActions/manualExec HTTP/1.1 content-type: application/json ... (omitted) ... { "actionType":"restapi", "actionName":"act001", "params":{ "method":"GET", "url":"http://hostname:20703/im/api/version", "headers":"{}" } }
-
The following is an example of using API to change event status of an event to processed.
POST http://hostname:20703/im/api/v1/responseActions/manualExec HTTP/1.1 content-type: application/json ... (omitted) ... { "actionType":"eventstatus", "actionName":"act001", "params": { "dealt":1, "eventSid":"_JP1IM_HOST185/_JP1IMSEQNO_8/_JP1IMEVBSEQNO_401" } }
-
- Response:
HTTP/1.1 200 OK content-type: application/json ... { "actionSid": "_JP1IMACTID_cb82bd6d-6409/_JP1IMMHOST_HOST185//" }