Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 4 Working with Rulebases : Referencing Variables in a Rulebase

Referencing Variables in a Rulebase
You can reference several kinds of variables in a rulebase. By referencing variables, the rulebase can adapt to changes on multiple machines. For example, not all machines store log files or temporary files in the same directory. Also, rulebases used on multiple platforms need to accommodate subtle differences in how path names are expressed. You can use variables rather than specifying this information manually.
When an action contains variable substitution, a new alert is generated each time the test is true and the value of the variable changes. Variable substitution is most useful for values that are either slowly changing, very important, or both.
Supported Types of Variables
The following types of variables are supported in a TIBCO Hawk rulebase:
Referencing these variables outside of a rulebase is not supported.
Referencing External Variables
External variables are variables defined by a user on the machine where the TIBCO Hawk agent runs.
First, you define the variable values in a properties file on the local machine. Then you specify the variable file using the -variable option when starting Hawk Agent. Then you can reference the external variable in a rulebase. For more information on agent startup parameters, see TIBCO Hawk Installation Configuration and Administration Guide.
After variable values are defined and the properties file is specified to the agent, you can reference external variables in a rulebase using the following syntax:
 
   ${External.<variable-name>}
where variable-name is the name of an environment variable defined in the properties file. The file uses a standard Java property file format, with one line per variable defined. Each entry is a name-value pair in the following format:
<variable-name>=<value>
You can reference external variables in string arguments of actions and in data source method string arguments. For example, the Hawk Services sample rulebase provides a rule for sending a high-level alert. Without variable substitution, the text of the alert is generic. With variable substitution, the alert includes information specific to the generating condition.
Restrictions
In Microsoft Windows, the following restrictions apply to external variables:
On UNIX systems, the env command outputs environment values in the correct format.
Referencing Internal Variables
Internal variables refer to elements of the current rulebase. This type of variable is defined internally by the TIBCO Hawk agent, and requires no properties file. Values are assigned to variables when the rule is processed.
Like external variables, internal variables can be referenced in string arguments of methods used as a rule’s data source or in string arguments of actions. You can manually type internal variable syntax in the string argument of a method, or, for action arguments, TIBCO Hawk WebConsole provides a dropdown list of internal variables.
Manually entering variables
To manually enter internal variables, specify the variable using the following syntax:
 
   ${Internal.<variable>}
where <variable> can be Agent Name, Agent IP Address, or so on.
The variables will be substituted with the appropriate value before the command is executed. For example, the command Telnet ${Internal.Agent Name} will be executed as Telnet kimyou if the command is executed for agent kimyou from the Agent View.
Referencing Data Source Variables
Data source variables are TIBCO Hawk variables that represent the return fields of a microagent method. The method must be used as the data source of the current rule. You can reference data source variables only in actions.
For example, the Hawk Services sample rulebase provides a rule for monitoring an event log and sending a high-level alert message when an error is written to the log. The Alert action type used in this rule allows you to specify a text string for the alert message. In this example, the text string is:
Hawk Agent : ${nextLine}
where ${nextLine} is the text of the error message in the log. nextLine is a label for values returned by the microagent method that gets information from the log file. Without variable substitution, you could include only static text, such as High level alert or a similar string, in the alert message.
How Variable Substitution Affects Actions
Action text strings can include variable references, where you include pertinent information from the data source in the alert text.
For example, the alert text:
 
   Disk space on ${Instance} is at ${% Free Space}%
might display as:
 
   Disk space on C: is at 10.2%
when generated. Or, if you call a script named ClearTempFiles.exe in an action whose data source provides information on disk partitions, you could specify the following command syntax:
 
   ClearTempFiles.exe ${Instance}
and the agent will insert the name of the logical drive into the command line.
Variable substitution can cause actions to be taken more than once. If an action raises an alert with a variable reference, a new alert is generated at each test evaluation when the text message is different until the alert is cleared, even if the action that raises the alert was configured to take place only once.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved