17.0 Implementing Business Logic Using Rule Engine

 


17.1 Overview

17.2 What Is Rule and Ruleset?

17.3 Enabling Rule Engine

17.4 Configuration Files Used for Rule Engine Operation

       17.4.1 File Containing Agent Details

       17.4.2 File Containing Ruleset Details

17.5 Functioning of Rule Engine

17.6 Customizing Rule Engine

17.6 Packaging Details


 

17.1 Overview

 

Agent Toolkit SNMP Agent introduces the concept of Rule Engine that defines the users' business logic as a set of simple rules to monitor attribute(s) and perform tasks. These rules are connected together as ruleset in the rule engine and initiate actions such as sending traps/notifications, sending mails, and performing set operation when a given expression/logic is evaluated as true. These logics are stored as XML documents and can be manipulated manually by the user. The XML documents contain the set of data which is required to perform the defined operations in rule engine.

 

The advantage of Rule Engine is that it makes the users' business logic declarative through the XML file instead of hard-coding or instrumenting the decision process in the stub files to perform any action. 

 

17.2 What Is Rule and Ruleset?

 

Rules are a set of expression/logic containing parameters or managed objects to monitor the attributes of the users' application/device and then execute some actions. It defines the conditions/criteria for the managed objects of the application and performs operations based on the expression. The input of a rule can be one or more expressions that result in an output of single value invoking some action.

 

The key concept/input of Rule Engine is Ruleset. They are collection of rules executing all the rules defined under it one-by-one.

 

17.3 Enabling Rule Engine

 

Rule Engine can be enabled by choosing Settings->Source Generation->Enable Rule Engine Service from the MIB Compiler UI. The following is the code generated in the agent's main file while enabling Rule Engine Service:

 

//Enabling Rule Engine Service

 

private void initRuleEngine() {

  try{

        snmpLog.trace("Initializing Rule Engine");

        RuleEngineFactory.setAgentDetailFile("rule/AgentDetails.xml");

        RuleEngineFactory.setRuleDir("rule/");

        if(agentOptions.getDebugLevel() != -1){

                          RuleEngineFactory.setLoggingLevel(agentOptions.getDebugLevel());

        }

        RuleEngineFactory.setSnmpAgent(this);

        RuleEngine ruleEngine = RuleEngineFactory.createRuleEngine(1,"conf/ruleenginefactory.xml");  

        RuleEngineFactory.setResource("SnmpSetAction", new SnmpSetActionImpl());

        RuleEngineFactory.setResource("SnmpTrapAction", new SnmpTrapActionImpl());   

    }  

catch(Exception ex){

          System.out.println("Error in creating the RuleEngine");

    }

}  

 

Enabling the rule engine generates the configuration files under the <WebNMS/Javaagent>/snmpprojects/ruleengine/agent/bin/rule directory.

 

Based on the execution mode, the rule engine acts in either triggered mode or scheduler mode.

 

Triggered-Based Rule Execution Mode: Here, the action specified in the rule engine configuration file is performed, once the expression is "true". You have to manually execute a rule from your code specifying the corresponding RULEID. Add the piece of code wherever the rule needs to be triggered.

 

RuleEngineFactory.getRule().execute(1)

 

Here, 1 denotes the RULEID as mentioned in the .rule file.

 

The main advantage of triggered mode is that you can also use the functionality without processing all the rules provided in the rule file. By default, the rule engine operates in the triggered mode.

 

Scheduler-Based Rule Execution Mode: Here, a scheduler will be started, which will execute all the rules defined in the .rule file at periodic intervals specified in the setRefreshTime() method. Add the following piece of code to the initRuleEngine() method, to enable scheduler service by which the rule engine changes its mode of operation to scheduler:

 

RuleEngineScheduler scheduler = new RuleEngineScheduler(ruleEngine);

scheduler.setRefreshTime(1000);
scheduler.start();
System.out.println("Started Scheduler");

 

Note: The functionality of executing only a particular rule explained in the Triggered mode is not applicable to Scheduler mode.

 

17.4 Configuration Files Used for Rule Engine Operation

 

The operations of rule engine are executed by persisting the set of related data in some configuration file. These are editable files and you can configure or edit any data both at design time and at runtime. The modifications in the rule file or addition of any new rule file at runtime is updated without restarting the agent, if the HotDeployment is enabled, for every interval mentioned in the setHotDeploymentRefreshTime() method.

 

The configuration files are:

Note: The above HotDeployment applies to .rule file only and the interval for refresh time is specified in milliseconds.

 

17.4.1 File Containing Agent Details

 

The configuration file, AgentDetails.xml, contains SNMP agent-related details such as the tables used for agent configurations. The following are the tables present in the file:

 

AGENT_TABLE: The table consists of AGENTID, AGENTNAME, and TYPEID.

 

AGENTID: This serves as a unique identification for the SNMP agent and associates the SNMP-specific details of the agent with the RuleSet in the rule file, i.e., all the operations that are associated with the ID will be evaluated. The default value mentioned in the rule engine is 1.
 

AGENTNAME: This implies Agent name, i.e., the name of the main class of the agent is reflected here. By default, it is WebNMSSnmpAgent.
 

TYPEID: This is a unique identification for different tables used for storing information of different table that are explained below. The default TYPEID for AGENT_TABLE is 1. In the AGENT_TABLE, the TYPEID is '2' that represents the next table (SNMP_AGENT_DESCRIPTION_TABLE) to be processed.

 

SNMP_AGENT_DESCRIPTION_TABLE: This table holds the details of SNMP agent such as AgentID, AccessType, version, hostname, port, and community. If the version is 1 or 2, it implies that the agent is SNMPv1 or SNMPv2c respectively and the agent processing is performed with the mentioned community that is required for authenticating the requests. If the version is 3, then it implies that the agent is SNMPv3 and the SNMP_V3_AGENT_DESCRIPTION_TABLE is processed.

 

SNMP_V3_AGENT_DESCRIPTION_TABLE: As the name implies, this table contains all the security-related details required for SNMPv3 request processing with the context name.

 

TYPE_TABLE: This table has 2 columns:

 

TYPEID: Uniquely identifies the tables used in the Rule Engine.

TABLENAME: Name of the table used in Rule Engine.

 

17.4.2 File Containing Ruleset Details

 

The configuration file, RuleSet1.rule consists of the Ruleset with a set of rules defined in it and the operations resulting in the actions to be performed for the Ruleset. By default, the managed objects-related rules defined in notification-type/trap_type macros in the MIB module for which the agent is generated, are given in the rule file. The following are the tables available in the file:

 

RULESET_TABLE: A rule engine can have any number of rulesets using different rule files. A RULESETID is a unique identification of a ruleset in a rule file. By default, there is one rule file with RULESETID as 1. The STATUS column in the table provides the status of the table. That is, 0 denotes that the ruleset status is disabled and 1 denotes that it is enabled.

 

AGENT_RULESET_TABLE: This table describes the relation between the RULESETID and the AGENTID. Though there can be any number of rulesets in the rule engine, only those with the AGENTID as mentioned in the AgentDetails.xml are executed.

 

RULE_TABLE: Every rule (identified using RULEID) will have an EXPRESSIONID, ACTIONSETID, STATUS, and polling interval details. The EXPRESSIONID and ACTIONSETID are explained in their respective tables.

 

STATUS: This column in the table provides the status of the table. That is, 0 denotes that the rule status is disabled and 1 denotes that it is enabled.

 

Polling Interval: This mentions the interval after which the rule engine polls the agent for data contained in the managed objects. By default, the polling interval is 5000ms.

 

RULESET_RULE_RELATION_TABLE: A ruleset is composed of one or many rules. This table is used to get the rules for the specified ruleset. This is obtained by mapping the set of rules using RULEID to the RULESETID which is performed in this table. The combination of RULEID and RULESETID should be unique.

 

EXPRESSION: It consists of EXPRESSIONID that specifies the different expressions to be executed in the rule engine. An expression performs the work of a program and consists of a series of variables and operators that are evaluated to a single value called the output. Here, the expression is identified using an expressionID which contains LEFTEXPID and RIGHTEXPID with an operator. Both the LEFTEXPID and RIGHTEXPID refers to the DATAID. These expressions can be either Composed Expression or Expression Operator Expression (EOE).

 

EOE: Any simple expression that compares two variables or constants using operators such as GreaterThan(>), LessThan(<), GreaterThanOrEquals(>=), LessThanOrEquals(<=), equals(==), !=, IsChanged, etc. are mostly considered the Expression Operator Expression (EOE).

 

Composed Expression: Any compound expression that evaluates complex or more than one expressions is mostly considered as the composed expression. The EOE can be made as a part of composed expressions with operators such as AND, OR, etc.

 

ACTION_TABLE:  When any expression is executed, an action should be performed as an acknowledgment to the expression being successfully completed. The outputs from a rule engine may be viewed through actions such as sending traps/notifications, mails, or setting another expression. These actions are denoted by ACTIONID. The different actions supported by the rule engine are:

 

Traps: Traps are generated from the agent usually when the values of the data objects defined by trap-type are modified. Using Rule Engine, traps can also be sent while executing some expression/logic. These traps also contain information similar to the traps sent through trap definition.

 

EMAIL: This action sends an e-mail to the email ID mentioned in the rule engine. This also sends mail with To, Cc, and Bcc address. The subject and message body of the mail is modifiable and any message related to the rule can be mentioned, say "E-mail received for $object$ from $host$ and $port$", where the string passed between $ sign mentions the macros. To know about macros, refer to MACRO_TABLE.

 

SET Action: When an expression is executed, a SET request is sent to a managed object as defined in the SNMP_SET_ACTION_TABLE.  

 

ACTIONSET_TABLE: An ActionSet contains one or more actions. So the ACTIONID is mapped to the ACTIONSETID using this table. For example, if there are 3 actions to be performed, then the actions can be grouped under one ACTIONSETID. There can be more than one ACTIONSETID.

 

DATA_TABLE: This table includes mapping of DATAID with TYPEID. The DATAID is the identification for the data used in the expression. An expression consists of variables, constants, and operators combined to perform some useful computation. The variables or constants are referred to using DATAID. The DATAID will in turn refer to a table such as SNMP_DATA_TABLE or CONSTANT_DATA_TABLE, using TYPEID for retrieving data.

 

DATA_LIST_TABLE: The table has DATALISTID and DATAID. The Datalist concept is used for grouping data. The DATALISTID is used to send extra varbinds through trap with the data mentioned using DATAID. This table specification is optional.

 

MACRO_TABLE: Macros are messages included in all the e-mail sent from the agent when configured in the rule engine. This reduces your manual work as you need to send any message that is unique to all e-mail, say a signature. This table consists of MACROID, MACRONAME, and DATAID. Here, MACROID and MACRONAME must be unique. Once the MACRONAME is passed between "$" sign in the EMAIL_ACTION_TABLE, then all the e-mail messages carry the data mentioned in the DATAID which is specific to that MACROID.

 

SNMP_DATA_TABLE: This table is used for retrieving the value of an SNMP attribute from the associated agent. The fields include DATAID, GROUPNAME, SUBID, and INSTANCE. The managed objects or the data used for the expression is identified using the DATAID mentioned in the DATA_TABLE. The other parameters define the details of the object.

 

GROUPNAME: This holds the name of the group (scalar or tabular) to which the managed object belongs.
SUBID: Here the SUBID of the object must be specified.
INSTANCE: For a scalar variable, the instance must be specified as "NONE". For a tabular variable, the instance must be mentioned. The rule engine supports expression for tabular variables with both index and external index, For example, both <INSTANCE>.1</INSTANCE> and <INSTANCE>.6.87.23.56.35.24.67</INSTANCE> are allowed. If <INSTANCE>ALL</INSTANCE> is mentioned, then values from all rows will be retrieved.

 

CONSTANT_DATA_TABLE: This table is used to store the values of the variables, i.e, constants. Here, the TYPEID denotes the TypeID of the type of the constant value (for example, java.lang.String).

 

Thus, the expression is evaluated using the above-mentioned tables and requires to acknowledge using actions which are enabled using the below tables.

 

EMAIL_ADDRESS_TABLE: For sending e-mail, the mail address is mentioned in the configuration file using this table. Any number of address can be given and they are identified using EMAILID.

 

EMAIL_SERVER_SETTINGS_TABLE: This table is used to specify the details of the SMTP server through which you need to send the mail. The server name is mentioned in the SERVERNAME and its port in PORT. If the mails are supposed to be sent through more than one server, they can be provided using a different SERVERID.

 

EMAIL_ACTION_TABLE: This table provides e-mail details such as the content of the mail, subject, and message body. The table parameters include:

 

ACTIONID: The ID is taken from ACTION_TABLE.

SERVERID: Identifies the SMTP server to send the e-mails and the value is obtained from EMAIL_SERVER_SETTINGS_TABLE.

EMAILID: Refers to the "From" address and can be any string mentioned in the EMAIL_ADDRESS_TABLE.

 

EMAIL_ACTION_RELATION_TABLE: This table is used for finding out the recipients of this e-mail. It gives the relation between EMAILID and ACTIONID where the ACTIONID decides whether the e-mail needs to be sent for the EMAILID. The e-mail will be sent only if the EMAILID is mapped to the ACTIONID that is specified in the EMAIL_ACTION_TABLE. Also, the e-mail can be send as To, Cc, and Bcc through RECIPIENTTYPE where 1 denotes To, 2 denotes Cc, and 3 denotes Bcc.

 

SNMP_SET_ACTION_TABLE: As explained above, rule engine performs a SET operation, when a given expression is evaluated. The expression or the details for the SET operation are provided in the table. It includes parameters such as

 

ACTIONID:The ID mentioned for SNMP SET action in the ACTION_TABLE.

VERSION: Version of the request.

OID: The OID of the managed object .

TYPEID: This denotes the data type of the managed object to which the SET operation is to be performed. Here, the mapping for the SNMP data type is done based on how it is defined in the SNMP API. For reference, see the SNMP API javadocs.

VALUE: Value to be set.

INSTANCE: Instance of the object.

 

SNMP_TRAP_ACTION_TABLE: This table gives information on the mapping of ACTIONID and TFTABLEID. The TFTABLEID is an identification for the trap forwarding table.

 

TRAP_FORWARDING_TABLE: This contains the Trap Forwarding Table details that include the following:

 

TFTABLEID: An identification for the trap forwarding table and the trap will be send only to those entries present in the SNMP_TRAP_ACTION_TABLE. If given a value of "0", this parameter will send trap to all entries available in the Trap Forwarding Table of the agent.

MANAGERHOST: This implies the IP address or the host of the manager.

MANAGERHOSTTYPE: This implies the host type (IPV4 or IPV6).

MANAGERPORT: This refers to the port at which the manager is running.

 

17.5 Functioning of Rule Engine

 

Now that we have known the tables in the rule engine configuration files, let us see the functioning of the rule engine to execute any expression based on the tables.

  1. Rule Engine Initialization: The SNMP agent-specific details such as SNMP port, version, etc., will be obtained by the Rule Engine and it will be initialized. Now all the .rule files in the <WebNMS Home>/<project_name>/agent/bin/rule directory will be checked and the rules given in the files will be executed.

  2. Rule Execution: First, the set of Ruleset(s) corresponding to the SNMP agent is determined. The details about the Ruleset(s) are available at RULESET_TABLE. If the Ruleset is active (Status = 1), then all the rules under this Ruleset are executed.

    From RULESET_RULE_RELATION_TABLE, the rules corresponding to a Ruleset are taken and executed one-by-one. The details about the rule(s) are taken from the RULE_TABLE. For each rule, a expression will be evaluated using the EXPRESSION table and if the expression is evaluated true, a set of actions can be performed.
     

  3. Note: All the rules defined in .rule file will be executed only in the Scheduler mode. In the Trigger mode, you have to manually execute a particular Rule by using the code

     

  4. Expression Evaluation: EXPRESSION table has the ID that associates itself to a table that provides the description of the expression. The expression may be simple such as attributeA != attributeB or complex such as {attributeA != attributeB} AND {attributeB != 'A'}. To handle expressions, the following tables are used:

     

  5.  

    Note: If the Operator used is a unary operator such as IsChanged, then RightOperand is not necessary.

     

    To evaluate a expression of a rule, the corresponding EXPRESSIONID is considered. The EXPRESSION table will be checked for this EXPRESSIONID. If it is not present, this expression will be evaluated false or the Composed expression table is checked. In this table, the left and right operands (which again may be a simple/complex expression) will be checked recursively and proceeded further.

    If there is no entry for composed expression, then the EOE table is considered. To obtain the values of the left and right operands in simple expression defined in EOE table, the columns LEFTEXPID and RIGHTEXPID are used and they refer to the DATAID.
     

    For Example, the following composed expression must be evaluated using Rule Engine,

    { (agentNetstat == 'net') OR (agentPing == 'ping') } AND {aaplicationUserName == 'testing'}

     

    For calculating the preceding composed expression,
    In composed expression table, following entries should be present
    C1 -> the whole expression
    C2 -> { (agentNetstat == 'net') OR (agentPing == 'ping') }

    In EOE table, following entries will be present
    E1 ->  {aaplicationUserName == 'testing'}
    E2 ->  (agentNetstat == 'net')
    E3 ->  (agentPing == 'ping')

     

    The above expression can be represented as

    C1 -> C2 AND E1

     

    where C2 -> E2 OR E3

     

    Using the DATAID, the constant or variable data used in the expressions can be retrieved in the following ways:

     

    1. The DATAID is checked in the DATA_TABLE where it is associated to TYPEID depending on whether the data type is constant or SNMP. (that is, the value of attributes defined in MIB modules for which the agent is generated).

    2. If the data is constant, the value of the data will be mentioned in the CONSTANT_DATA_TABLE. The TYPEID column defines the type of the constant data (That is, java.lang.String, java.lang.Integer etc) in the AgentDetails.xml file.

    3. If the data is SNMP, the SNMP_DATA_TABLE is used to retrieve the value from the agent. In case of retrieving values from the table groups (defined in MIB), the relevant instance part should be given in the INSTANCE column.

     

  6. Performing Actions: Once the expression is evaluated true, the corresponding ActionSet, having a list of actions to be performed for this rule, is specified by the column ACTIONSETID. The list of actions in a particular ActionSet can be obtained from the ACTIONSET_TABLE.

    The details about each action will be present in the ACTION_TABLE. Now depending on the TYPEID column in ACTION_TABLE, three types of actions can be performed. They are as follows:

  7.  

    4.1 SNMP Trap Action: For performing SNMP Trap action, SNMP_TRAP_ACTION_TABLE is used. For sending traps, the configuration tables of the agent v3TrapForwardingTable/v1v2TrapForwardingTable are used. Here the relevant details such as manager host address and manager port are present. The OID of the traps generated by the Rule Engine is specified in the column TRAPOID.

    There is also a provision for sending additional Snmp varbinds along with the Trap PDU using DATA_LIST_TABLE.

    4.2 Snmp Set Action: For performing this action, SNMP_SET_ACTION_TABLE is  used. The value to be set is given in the VALUE column and the SNMP type of the value to be set is given by the corresponding TYPEID. For performing SNMP Set operations for the attributes in table groups, the instance part should be specified in the INSTANCE column.
     

    Note: For sending String data, the type STRING (notation from SNMP API class), not java.lang.String must be used.

     

    4.3 E-mail Action: The EMAILID column denotes the 'From' address of the e-mail to be sent. The SMTP server configurations will be taken using the SERVERID column. Using the ACTIONID, the EMAIL_ACTION_RELATION_TABLE will be used for finding the intended recipients of the e-mail. There is a provision for using Macros in Subject and Message body. To use the macros, the ISMACROALLOWED column in ACTION_TABLE should be 1(true).

17.6 Customizing Rule Engine

 

The rule engine can be customized using the various interfaces packaged with the Agent Toolkit. The interfaces helps you to implement your own classes that in turn evaluates the rule file accordingly. The interfaces generated for rule engine are as follows:

While enabling the rule engine, it loads the classes related to the ruleset operations from the ruleenginefactory.xml file. This file is generated under the <WebNMS/Javaagent>/snmpprojects/<projectname>/bin/conf directory and contains the default implementation class names for expression, action, rule etc. You can enjoy your own functioning of the rule engine by providing his implementation classes in place of the default classes in the xml file.

 

17.7 Packaging Details

 

The jars and the configuration files required for rule engine are as follows:



Copyright © 2013, ZOHO Corp. All Rights Reserved.