Rules: An Introduction

Components of a Rule’s Structure

A rule is a definition within the application project and, as such, does contain a handful of attributes. Specifically, each rule has a name and a group. The name uniquely identifies the rule within the module. The group is an application project-specific value used to organize rules.

The real definition of a rule, however, is contained in its Structure. The structure of a rule is the encapsulation of the logic to be evaluated at run-time. This logic then determines what the rule ultimately returns to the definition that called the rule. The components of a rule’s structure are referred to as Rule Terms. There are in general two types of terms that make up a rule. These are Function Terms and Data Terms. How these terms are then organized within the rule definition provides the overall structure of the rule; i.e., its evaluation logic.

Function terms provide specific processing or logic performed during the rule evaluation. Most functions take one or more arguments, or “parameters” that provide values to be processed by the function. The function itself will then return a value to its caller based on the value of its parameters. A function’s parameters can include both the return value from other functions and rule data terms.

Data terms are any term that is not a function and that provide data values processed by functions within the rule. There are several different sources for a data term, including properties, globals, actions, screen sets, and constant values set within the rule structure.

Context of Rule Evaluation

The processing of a rule definition on the Agentry Client is referred to as “rule evaluation.” This evaluation is always performed in some context based on the definition attribute for which the rule is being evaluated, and the data type expected to be returned by the rule. The context of a rule’s evaluation will affect what values are in scope for that evaluation and the overall behavior of the rule and its functions.

This behavior is driven by the data type specified by the context of the rule evaluation. A given rule is expected to return a specific data type based on the context in which it is evaluated. The rule will always return a value in that data type. If a caller of a rule expects a string, the rule will return a value with a data type of string. Within the rule, function terms have a similar behavior. Functions will always return a value in the data type asked for by whoever called the function. This caller will either be another function, or the caller of the rule.

The impact of a rule’s context on the data type of its return value, as well as the impact of a function’s context on its return value’s data type, is one that is important in understanding the overall evaluation processing of a rule. Most importantly, it is necessary to understand that not all functions support all return types. If a function is asked for a value in a data type it does not support, it will return a null value in the data type for which it has been asked. It is therefore important to have a clear understanding of both the context in which a function is called, and whether or not that function supports the return type dictated by that context.

Context will also impact what definitions can call a given rule. Rules are normally defined in the context in which they will be evaluated. However, as with most definitions, rules can be referenced by more than one caller. For rules, the data terms referenced by the rule, specifically properties must be available in all contexts in which the rule will be evaluated. A property will be referenced within the rule’s structure via a target path. This path must be one that is valid in every context in which the rule is evaluated. If it is not, the rule will return a null value for that property. This is likely to produce unexpected return values from the rule.

Rule Function Terms

Rule function terms, or simply rule functions, are the terms that provide the overall processing of a rule. Each rule has an entry point, which is the term that will return the value to the rule that is then returned to the caller of the rule. The simplest rule definition is one for which this entry point is set to a data term. However, such rules are uncommon as there are few situations in which it is necessary to return a value such as this using a rule.

In the majority of rule definitions, the rule’s entry point is a function call. Most functions take parameters. The parameters to a function provide the values the function will process or manipulate in order to produce a value to be returned by that function. This is similar to functions or methods in other languages a developer is familiar with.

Where rule functions are different is in their dealings with data types. The context in which a function is called sets the data type for that function call. A given function may support one or more data types, referred to as the function’s “supported return types.” If a function does not support the data type dictated by the context, the function will return the null equivalent for that data type.

The context of a function call can also impact the behavior of the function’s processing. This impact can include the data type of the function’s parameters, as well as how those parameters are processed by the function. Many functions will take parameters matching the data type of the context in which they are called. These same functions will support multiple return types. This means that the function can take parameters of one data type in one context and another data type in another context.

Rule Evaluation at Run-Time

A rule is evaluated at run time on the Agentry Client when the definition referencing the rule calls it. Rules are a purely client-side definition, meaning they only directly impact the behavior of the client application. Rules have no effect on the behavior of the Agentry Server or on communications between Agentry Client and Agentry Server.

When the rule is called is dependent on the type of definition referencing the rule. Rules evaluated to set the label of a button will be called when the parent screen for that button is displayed. Initial value rules to initialize transaction properties will be evaluated when the transaction is instantiated, or possibly when the transaction is applied, depending on the definition of the property’s initialization attributes. Other rule uses will result in different events resulting in a rule being evaluated.

The structure of the rule dictates the behavior of the evaluation. This structure is represented in a tree control in the Rule Editor within the Agentry Editor. Following is an example of this structure for a rule that creates an ID value for a new object instance on the Agentry Client:

This example is taken from the rule editor and is one of the components of that tool provided to developers for the purpose of defining a rule. In this example, the rule itself is represented by the root node of the tree control, which is named InitialCustomerID. As the only child node to this root is a function call to the function CONCATENATE. This function concatenates two or more string values, returning the result. The strings to concatenate are provided as parameters to the function.

In the example provided here the CONCATENATE function takes two parameters. The first is a constant value containing the text LOCAL_. This second parameter is a call to the function FROM_INTEGRAL_NUMBER, which is a conversion function that converts integral values to other data types.

Working down through this tree structure there are other rule terms for functions and data terms. At run time, this rule will be evaluated beginning with the innermost term. This term will then return a value to its caller, which will be a function. Each parameter to a function is evaluated in the order provided. In the above example, then, the first term evaluated is the first parameter to COUNT, which is a property denoted as :>Current Property. For this rule this refers to a collection of objects to be counted by the COUNT function. The second parameter to the COUNT function is then evaluated, which is a call to the function EQSTR. This function takes another function call as its first parameter, which is the function LEFT. Due to the nature of the COUNT function, the second parameter that is the EQSTR function call will be evaluated once for each object within the collection referenced by the target path :>Current Property. Once COUNT’s evaluation is complete, it will return a value to SUM, which will add this value to its second parameter, the constant value 1.

This evaluation continues back up to the top level term, which is the CONCATENATE function. The value returned by the CONCATENATE function will then be the value returned by the rule to the definition that called the rule.