NetIQ Documentation: Operations Center 5.5 Event Manager Guide - Defining and Editing Rulesets

7.4.1 Understanding the Ruleset Editor

The Ruleset Editor directly supports building rulesets and processing raw text.

The following topics provide an overview of using the Ruelset Editor tool:

Understanding the Ruleset Editor’s Views

The Ruleset Editor consists of a left pane and two tabular views: Properties and Alarm.

Figure 7-1 Event Manager Ruleset Editor

The following lists the Ruleset Editor panes:

Rules Hierarchy: A hierarchy tree displays parent and child rules defined for the current ruleset. Select a rule. The data in panes to the right update to reflect the properties for the currently selected rule. This pane displays when either the Properties or Alarm tab displays.
Variables: A list of reserved system variables and user-defined variables used for parsing and filtering incoming events. System variables display in bold typeface. This pane displays when either the Properties or Alarm tab displays.
Raw Data: Displays the contents of a selected imported text file. This pane is part of the Properties tab.
Rule Matching: Statements that identify specific text strings to match in the incoming data. Incoming lines that contain matching text strings are then processed by statements in the Rule Parsing pane. This pane is part of the Properties tab.
Rule Parsing: Statements that specify the rules for parsing and storing text from incoming event data in variables defined for the ruleset. This pane is part of the Properties tab.
Rule Logic: Statements that evaluate variable values for the incoming events and define actions to perform based on these values. This pane is part of the Properties tab.

Understanding How the Ruleset Editor Processes Incoming Text

In the simplest scenario, the following actions occur when the Ruleset Editor processes incoming event data:

A selected rule applies to an event message received by the Event Manager.
If the message contains text that matches the statements in the Rule Matching pane, it is parsed into variables specified in the Rule Parsing pane.
Statements in the Rule Logic pane process the parsed variables.
Alarm properties specified in the Alarm tab of the Ruleset Editor apply to the event.

Alarms are sent to the Alarm Server and subsequently to the Operations Center Event Manager adapter.

7.4.2 Creating Rules within a Ruleset

The following steps explain the general process of defining new rules within a ruleset. Subsequent sections explain the details.

The general steps for defining new rules within a ruleset are:

In the Rules Hierarchy pane, identify the location of the new rule in the hierarchy, then add the rule.

For more information, see Understanding Rule Inheritance and Event Processing.
In the Rules Hierarchy pane, define the rule name and description.

The name can contain spaces, periods, underscores and dashes.

For more information, see Adding Rules.
In the Variables pane, define variables that will store some of the parsed incoming raw text.

For more information, see Section 7.4.4, Defining and Editing Variables.
Load sample event data to facilitate the creation and testing of rules.

For more information, see Section 7.4.5, Loading Sample Data.
In the Rule Matching pane, identify the text strings to look for in the incoming lines of raw text. Lines with matching text strings are selected for further processing by statements in the Rule Parsing pane.

For more information, see Section 7.4.6, Editing the Rule Matching Pane.
In the Rule Parsing pane, define statements that parse the incoming event data into variable values.

For more information, see Section 7.4.7, Editing the Rule Parsing Pane.
Define statements in the Rule Logic pane. Define statements that evaluate the variable values and perform actions based on these values.

For more information, see Section 7.4.8, Editing the Rule Logic Pane.
In the Alarm tab, define alarm properties for events that match all conditions of the selected rule in the Rules Hierarchy pane.

The Alarm tab defines the alarms that display in the Operations Center console.

For more information, see Section 7.4.9, Configuring Alarms.
Test rules using sample data.

After defining a new rule, use the Raw Data pane to test the rule and make adjustments before putting it into production.

For more information, see Section 7.4.10, Testing Rulesets Using Sample Data.

7.4.3 Creating and Managing Rules

The rule hierarchy is designed to process events efficiently. The following sections cover aspects of rule inheritance and event processing, as well as outline steps for adding rules, deleting rules, moving rules, and setting a default rule.

Understanding Rule Inheritance and Event Processing

Typically, multiple parents and child level rules process an incoming event. The processing occurs through a branch of the rule tree structure.

If an event successfully matches a parent rule, then all rules that are children of the parent rule process the event.

Each rule can contain one or more statements in the Rule Matching pane. If an incoming event matches all the statements in the Rule Matching pane, additional processing occurs:

The Rule Parsing pane extracts specific characters in the raw text as named variables

See Section 7.4.7, Editing the Rule Parsing Pane.
Statements in the Rule Logic pane evaluate the variable values and perform actions based on these values
An alarm is generated, unless a rule in the Rule Logic pane specifies a No Fire action

If an event fails to match a parent rule, parsing and screening do not occur and none of the child rules apply.

Processing from the top-level parent through the lowest-level child stops when one of the following conditions is met:

Rule processing reaches the lowest level in the rule branch
The incoming data fails to match a statement the Rule Matching pane
A rule in the Rule Logic pane specifies not to convert an event to an alarm (a No Fire action)

Adding Rules

Define parent and child rules using the tree structure in the Rules Hierarchy pane. Child rules display indented beneath their parents.

Figure 7-2 illustrates parent and child rules in the hierarchy tree:

Figure 7-2 Ruleset Editor

Adding Child Rules

To add a child rule to an existing rule:

Select a rule in the Rules Hierarchy pane.
To open the Create New Rule dialog box, do one of the following:
- Click (Add).
- Right-click a rule, then select Create Rule.
In the Create New Rule dialog box, specify a name and a description for the new rule:

A rule name can consist of any combination of alphanumeric and underscore, space and dash characters, between 1 and 40 characters.

If a rule name that exceeds 37 characters is pasted, the rule name is truncated at 37 characters.

If this rule name is not unique, additional characters are appended until a unique rule name (40 characters or fewer) is created.

The default line count is 1, but can be a number between 1 and 999. The line count is the number of lines in an incoming event.
Click OK.

The new rule displays as a child of the currently selected rule. It displays beneath all other child rules in the branch.

It is possible to move the rule (see Moving Rules) elsewhere within the same branch.

Adding Rules at the Same Level

To add rules at the same level:

Select a rule in the Rules Hierarchy pane.
Click (Insert Before) or (Insert After) to open the Create New Rule dialog box.
Specify the Rule Name, Description and Line Count.
Click OK.

The new rule displays before or after the currently selected rule, at the same level.

Copy, Pasting and Renaming Rules

It is possible to create new rules from existing rules. Copy and paste an existing rule, then modify it using the Properties and Alarm tabs.

Copying and Pasting a Rule

To copy and paste a rule in the Ruleset Editor:

Right-click a rule in the Rules Hierarchy pane, then select Copy.
To paste the rule as a child of another rule, right-click a rule, then select Paste as Child.

A copy of the original rule displays as a child of the selected rule.

Pasting at the Same Level of a Rule

To paste a rule at the same level as another rule in the Ruleset Editor:

Right-click a rule, then select Paste as Sibling.

A copy of the original rule displays as a sibling of the selected rule.

Renaming a Rule

To rename a rule in the Ruleset Editor:

Right-click the rule, then select Rename Rule.
Specify the new name.

Editing a Rule Properties

To edit a rule’s description and line count:

Right-click a rule, then select Properties to open the Edit Rule Properties dialog box.

Edit the description and line count.
Click OK to save changes.

Deleting Rules

To delete a rule in the Ruleset Editor:

Do one of the following:
- Select a rule in the Rules Hierarchy pane, then click (Delete).
- Right-click a rule, then select Delete Rule.
  
  This option works only for rules with no children.

Moving Rules

It is possible to change the order that rules display within a branch in the Rules Hierarchy pane.

Understanding Moving Rules

A rule can move only within its current branch. At the top level, a parent rule (and all its children) can move above or below other rules at the same level.

In the following example, Rule_1_1, Rule_1_2 and Rule_1_3 can move within the branch. For example, Rule_1_2 can move above Rule_1_1 or below Rule_1_3. However, none of the rules can move beyond its parent, Rule_1.

At the top level of this example, only Rule_2 and Rule_3 can move. For example, Rule_2 can move above Rule_1 or move below Rule_3. Although Rule_1 cannot move, changing the order of Rule_2 and Rule_3 could cause this to happen inadvertently.

Figure 7-3 illustrates reordering rules within a branch:

Figure 7-3 Ruleset Editor

Moving a Rule

To move a rule in the Ruleset Editor:

Select a rule, then click (Up or Down) to move the rule.

Only rules with no children can move.

Defining and Applying a Default Rule

Use the default rule to handle unexpected events. Apply it to an event after all the other rules in a ruleset fail to identify a match.

Understanding Default Rules

The default rule must be at the top level of the rule hierarchy; it has no parent and no children.

A greyed out option means the rule cannot be the default rule. The rule has children or is not at the top level of the rule hierarchy.

Figure 7-4 Ruleset Editor: Rule Right-Click Menu

When selected, the rule name changes to include the text: (Default). The rule moves to the bottom of the rule hierarchy. It is not possible to add new rules after it, or to move existing rules move beneath it.

Figure 7-5 Ruleset Editor: The default rule is identified.

Defining a Default Rule

To define a default rule:

Right-click a rule, then select Set as Default Rule.

Changing a Default Rule

To change the default rule:

Right-click a rule, then select Set as Default Rule to open the following dialog box:
Click Yes to confirm the change.

Searching for a Rule

When many rules display in the Rules Hierarchy pane, use the Search feature to locate a rule quickly.

To search for a rule:

Click (Search) to open the Find Rule dialog box.
Enter search criteria for finding a rule in the Rules Hierarchy pane. In the following dialog box, enter the search string:

Do the following in this dialog box as necessary:
- To search the entire hierarchy from the top, select the Search from Root check box.
  
  To search the current branch starting from the selected rule, deselect the check box.
  
  The search includes the current level and lower levels for the current branch only.
- To conduct a case-sensitive search, select the Match Case check box.
  
  To search using any combination of uppercase and lowercase text strings, deselect the check box.
Click Find to begin the search.

The first rule containing a matching string is selected. If necessary, the search automatically expands the rule hierarchy tree to locate a matching rule.
Continue clicking Find to locate additional matches.

A message displays when there are no more matches.
Click Close to end the search.

7.4.4 Defining and Editing Variables

The Variables pane contains a list of reserved system variables and user-defined variables used to parse and screen incoming events. Variables can consist of text or numbers. System variables display in bold typeface. Variables display in alphabetical order; user-defined variables display first, followed by system variables.

Figure 7-6 Variables Pane

The following topics describe how to add and maintain variables:

Understanding the System Variables for the Ruleset Editor

Table 7-1 lists all system variables currently defined in the Ruleset Editor:

Table 7-1 Variables

Variable	Definition	Values
#PRI	Priority of the alarm.	1–99; 1 is the highest priority (Default = 50)
#SEV	Severity of the alarm.	1 = Critical 2 = Major 3 = Minor 4 = Informational (Default) 5 = OK
#TIMEOUT	The time interval (number of minutes) after which an alarm closes automatically.	0–32767 minutes
CLASS	The class assigned to the agent from which the event was received.	N/A
DATE	The date that the event was received.	Format is: mm/dd/yyyy, Where: mm (month) is between 01 and 12 dd (day) is between 01 and 31 yyyy (year) is the current year
DATETIME	The date and time that the event was received. When intending to use the Alarm data to set event date/time, be sure that the usedatetime custom properties are set correctly. See Section 3.4.3, Custom Properties Related to Alarm Server Functions.	Format is: yyyy‑mm‑dd hh:MM:ss Where: yyyy is the current year mm (month) is between 01 and 12 dd (day) is between 01 and 31 hh (hour) is between 00 and 23 MM (minute) is between 00 and 59 ss (second) is between 00 and 59
DAY	The day of the week that the event was received.	Format is: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, and Saturday
EMS	The agent from which the event was received.	N/A
TOD	The time of day that the event message was received.	Format is: hh:mm Where: hh (hour) can be between 00 and 23 mm (minute)can be between 00 and 59

Reserved Words

The following are reserved words and cannot be used when defining variables:

id
severity
date
accum
is_assigned
escalated_up
escalated_down
class
can_escalate
can_delay
can_threshold
can_accumulate
can_discard
can_timeout
ems
ems_class
initdate
assignedto
enrouteto
text
priority
rule
group
circuit
segment
object
hrlt3
hrlt4
hrlt5

Adding Variables

To add a variable in the Ruleset Editor:

Click (Add) in the Variables pane to open the Create New Variable dialog box:
Specify a name for the new variable.

Variable names must consist of alphanumeric characters (no `spaces) between 1 and 40 characters in length.
Click the Variable Type drop-down list, then select a variable type: String, Long, Short, or Float.
Click OK.

The new variable displays in the pane in alphabetical order.

Editing Variables

The name of a user-defined variable cannot change. Instead, delete the variable and add a new one. It is also not possible to edit the name or type of a system-defined variable. However, it is possible to change the type of a user-defined variable.

To change the type of a user-defined variable:

In the Variables pane, click the Type drop-down list next to the variable name, then select one of the following variable types:

String: Any text string.

Long: Any signed 32‑bit decimal (‑2147483647 to +2147483647).

Short: Any signed 16‑bit decimal (‑32767 to +32767).

Float: Any valid IEEE 754 32‑bit floating point number (3.40282347e+38f to 1.40239846e‑45f).

Deleting Variables

It is not possible to delete some system variables. The Delete button is dimmed after selecting these variables.

To delete a variable:

In the Variables pane, select the variable, then click (Delete).

A dialog box opens to confirm the deletion.
Click Yes to delete the variable.

7.4.5 Loading Sample Data

Load sample event data to facilitate the creation and testing of rules. When defining rules, select text and identify start and stop columns using the sample event data.

The (Test) button located in the Raw Data pane tests the current ruleset using the sample event data. Both of these features are explained later in Section 7.4.10, Testing Rulesets Using Sample Data.

Loading a Text File Containing Sample Data

To load a text file that contains sample data:

In the Raw Data pane, click (Open).
Browse and select a data file.

The file content displays in the Raw Data pane:

This text is read-only.
Do any of the following:
- Use the vertical scroll bar to view additional rows of sample data.
- Use the horizontal scroll bar to view additional data on a line.

Copying Raw Data to Other Panes

To minimize data entry errors, copy text strings and the start and end column numbers from the sample raw data to fill in cells in the Rule Matching, Rule Parsing, and Rule Logic panes.

To copy the raw data:

Click and drag to select information in the Raw Data pane.
Confirm the selection by checking the status bar of the Raw Data pane, which displays the selected start, text, and end columns:
In the Rule Matching, Rule Parsing, or Rule Logic pane, select the cell to paste the information.
Click the (lightning bolt icon) next to the cell to paste the information.

7.4.6 Editing the Rule Matching Pane

Statements in the Rule Matching pane evaluate specific sections of the incoming data for string matches. String matches are based on user-defined text strings and the start and end columns of the incoming data. Incoming data with string matches that meet the True or False criteria specified by the Rule Matching statements are further processed by statements in the Rule Parsing pane.

Understanding the Rule Matching Pane

In Figure 7-7, each statement searches for a single character.

Figure 7-7 Ruleset Editor: Rule Matching Pane

Before editing the Rule Matching pane, select the appropriate rule in the Rules Hierarchy pane. The title bar displays the currently selected rule name and description:

Figure 7-8 Ruleset Editor - The Title Bar Identifies the Current Rule.

The Rule Matching pane can contain one or more rows automatically joined by the AND operator. Multiple statements mean incoming events must match all the specified criteria.

Specifying a Start and End Column value is not required. A blank in these columns instructs the search to start at the beginning of a line and finish at the end of a line.

In the following example, the matching events must contain the string MessageType:PCC1, but must not contain the string ISPCC1. There is no End Column value, so the search ends at the last column of the line.

Figure 7-9 Ruleset Editor: Rule Matching pane with both True and False search strings

Adding Statements

Adding a Statement at the Bottom of the Rule Matching Pane

To add a statement at the bottom of the Rule Matching Pane:

Click (Add) in the Rule Matching pane.

A new row displays.
Specify the match statement in the new row.

Adding a Statement Beneath the Currently Selected Statement

To add a statement beneath the currently selected statement:

Click (Insert After).

A new row displays beneath the current row.

HINT:Be aware that clicking a cell in a row can automatically place it in an edit mode.

Adding a Statement Above the Currently Selected Statement

To add a statement above the currently selected statement:

Click (Insert Before).

A new row displays above the current row.

Moving Statements

To move a statement within the pane:

Select a statement.
Click (Up or Down) to move the statement.

Editing Rule Matching Columns

Table 7-2 provides a description of each column in the Rule Matching pane:

Table 7-2 Rule Matching Columns

Column	Value	Description
Test	True (Default)	Rule fires if the event message contains the text specified between the start and end columns.
Test	False	Rule fires if the event message does not contain the text specified between the start and end columns.
Line	1–999	The target line to search for a match in the event data. The default is 1. If the line count for the associated rule is greater than 1, select a different number from the drop-down list. If the line count for the rule equals 1, do not change this value.
Start Column	1–999	The position in the specified line where the string search begins. If this column is blank, the search begins at the first column of the line.
String	Any characters	The exact text found (True) or not found (False) in the event message. Trailing spaces are not trimmed and are represented using the space character (““).
End Column	1–999	The position in the specified line where the string search ends. If this column is blank, the search ends at the last column of the line.

Copying and Pasting Statements

Copying a Statement

To copy a statement:

Right-click a statement, then select Copy.

Pasting a Statement Above or Below an Existing Statement

To paste a statement:

Right-click any location in the row, then select Paste Before or Paste After.

Pasting the Statement at the End of the Pane

To paste a statement at the end of the pane:

Right-click any location in the bottom section of the pane that is not part of a row, then select Paste.

Deleting Statements

To delete a statement:

Select the row, then click (Delete) to open a dialog box where you can confirm the deletion.
Click Yes to delete the statement.

7.4.7 Editing the Rule Parsing Pane

The Rule Parsing pane specifies how to parse and store the incoming event data in variables defined for the ruleset. Be sure to define variables in the Variables pane before editing the Rule Parsing pane.

In Figure 7-10, the Ruleset Editor parses the string “|”into the variables named DATE, ALARM, and CLASS.

Figure 7-10 Ruleset Editor: Parse strings using relative start columns.

It searches the entire incoming line for the string because no start or end column is specified.

Subsequent parsing depends on the location of the first parsed variable by defining a Start Column value of ‑1 which specifies that the search begins after the last parsed column.