Hitachi

JP1 Version 13 JP1/Integrated Management 3 - Manager Command, Definition File and API Reference

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) ...
  ]
}

To Page Top

Copyright (C) 2023, 2024 Hitachi, Ltd.

Copyright (C) 2023, 2024 Hitachi Solutions, Ltd.