5.13.2 Response action suggestion

Description

Compares the suggestion definitions against the suggestion activation criteria and suggests response actions appropriate to the system status, according to the specified IM management node or suggestion ID.

Execution permissions

JP1_Console_Admin
JP1_Console_Operator
JP1_Console_User

API version

Format

Request line

POST /application/component/apivVersion/nodes/suggestions/suggest httpVersion

Request message body

{
    "sid": tree-SID-of-IM-management-node,
    "suggestionIds": list-of-suggestion-IDs
}

Response message body

{
    "suggestions":[
        {
            "suggestionId": suggestion-ID,
            "label": display-name-of-suggestion,
            "status": whether-suggestion-activation-criteria-are-satisfied,
            "cases":[
                [
                    {
                        "description": description-of-criterion,
                        "status": status-of-criterion,
                        "acquisitionDate": acquisition-date-and-time,
                    },
                    ...
                ],
                [
                    {
                        "description": description-of-criterion,
                        "status": status-of-criterion,
                        "acquisitionDate": acquisition-date-and-time,
                    },
                ...
            ],
            "action": {
                    "type": type-of-response-action,
                    "params": parameters-of-response-action,
                    "description": description-of-response-action
                      }
            "messageList":[
                {
                    "messageId": message-ID,
                    "message": message-text
                },
                ...
            ]
        },
        ...
    ]
}

Parameters

sid

Specify the tree SID of an IM management node.

suggestionIds

Specify a list of suggestion IDs. You can specify a list of 1 to 1,000 suggestion IDs. If you specify an empty list, the error message KAJY22019-E is output, and the response action suggestion processing stops.

When this parameter is omitted, only those suggestion definitions mapped to the specified IM management node that the logged-in user is allowed to view are compared against the suggestion activation criteria to judge if they satisfy the criteria, and information regarding the suggested response actions that are appropriate to the system status is subsequently acquired.

When the specified suggestion IDs correspond to either those suggestions definitions that are not mapped to the tree SID of the specified IM management node or those which the logged-in user is not allowed to view, the error message KAJY22021-E is output, and the acquisition of response action suggestion information stops.

Status codes

The following table describes the status codes that may be returned as a response to the request:

Status code	Message	Description
`200`	None	Response actions were successfully suggested.
	`KAJY22026-W`	Failed to convert the variables in the suggestion definitions.
	`KAJY22027-W`	Suggestion information obtained by the conversion of variables in the suggestion definitions is invalid.
	`KAJY22028-W`	Failed to make a judgment as to whether the suggestion activation criteria are satisfied.
	`KAJY22047-W`	Failed to acquire information from the Repeated event list window.
`400`	`KAJY22020-E`	The request of the REST API is invalid. The possible causes are: invalid format of the tree SID of the IM management node, invalid suggestion IDs, invalid number of lists of suggestion IDs, etc.
	`KAJY22022-E`	The request of the REST API is invalid. There are duplicate suggestion IDs.
	`KAJY22011-E`	Either the specified tree SID does not exist or the logged-in user does not have the permission to view the specified IM management node.
	`KAJY22021-E`	The specified suggestion IDs correspond to either those suggestions that are not mapped to the specified IM management node or those which the logged-in user is not allowed to view.
`403`	`KAJY01000-E`	The logged-in user does not have the permission to execute the REST API.

When the status code is 200, the following information is returned in the response body:

No.	Member name				Data type	Description
1	`suggestions`				object[]	Returns the acquired suggestion information as an array. When there are no suggestion definitions that are mapped to the tree SID of the specified IM management node, or when the logged-in user is allowed to view none of the suggestion definitions mapped to the tree SID of the specified IM management node, an empty array is returned.
2		`suggestionId`			string	Sets the suggestion ID.
3		`label`			string	Sets the display name of the suggestion.
4		`status`			int	Indicates whether the suggestion activation criterion was satisfied. One of the following values are returned: `0`: Criterion satisfied `1`: Criterion not satisfied `2`: Error
5		`cases`			object[][]	Returns double-array data of suggestion criteria objects. The inner array represents a group of AND conditions whereas the outer array represents a group of OR conditions. This member is not returned when the `cases` member is not specified in the suggestion definitions.
6			`description`		string	Returns the description of the criterion after conversion of the variables.
7			`status`		int	The status of a criterion. One of the following values is returned: `0`: Not judged `1`: Match `2`: Does not match `3`: Error
8			`acquisitionDate`		string	Returns the date and time when criterion information was acquired, as UTC time in ISO 8601 format. When `status` (status of criterion) is `0` (Not judged) or `3` (Error), an empty string is returned.
9		`action`			object	Information regarding a response action is returned.
10			`type`		string	The type of response action specified in the suggestion definition is returned. For details on the `type` member, see (2) Response action in Suggestion definition file in Chapter 2. Definition Files.
11			`params`		object	When `jump` is specified as `type` of the response action and at the same time `relatedEvent` is also specified, `relatedEvent` and members no. 12 to 15 are returned. In all the other cases, the parameters of the response action specified in the suggestion definition are returned with their variables converted. For details on the members other than members no. 12 to 15, see (2) Response action in Suggestion definition file in Chapter 2. Definition Files.
12				`suppressId`	int	The value of the `E.JP1_IMSUPPRESS_ID` attribute (suppressed event ID) of the JP1 event specified with `relatedEvent`^#
13				`eventSevere`	int	The value of the `E.@JP1IM_SEVERE` attribute (severe event) of the JP1 event specified with `relatedEvent`^#
14				`suppressName`	string	The value of the `E.JP1_IMSUPPRESS_NAME` attribute (repeated event condition name) of the JP1 event specified with `relatedEvent`^#
15				`nodeSid`	string	The tree SID of the IM management node to which the JP1 event specified with `relatedEvent`^# belongs
16			`description`		string	When `status` (whether the suggestion activation criterion was satisfied) is `0` (criterion satisfied): Returns the description of response action with the variables converted. When `status` is other than `0`: Returns the description of response action without the variables being converted. If the returned string exceeds 512 characters, it is truncated to 512 characters.
17		`messageList`			object[]	Returns the warning message issued during processing that does not prevent the processing from continuing. This member is not returned when there is no warning message that does not prevent the processing from continuing.
18			`messageId`		string	Returns a message ID.
19			`message`		string	Returns message text.

#: For details on relatedEvent, see information regarding relatedEvent provided in (2)(A)(e) Response action when type is set to jump in Suggestion definition file in Chapter 2. Definition Files.

Examples

The following example shows how response actions are suggested for the IM management node (tree SID: _ROOT_AllSystems/_HOST_HOST1/_CATEGORY_platform/_SUBCATEGORY_JP1%2FPFM%20-%20Windows/_OBJECT_JP1PFM-ATA1HOST2) that belongs to the service provided by the PFM agent that constitutes a management object.

Request:

POST http://hostname:20703/im/api/v1/nodes/suggestions/suggest
{
"sid":"_ROOT_AllSystems/_HOST_HOST1/_CATEGORY_platform/_SUBCATEGORY_JP1%2FPFM%20-%20Windows/_OBJECT_JP1PFM-ATA1HOST2"
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "suggestions":[
        {
            "suggestionId":"check_affected_rootJobnet",
            "label":"Impact on root jobnets affected by host going down",
            "status":0,
            "cases":[
                [
                    {
                         "description":"A JP1/AJS - Agent node exists on the same host where the selected node (PFM - Agent) exists",
                         "status":1,
                         "acquisitionDate":"2020-03-11T11:00:00Z"
                    },
                    {
                         "description":"A JP1 event indicating that the host stopped has been issued",
                        "status":1,
                         "acquisitionDate":"2020-03-11T11:00:01Z"
                    },
                    {
                         "description":"The host of the selected node is down",
                         "status":1,
                         "acquisitionDate":"2020-03-11T11:00:02Z"
                    }
                ]
            ],
            "action":
                {
                    "type":"jump",
                    "params":
                        {
                            " url":"index?sid=%5FROOT%5FAllSystems%2F%5FHOST%5FHOST1%2F%5FCATEGORY%5FmanagementApplications%2F%5FOBJECT%5FJP1AJSAGT&view=tree&tab=relation&eou=1"
                        },
                    "description":"Move to the Related node tab displaying the JP1/AJS - Agent node"
                }
        }
    ]
}

To Page Top