[ Bottom of Page | Previous Page | Next Page | Contents | Index ]

Filters

Filters define the criteria that must be satisfied by an event before a rule is run. If the evaluation of a filter fails, the rule is skipped. The properties tested in a filter must be those defined for the class of the event. There are three types of filters:

• Event filter
• Change rule filter
• Timer rule filter

Event filters

An event filter tests event class names and optionally tests attribute values of the event under analysis. If the event passes the event filter criteria, the rule is run. Event filters can also be used in rule actions to test for related events in the event cache, in which case if the event in the cache is found, subsequent predicates within the action are run.

You can use variables in an event filter that defines the conditions that must be met for triggering a rule. These variables can be used to instantiate the event class name or attribute values of the event under analysis for use later in the rule. The scope of a variable instantiated in this event filter is the rest of the rule in which the variable is instantiated.

You can also use variables in an event filter that is used with a predicate in a rule action to accomplish the same goal for the referenced event in the predicate. These variables have a scope that is limited to the current rule action, which means they can be accessed only by other predicates that are called within the same action.

An event filter usually begins with a variable that is instantiated with a pointer to the event under analysis. For this variable, the recommended naming convention is _event, although you can use any variable name. The event pointer variable is required for event filters of all rule types except for simple and correlation rules. You cannot specify it in simple and correlation rules.

The of_class operator follows the _event variable and is required for event filters of all rule types except simple or correlation rules. You cannot specify it in simple or correlation rules. The of_class operator signifies that an event class specification follows.

The event class specification tests the class of the event under analysis to see if the rule applies to that event class. The following list describes variations of a class specification and shows examples of each:

_

The _ variable (a single underscore character), also referred to as the anonymous variable, is instantiated with the name of the event class of the event under analysis. This variable means that you won't be retrieving the name of the event class for use later in the rule. The following example event filter succeeds for every event of every event class and instantiates the name of the event class to the anonymous variable:

event: _event of_class _ 

_class

The _class variable is instantiated with the name of the event class of the event under analysis. The following example event filter succeeds for every event of every event class and instantiates the _class variable with the name of the event class:

event: _event of_class _class 

class_name

This is the explicit name of an event class. The following filter succeeds if the event under analysis is of the Printer_Error_Cleared event class.

event: _event of_class 'Printer_Error_Cleared'

Note:

If class_name is a superclass of the event under analysis, the class specification part of the filter succeeds for all events that are subclasses of class_name. If the fire_on_non_leaf compiler directive is enabled, the class specification part of the filter also succeeds if class_name is a superclass (also referred to as a non-leaf node).

_class within [class_name1,...]

This class specification tests for one or more event classes in a list. If the event under analysis is a member of the list, the class specification part of the filter succeeds.

If any of the event class names in the list is a superclass, the class specification part of the filter succeeds for all events that are subclasses of the superclass.

If the fire_on_non_leaf directive is enabled, the class specification part of the filter also succeeds if event class is a superclass.

The list can either be specified as a variable that has been previously defined, or an explict list of class names. For lists, the brackets are required and event class names must be separated by a comma. The following filter succeeds if the event under analysis is one of those within the list and is an example of specifying an explicit list within the rule:

event: _event of_class 
    within ['Printer_Paper_Out',
            'Printer_Toner_Low',
            'Printer_Offline',
            'Printer_Output_Full',
            'Printer_Paper_Jam',
            'Printer_Door_Open'
    ]

Note:

You can optionally use the _class variable to capture the event class name for use later in the rule. For example, an event filter can look like the following example. If the event under analysis is one of those in the list, the _class variable is instantiated with the event class name.

event: _event of_class _class
    within ['Printer_Paper_Out',
            'Printer_Toner_Low',
            'Printer_Offline',
            'Printer_Output_Full',
            'Printer_Paper_Jam',
            'Printer_Door_Open'
    ]

The following example shows the use of a variable in place of a literal LIST_OF value:

;Class file

TEC_CLASS:
     Logfile_Base ISA EVENT
     DEFINES {
        alist: LIST_OF STRING, default=['Printer_Paper_Out',
                                        'Printer_Toner_Low',
                                        'Printer_Offline'];
     };
END

;Rules file
print_reset:
   ( event: _event of_class 'Printer_Error_Cleared'
     where [   status: equals 'OPEN',
              alist: _aclasslist     ],

reception_action:
    ( first_instance( event: _prt_ev of_class
           within _aclasslist
           where [ status: outside ['CLOSED'] ],
          _event - 3600 - 3600),
    change_event_status(_prt_ev, 'CLOSED') ) 
).

_class outside [class_name1, ...]

This class specification tests for one or more event classes in the form of a list. The brackets are required and event class names must be separated by a comma. If the event under analysis is a member of the list, the class specification part of the filter does not succeed. If any of the event class names in the list is a superclass, the class specification part of the filter does not succeed for all events that are subclasses of the superclass. If the fire_on_non_leaf compiler directive is enabled, the class specification part of the filter also does not succeed if the event class is a superclass. The following filter does not succeed if the event under analysis is one of those within the list:

event: _event of_class 
    outside ['Printer_Paper_Out',
             'Printer_Toner_Low',
             'Printer_Offline',
             'Printer_Output_Full',
             'Printer_Paper_Jam',
             'Printer_Door_Open'
    ]

Note:

You can optionally use the _class variable as described in the _class within specification.

Attribute conditions

You can optionally further restrict the criteria of an event filter with attribute conditions. Attribute conditions are the where clause of an event filter. Attribute conditions let you optionally specify tests that must be satisfied by certain attribute values of the event under analysis. You can also instantiate variables with attribute values in the attribute conditions section. This lets you use those variables later in the rule--similar to the _class variable in an event filter.

The event under analysis must have passed the class specification part of the event filter first, before the attribute conditions are tested. If the event passes both the class specification and attribute conditions of the event filter, the rule is run.

Attribute conditions can take the following general forms. The where clause begins with the where keyword and an open bracket. It ends with a closed bracket. The entire event filter, including the where clause, ends with a comma. If you don't specify any attribute conditions, you must still create an empty where clause.

• Test an attribute's value. The following operators are valid for testing an attribute's value:

  comparison_operator

  Compares an attribute's value to a certain value. Valid operators are:

  • equals
  • greater_than
  • greater_or_equals
  • smaller_than
  • smaller_or_equals
  • within
  • outside

  The within operator tests whether an attribute value is equal to one of the values in a list, while the outside operator tests whether an attribute value is equal to a value not in the list.

  The following example tests whether the value of the status attribute is OPEN. OPEN is delimited by single quotation marks because it begins with an uppercase letter and would be interpreted by the rule compiler as a variable if it was not enclosed in single quotation marks.

  where [status: equals 'OPEN'],

  The following example tests whether the value of the status attribute is either OPEN or ACK and instantiates the _status variable with the value:

  where [status: _status within ['OPEN','ACK']],

  The following example tests whether the value of the status attribute is anything other than CLOSED:

  where [status: outside ['CLOSED']]

  Note:
  Ensure that you use the appropriate operator for the data type to test.
• Simple instantiation of a variable with an attribute's value. The following example simply instantiates the _status variable with the value of the status attribute. There is no testing of the status attribute's value.

  where [status: _status],

• A combination of both preceding forms. The following example tests for events that are not closed and are of a critical severity. If the event passes those tests, the _hostname variable is instantiated with the name of the host where the event occurred.

  where [
    status: _status outside ['CLOSED'],
    severity: equals 'CRITICAL',
    hostname: _hostname
  ],

Change rule filters

You can have the following two additional filters in change rules:

• Sender filter
• Attribute change filter

Sender filter

A sender filter of a change rule lets you filter on the sender of a change request. Senders of change requests can be one of the following:

agent

An event adapter.

engine

The rule engine.

operator(name)

An administrator from an event console.

The valid operators for a sender filter are:

equals

Tests whether the sender is a specific value. The following example tests whether the sender is the rule engine:

sender: equals engine,

The following example tests whether the sender is an operator. This example also instantiates a new variable, _sender, which can be used in a subsequent action. (The _x variable is not available outside the filter.)

sender: _sender equals operator(_x),

outside

Tests whether the sender is not equal to one of the values in a list. The following example tests whether the sender is an administrator:

sender: outside [agent,engine],

within

Tests whether the sender is equal to one of the values in a list. The following example tests whether the sender is member of a set of administrators, and if so, instantiates the _sender variable with the value:

sender: _sender within                    [operator('root@orange'),
                    operator('root@red'),
                    operator('root@blue')
                    ],

You can also use a sender filter to simply instantiate a variable with the value of the sender, as shown in the following example:

sender: _sender,

Attribute change filter

An attribute change filter of a change rule lets you filter on the requested change to an attribute value of an event.

The only required operator for an attribute change filter is set_to. The operand on the left side of the set_to operator is the name of the attribute to test. The operand on the right side of the set_to operator is the value specified in the requested change, or a comparison to the requested change. The operand on the right side of the set_to operator can be a single value or a list specification. For a list specification, a variable must be used to hold the value of the requested change.

The following operators are valid for comparisons in an attribute change filter:

• equals
• greater_than
• greater_or_equals
• smaller_than
• smaller_or_equals
• within
• outside

The within operator tests whether an attribute value is equal to one of the values in a list, while the outside operator tests whether an attribute value is equal to a value not in the list.

The following examples show various attribute change filters:

• The following attribute filter succeeds if the status attribute was changed to CLOSED:

  attribute: status set_to 'CLOSED',

  Note:
  The slot keyword for an attribute change filter was used in earlier releases of the IBM Tivoli Enterprise Console product. The attribute keyword is now used. Although the slot keyword is still valid, it might be removed in a future release.
• The following attribute filter succeeds if the status attribute was changed to any value. The _newstatus variable is instantiated with the value in the requested change.

  attribute: status set_to _newstatus,

• The following attribute filter succeeds if the status attribute was changed to ACK or CLOSED. The _newstatus variable is instantiated with the value in the requested change.

  attribute: status set_to _newstatus within ['ACK','CLOSED'],

• The following attribute filter succeeds if the repeat_count attribute was changed to a value greater than 5. The _newrepeatcount variable is instantiated with the value in the requested change.

  attribute: repeat_count set_to _newrepeatcount greater_than 5,

• The following attribute filter succeeds if the administrator attribute was changed to fred, wilma, or betty. The _newadministrator variable is instantiated with the value in the requested change.

  attribute: administrator set_to _newadministrator 
    within ['fred','wilma','betty'],

Timer rule filters

You can have the following two additional filters in timer rules:

• timer_info filter
• timer_duration filter

timer_info filter

A timer_info filter of a timer rule lets you filter on the timer information specified with the timer_info argument of the set_timer predicate. The set_timer predicate is used to set a timer on an incoming event. The timer_info argument of the set_timer predicate can be any value, such as an integer, string, or a structured item (such as a list).

The following operators are valid for comparisons in a timer_info filter:

• equals
• greater_than
• greater_or_equals
• smaller_than
• smaller_or_equals
• within
• outside

The within operator tests whether an attribute value is equal to one of the values in a list, while the outside operator tests whether an attribute value is equal to a value not in the list.

The following examples show various timer_info filters:

• The following timer_info filter succeeds if the timer information was specified as Level 1:

  timer_info: equals 'Level 1',

• The following timer_info filter succeeds if the timer information was specified as either Level 1 or Level 2. The _timerinfo variable is instantiated with the value of the timer information.

  timer_info: _timerinfo within ['Level 1','Level 2'],

• The following timer_info filter simply instantiates the _timerinfo variable with the timer information:

  timer_info: _timerinfo,

timer_duration filter

A timer_duration filter of a timer rule lets you filter on the value specified for the timer_duration argument of the set_timer predicate. The set_timer predicate is used to set a timer on an incoming event. The timer_duration argument of the set_timer predicate is an integer value representing the number of seconds for the duration of the timer.

The following operators are valid for comparisons in a timer_duration filter:

• equals
• greater_than
• greater_or_equals
• smaller_than
• smaller_or_equals
• within
• outside

The within operator tests whether an attribute value is equal to one of the values in a list, while the outside operator tests whether an attribute value is equal to a value not in the list.

The following examples show various timer_duration filters:

• The following timer_duration filter succeeds if the timer was specified to last 60 seconds:

  timer_duration: equals 60,

• The following timer_duration filter succeeds if the timer was specified to last either 60 or 90 seconds. The _timerduration variable is instantiated with the value of the timer duration.

  timer_duration: _timerduration within ['60','90'],

• The following timer_duration filter simply instantiates the _timerduration variable with the timer duration:

  timer_duration: _timerduration,

[ Top of Page | Previous Page | Next Page | Contents | Index ]