5.16.1 Obtain execution result of Response Action
- Description
-
Gets the execution result of Response Action.
If you set the search criteria to a parameter, you retrieve the execution result of Response Action that match the search criteria.
- Execution permissions
-
Following permissions are required:
When only one key "execDetailEventSid" is specified in the filter:
-
JP1 permission level: JP1_Console_Admin, JP1_Console_Operator, JP1_Console_User
In other cases:
-
JP1 resource group: *
-
JP1 permission level: JP1_Console_Admin, JP1_Console_Operator, JP1_Console_User
-
- API version
-
v1
- Format
-
- Request line
POST /application/component/apiVersion/responseActions/results httpVersion
- Request message body
{ "type":"Process content", "direction":"ResponseAction execution result acquisition direction", "searchType":Search type, "count":Acquired number of ResponseAction execution results, "since":"Search start position action SID", "lastDirection":"Search direction for response action results specified in the previous search process" "dbInfo":[ { "beginData":"Search start position action SID", "endData":"Search end position action SID", "since":"Action SID for the search start position specified in the previous search process" } ] "filter":[ //ResponseAction result search filters {"key":"Search key","ope":"Compare keyword","val":["operand 1",...]}, ... ] }
- Response message body
{ "actionResult":[ //ResponseAction result { "actionSid":"ResponseAction SID", "executionHost":"Destination host Name", "actionName":"Action name", "executionCommand":"Command", "actionStatus":"Action status", "targetSid":"Execute target SID", "executionDeal":"Execute trigger", "executionDetailInfo":"Execute trigger detailed Information", "actionType":"Action type", "actionAcceptTime":"ResponseAction reception time", "actionSendTime":"ResponseAction input time", "actionEndTime":"ResponseAction end time", "executionResult":["Execute result"], "returnValue":"Return value", "message":["Message"] }, ... ], "beginData":"ResponseAction execution result search start position ResponseAction result information", "endData":"ResponseAction result information of the search end position of the ResponseAction execution result", "dbInfo":"Next search information for the execution result of ResponseAction for distribution DB", "messageList":[ { "messageId":"Message ID", "message":"Message" }, ... ] }
- Parameters
-
Here are the parameters that you specify for message body of the request:
Member name
Data type
Optional
Description
type
string
No
Specifies the execution result of the ResponseAction to retrieve.
-
list
Get a list of ResponseAction findings
-
detail
Get ResponseAction result detail info
If a value other than the above is specified, error is returned.
direction
string
Yes
Specify the search direction for ResponseAction execution results.
-
past
Search in the past direction
-
future
Search for future directions
The default is "past".
If a value other than the above is specified, Error is returned.
searchType
int
No
Specify the search type.
-
0: Action SID specification
Specify the target SID for since and 1 for count.
-
1: Latest page
-
2: New page
-
3: Update
-
4: Old page
-
5: Oldest page
If you specify anything other than the above, an error will occur.
count
int
Yes
Specify a range from 1 to 2,000 for the maximum number of results of ResponseAction execution that can be acquired.
The default is 100.
If a value other than the above is specified, Error is returned.
since
string
Yes
Specify the search start position of the ResponseAction execution result with the corrective action SID.
It is specified as a character string of less than 1024 bytes. Otherwise, it is Error.
Search for past or future ResponseAction execution results from the specified action SID (The ResponseAction execution result of the specified ResponseAction SID is not included in the search target.
However, if count is 1, the specified action SID is searched.)
If omitted, the search starts from the beginning or end of the ResponseAction result management database according to the specified direction.
For setting method, see ■About setting method for since and direction for retrieval target below.
lastDirection
string
Yes
Specifies the search direction for response action results specified in the previous search procces.
Specify "past" for the past direction and "future" for the future direction.
Required if searchType is 2 or 4.
If you specify anything other than the above, an error will occur.
dbInfo
object[]
Yes
ResponseAction is an Execute control for ResponseAction that specifies the starting and ending position for ResponseAction results-management database search.
It can be omitted when searching from the beginning (Latest) for the first time.
From the next time onwards, specify the content of dbInfo returned in the previous return Value.
For setting method, see ■About setting method for since and direction for retrieval target below.
beginData
string
Yes
Specifies the ResponseAction SID of the search start position for the ResponseAction execution result.
It is specified as a character string of less than 1024 bytes. Otherwise, it is Error.
endData
string
Yes
Specifies the ResponseAction SID of the search end position for the ResponseAction execution result.
It is specified as a character string of less than 1024 bytes. Otherwise, it is Error.
since
string
Yes
The action SID of the search start position when the previous search type was 1, 2, 4, 5.
Set it to less than 1024 bytes. Otherwise, an error will occur.
filter
object[]
Yes
An object that specifies the filter for obtaining the execution result of ResponseAction.
For details, see ■About ResponseAction result search filter below.
■About setting method for since and direction for retrieval target
Object of acquisition
searchType
since
direction
Additional setting
Latest (First time)
1
Empty character (can be omitted)
past
None
Oldest
5
Empty character (can be omitted)
future
None
Transition to a new page
2
Setup the most recent (last in the array sequence) actionSid from actionResult of the previous search response.
future
dbInfo is mandatory.
lastDirection is mandatory.
Transitions to one old page
4
Setup the oldest (first in the array sequence) actionSid from actionResult of the previous search response.
past
dbInfo is mandatory.
lastDirection is mandatory.
Update (Refresh)
3
Setup value that was the same as since of the last search.
Setup value that was the same as direction of the last search.
dbInfo is mandatory.
lastDirection can be omitted.
Get detailed Information by ResponseAction SID specification
0
Setup ResponseAction SID you want to retrieve.
past/future
Set count to 1 and set "detail" to type.
lastDirection can be omitted.
Note: If the above configuration file content is invalid, correct results may not be obtained. If so, execute again from Latest page-first retrieval.
■About ResponseAction result search filter
This section explains how to specify parameters.
{ "key":"Search key","ope":"Comparison keyword","val":["operand 1","operand 2",...] }
Table 5‒14: Combinations of attribute name and compare keywords that can be specified Search key
(Value to setup)
Data type
Comparison
keywords
Operand
ResponseAction SID
(actionSid)
string
-
Full match
(MATCH)
-
Regular expression
(REGEX)
Specify ResponseAction SID.
You can specify a maximum of 100 items in the range of 1 to 4096 bytes. Otherwise, it is Error.
If you specify a regular expression, you cannot specify more than one. If more than one value is specified, error is set.
Destination host name
(executionHost)
string
-
Full match
(MATCH)
-
Regular expression
(REGEX)
Specifies host name that execute ResponseAction.
You can specify a maximum of 100 items in the range of 1 to 4096 bytes. Otherwise, it is error.
If you specify a regular expression, you cannot specify more than one. If more than one value is specified, error is returned.
Action status
(actionStatus)
string
-
Full match
(MATCH)
Specifies status of ResponseAction. You can specify more than one.
The following values can be specified:
-
send (Execution destination sending)
-
queue (Queuing)
-
running (Execution in progress)
-
ended (Exit)
-
unknown (Status unknown)
-
none (None)
-
fail (Fail)
-
senderror (Communication failure)
-
error (Execution failure)
If a value other than the above is specified, error is returned.
Action name
(actionName)
string
-
Full match
(MATCH)
-
Regular expression
(REGEX)
Specifies action name of ResponseAction.
You can specify a maximum of 100 items in the range of 1 to 4096 bytes. Otherwise, it is error.
You can specify any character other than the control character (0x00 to 0x1F,0x7F to 0x9F).
If you specify a regular expression, you cannot specify more than one. If more than one value is specified, Error is returned.
Execution trigger detailed information
--
--
Specifies execution trigger for ResponseAction.
For auto ResponseAction, for JP1 event SID, manual ResponseAction, specify JP1 user name who requested the manual execution.
JP1 Events. SID (execDetailEventSid)
string
-
Full Match
(MATCH)
Specifies SID of JP1 events.
You can specify a maximum of 100 items in the range of 1 to 4096 bytes. Otherwise, it is error.
JP1 user name (execDetailUserName)
string
-
Full match
(MATCH)
-
Regular expression
(REGEX)
Specify JP1 user name.
You can specify a maximum of 100 items in the range of 1 to 4096 bytes. Otherwise, it is error.
If you specify a regular expression, you cannot specify more than one. If more than one value is specified, error is returned.
ResponseAction reception time
(actionAcceptTime)
string
-
Date/time specification
(TRANGE)
Specifies the time when ResponseAction execution control received a ResponseAction execution request.
The input format is the extended form of ISO 8601 (YYYY-MM-DDThh:mm:ssTZD), otherwise it is error. Specify the starting date/time, and then the ending date/time.
If you do not enter a starting date/time, retrieve all date/time data prior to the ending date/time.
If you do not enter an exit date/time, retrieve all of the later date/time from the starting date/time.
Return value
(returnValue)
string
-
Full match
(MATCH)
-
Regular expression
(REGEX)
Execute specifies the return value of the finding.
You can specify a maximum of 100 items in the range of 1 to 4096 bytes. Otherwise, it is error.
If you specify a regular expression, you cannot specify more than one. If more than one value is specified, Error is returned.
■About regular expressions
The following regular expressions are used in ResponseAction result finding filter:
-
For Windows: Extended regular expressions (XPG4 compliant)
-
For Linux: Extended Regular Expressions (POSIX1003.2)
-
- Status codes
-
The following table describes the status codes that are returned as a response to the request:
Status code
Message
Description
200
--
--
200
KAJY63041-W
Some execution results cannot be obtained because communication with the ResponseAction execution control, which is the destination for obtaining ResponseAction execution results, cannot be established.
200
KAJY63042-W
An error is returned from the ResponseAction execution control at the ResponseAction execution result acquisition destination, and some execution results cannot be obtained.
400
KAJY63302-E
REST API parameter was specified incorrectly.
<Cause>
-
A parameter that cannot be omitted is omitted.
-
You set a value that cannot be set
-
Character limit exceeded
-
The maximum number of items that can be specified is exceeded.
-
Duplicate search key
400
KAJY63303-E
JSON formatting of the request message body is invalid.
403
KAJY01000-E
You do not have permission to execute REST API.
500
KAJY63040-E
Execute destination cannot be obtained from the system configuration information. (There is no management node for the execution request destination host in the system configuration.)
Execute destination could not be obtained from the system configuration information. (The integrated agent management base that manages the execution request destination host could not be obtained.)
500
KAJY63039-E
The system configuration information is not accessible.
500
KAJY63333-E
An unexpected error occurred in REST API processing.
500
KAJY00007-E
System error has occurred (out of disk, out of memory, etc.).
-
- Return values
-
-
When the status code is 200
Returns the data shown in the following tables to message body of the response.
The returned information differs depending on the value specified in the request parameter type.
Member name
Data type
Value of type
Description
list
detail
actionResult
object[]
Y
Y
ResponseAction result object. The members returned depend on value specified in type of request parameters.
actionSid
string
Y
Y
Returns ResponseAction SID.
executionHost
string
Y
Y
Returns the destination host.
-
When action type is "cmd"
Host name of the execution destination integrated JP1/IM agent control base
-
When action type is not "cmd"
ResponseAction execute control host name
actionName
string
Y
Y
Returns action name.
executionCommand
object
Y
Y
Returns the execution command. The object to be returned depends on action type.
-
When Action type is "cmd"
See ■When action type is "cmd" table below.
-
When action type is "restapi"
See ■When action type is "restapi" table below.
-
When action type is "eventstatus"
See ■When action type is "eventstatus" table below.
actionStatus
string
Y
Y
Returns status of ResponseAction.
targetSid
string
Y
Y
Returns the configuration SID of the system (JP1/IM agent control base, or JP1/IM - Manager) that execute ResponseAction.
executionDeal
string
Y
Y
Returns the timing when ResponseAction is executed.
executionDetailInfo
string
Y
Y
Returns detailed information at the time ResponseAction was executed.
-
For auto ResponseAction (JP1 event trigger)
JP1 Events SID
-
For manual ResponseAction
JP1 user name that made the execution request
actionType
string
Y
Y
Returns type of ResponseAction to be executed.
Value to be returned is shown below.
-
cmd
-
restapi
-
eventstatus
actionAcceptTime
string
Y
Y
Returns the time when the ResponseAction execution control accepted the ResponseAction execution request.
actionSendTime
string
Y
Y
Returns the time when the ResponseAction execution control sent the ResponseAction execution request.
actionEndTime
string
Y
Y
Returns the time when the execution of the ResponseAction is completed.
executionResult
string[]
N
Y
Returns a execution result.
-
When action type is "cmd"
Command standard output and standard error output
-
When action type is "restapi"
REST API response body
-
When action type is "eventstatus"
Return object of event handling status change method
returnValue
string
Y
Y
Returns the return value of the execution result.
-
When action type is "cmd"
Command-return value
-
When action type is "restapi"
REST API status code
-
When action type is "eventstatus"
The value is 0 if the event handling status change was successful, and 1 if it failed.
message
string[]
N
Y
This is message output by ResponseAction execution control.
beginData
string
Y
Y
Returns the ResponseAction SID next to the search start position of the ResponseAction execution result.
Omit if there is no ResponseAction SID after the search start position.
endData
string
Y
Y
Returns the ResponseAction SID next to the search end position of the ResponseAction execution result.
Omit if there is no ResponseAction SID after the search end position.
dbInfo
object[]
Y
Y
This is an object that returns the search start and end positions of the distributed DB response action results.
beginData
string
Y
Y
Returns the ResponseAction SID of the search start position of the ResponseAction execution result. Omit if there is no search target ResponseAction execution result.
endData
string
Y
Y
Returns the ResponseAction SID of the search end position of the ResponseAction execution result. Omit if there is no search target ResponseAction execution result.
since
string
Y
Y
Returns the action SID of the search start position when 1,2,4,5 was specified as the previous search type.
messageList
object[]
Y
Y
Only returned if there is a continuable warning message that occurred in processing.
messsageId
string
Y
Y
Returns message ID.
message
string
Y
Y
Returns message.
Legend
Y: The information of the applicable member is returned.
N: The information on the applicable member is not returned
■When action type is "cmd"
Member name
Data type
Description
cmd
string
Returns the command name.
envFile
string
Returns environment-variable file name and pass.
■When action type is "restapi"
Member name
Data type
Description
method
string
Returns REST API method.
url
string
Returns URL of REST API.
headers
object
Returns REST API request headers.
body
string
Returns REST API request body. Omit the request body if it is not needed.
■When action type is "eventstatus"
Member name
Data type
Description
dealt
string
Returns event status.
eventSid
string
Returns SID of JP1 events.
-
-
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.
When a warning has occurred, a warning information similar to the one with status code 200 is added to the item "extensions" (extended information) and returned to the requestor.
-
- Examples
-
- Request:
-
The following is an example of how to use the API to set search conditions as parameters and acquire information in the ResponseAction result list.
POST http://hostname:20703/im/api/v1/responseActions/results HTTP/1.1 content-type: application/json ... (omitted) ... { "type":"list", "direction":"past", "searchType":1, "count":100, "filter":[ {"key":"actionStatus","ope":"MATCH","val":["running","ended"]}, {"key":"executionHost","ope":"MATCH","val":["HOST185"]}, {"key":"actionAcceptTime","ope":"TRANGE","val":["2023-10-25T12:00:00+09:00", "2023-10-30T12:00:00+09:00"]} ] }
- Response:
HTTP/1.1 200 content-type: application/json ... (omitted) ... { "actionResult":[ { "actionSid":"_JP1IMACTID_20f916e2-10d7/_JP1IMMHOST_HOST185//", "executionHost": "HOST185", "actionName": "act002", "actionType": "eventstatus", "executionCommand": { "dealt": 3, "eventSid":"_JP1IM_HOST185/_JP1IMSEQNO_8/_JP1IMEVBSEQNO_401" }, "actionStatus": "ended", "targetSid": "_JP1IM_HOST185/_HOST_HOST185", "executionDeal": "manual", "executionDetailInfo": "jp1admin", "actionAcceptTime": "2023-10-27T15:26:50+09:00", "actionSendTime": "2023-10-27T15:26:50+09:00", "actionEndTime": "2023-10-27T15:26:50+09:00", "returnValue": "0", "executionResult": null, "message": null }, ... (omitted) ... ], "beginData":"", "endData":"_JP1IMACTID_25e566fa-c54a/_JP1IMMHOST_HOST185//", "dbInfo":[ {"beginData":"_JP1IMACTID_d9947fe1-23a5/_JP1IMMHOST_HOST185//", "endData":"_JP1IMACTID_20f916e2-10d7/_JP1IMMHOST_HOST185//", "since":"", }, ... (omitted) ... ] }