4.5.13 jp1EmService.getEvent

This method retrieves events related to an IM management node from the integrated monitoring database. Specifically, a list of events matching the conditions specified by the parameters is retrieved.

If the JP1 user who specified this method does not have the permission to view the events in question, the user cannot retrieve them. In this case, no error message is output.

The range of events that can be retrieved depends on the JP1 resource group settings and the event receiver filter settings in JP1/IM - Manager. For details about the conditions under which a user may be able to view certain events, see information regarding the events that can be displayed in the event view when an IM management node is selected in 3.2.1 Structure of the IM management node in the JP1/Integrated Management 2 - Manager Overview and System Design Guide.

This method cannot be called from the __eventGet method provided by product plug-ins or from the method called by the __eventGet method.

The details of the jp1EmService.getEvent method are provided below.

Method name

Object jp1EmService.getEvent(String sid, Object filter, String direction, String since, int count, String[] attrs, int[] statusFilter, boolean consolidateEvent, int searchCount, String lang, String jp1User, String jp1Token)

Parameters

sid

Specify the tree SID of an IM management node. A list of events issued by the specified IM management node is retrieved.

If you specify null or an empty string, it is assumed that all systems (_ROOT_AllSystems) are specified. If you specify null or an empty string without any IM management nodes having been set up, an empty list of events is returned.

filter

Specify an event search condition object.

This method searches the integrated monitoring database for events that meet the specified event search conditions. For details about the event search condition object, see 7.2.1 (3) Event search condition object. If you specify a single-byte space as any of the attribute values, it is assumed that %20 is specified.

You can narrow down the events specified with sid to those that meet the event search conditions specified with filter. If you do not need to narrow down the retrieved events, specify null for filter.

When there is no pass-conditions group that contains both an event search condition in which key is set to B.TIME (registered time) and ope is set to TRANGE (time) and an event search condition in which key is set to B.ARRIVEDTIME (arrived time) and ope is set to TRANGE (time)^#, it is assumed that one of the pass-conditions groups is specified as follows:

{"key":"B.TIME","ope":"TRANGE","val":["1-day-before-current-time","current-time"]}

#: This includes specifying null for filter.

In an event search condition in which key is set to B.ID (event ID), the digits of the value specified for val are automatically padded with zeros.

direction

Specify the direction in which to search for events.

Specify past to search for events that occurred before the specified event and future to search for events that occurred after the specified event. If you specify null or an empty string, it is assumed that past is specified.

since

Specify the SID of the JP1 event that serves as a starting point for the event search. The method searches for events that occurred either before or after the JP1 event corresponding to the specified SID. Note that the JP1 event corresponding to the specified SID is not included in the search. If you specify null or an empty string, the integrated monitoring database is searched from either the beginning or end depending on the setting specified for direction. For details about the SIDs of JP1 events, see 7.2.1 (1) Event information object.

count

Specify the maximum number of events to be retrieved in the range from 1 to 2,000.

attrs

Specify an array of event attributes to be retrieved.

Example:

"attrs":["B.ID","B.MESSAGE",...]

The attributes specified for attrs are retrieved in user-specified order. When null is specified, attributes are acquired differently depending on the type of JP1 events specified.

• When consolidation start events are specified

  All the attribute values that can be output by the event report output function are retrieved first. Afterwards, the attributes listed in the table under Event attributes of the consolidation start event in 7.2.1 (1) Event information object are retrieved.

• When events other than consolidation start events are specified

  All the attribute values that can be output by the event report output function are retrieved. The specifiable event attributes include all the attributes that can be output by the event report output function and the attributes listed in the table under Event attributes of the consolidation start event in 7.2.1 (1) Event information object.

For details about the event report output function, see 4.15.2 Saving event information in the integrated monitoring database (CSV report) in the JP1/Integrated Management 2 - Manager Overview and System Design Guide.

statusFilter

To narrow down the events to those whose nodes match the specified status, specify status values by using the int array.

Example: To retrieve only those events whose node status is 30 and 40

"statusFilter":[30,40]

For details about the node status codes, see 5.8.3 IM management node status acquisition. If you do not need to narrow down events, specify null.

consolidateEvent

When repeated events have been consolidated on the Intelligent Integrated Management Base, specify whether you want the consolidated repeated events to be returned. To prevent repeated events from being returned, specify true.

• true

  When the display of repeated events is suppressed on the Intelligent Integrated Management Base, only the consolidation start events are returned. Repeated events that come after each consolidation start event are not returned.

• false

  Repeated events are returned regardless of whether the display of repeated events is suppressed on the Intelligent Integrated Management Base.

searchCount

Specify the maximum number of times a search for events can be repeated in the range from 0 to 120,000.

A total of 100 events mapped to the IM management node specified by the sid parameter are searched through, starting from the event specified by the since parameter and proceeding in the direction specified by the direction parameter.

When the number of events specified by the count parameter cannot be retrieved due to an event receiver filter or other restrictions, the search is repeated, that is, the next 100 events are searched through. The maximum number of times the search for events can be repeated is what you need to specify for this parameter.

When the specified maximum limit is reached, the search is discontinued, and a list of all events retrieved before the discontinuation of the search is output along with the KAJY32010-W message. If you specify nothing or 0 for this parameter, there is no limit to the number of times a search can be repeated.

lang

Specify the language of the message. You can specify ja, ja-JP, or en. If you specify any other values, it is assumed that en is specified. For details, see Language conventions of user-created plug-ins in 4.4 Methods implemented in the plug-in.

jp1User

By using a string of 1 to 31 bytes, specify the name of a JP1 user who has one of the following JP1 permission levels. Only the events that the specified JP1 user has the permission to view are retrieved.

• JP1_Console_Admin

• JP1_Console_Operator

• JP1_Console_User

jp1Token

Specify a JP1 authentication token for the JP1 user specified for jp1User.

Return values

After successful retrieval of events, an object storing event information is returned. The following table describes the keys and their values stored in the object after successful retrieval of events:

No.	Key	Value
1	eventData	Returns an array of event information objects that represents a list of retrieved events. For details about event information objects, see 7.2.1 (1) Event information object. When there is no event to be returned, a zero-length array is returned.
2	messageId	Returns the message ID of a temporary error message generated during an event search. Either KAJY32005-W or KAJY32010-W is returned. When there is no message to be provided, null is specified. For details about messages, see the manual JP1/Integrated Management 2 - Manager Messages.
3	message	Returns the body of a temporary error message generated during an event search. When there is no message to be provided, null is specified.
4	beginSid	Returns the SID of a JP1 event that is right next to (that is, immediately before or after, depending on the specified direction of event search) the event that has been specified by the since parameter as the starting point for the event search. When there are no JP1 events to be searched for, this key is omitted.
5	endSid	Returns the SID of the JP1 event located at the end position of the event search. When the event search is discontinued, the SID of the JP1 event where the search was discontinued is returned. When there are no JP1 events to be searched for, this key is omitted.

The following table describes the keys and their values stored in the object after a failed attempt to retrieve events:

No.	Key	Value
1	errorMessage	An error message. When any of the arguments are invalid, the KAJY22043-E error message is set. If this method is executed while the JP1/IM2 - Manager service is stopped, the KAJY32000-E message is set. For details about the error messages set in all the other cases, see the table under Status codes in 5.6.1 Event search.
2	errorMessageId	Returns the ID of the error message.

In methods of a product plug-in that calls this method, consider error messages and error processing based on the specifications of the plug-in, according to the value of the key errorMessageId.

Output the key errorMessage to the internal log of the product plug-in for use in troubleshooting it.

Exception

None

To Page Top