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

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 "Remote command (cmd)"

    "params":{
        "host":"execution-host-name",
        "cmd":"execution-command",
        "envFile":"environment-variable-file"
    }

When action type is "REST API (restapi)"

    "params":{
        "method":"method-of-REST-API",
        "url":"URL-of-REST-API",
        "headers":"request-header-for-REST-API",
        "body":"request-body-of-REST-API"
    }

When action type is "Updating event status (eventstatus)"

    "params":{
        "dealt":event-status,
        "eventSid":"SID-of-JP1-event,..."
    }

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	Specify the 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	Specify the 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	Specify the 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.

Member name

Data type

Optional

Description

actionType

string

Specify the 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

Specify the 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

Specify the 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	Specify the execution host name. Specify no more than 255 bytes. Otherwise, it is error.
cmd	string	No	Specify the OS command and parameters 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	Specify 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	Specify the 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	Specify the header of REST API to execute. Specify no more than 65,536 bytes. Otherwise, it is error.
body	string	Yes	Specify 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	Specify the 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	Specify the 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.

Member name

Data type

Optional

Description

dealt

string

Specify the value of event status. You can specify value as follows: Otherwise, it is error.

0:Unprocessed
1:Processed
2:Processing
3:Hold

eventSid

string

Specify the 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.)
500	KAJY64001-E	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.

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.

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//"
}

To Page Top