Rule Editor
|
The Rule Editor is your RuleLab.Net tool for building and modifying the individual Rules. The Editor screen opens when you click an “Insert”, ”Append” or “Edit” button on the Rules Browser screen. The Editor consists of the 3 main sections: Precondition, Condition and Action.
Each Rule has an ID – a unique alias - that RuleLab.Net uses to refer to a particular Rule. You can change the Rule ID by editing it in the Rule Alias textbox. The textbox becomes editable only if no other rule depends on this one, that is – no other rule contains it in its Satisfied Rule list.
Use the Rule Priority dropdown box to alter the order in which the Rules will be evaluated by the BRE. You can always change the priority assigned to a Rule.
Comment popup allows entering Rule comments that appear in the Rules Browser. The Comment popup dialog displays all the operands/functions used in the Rule that you can Copy into the Comment text with a click of a button. To enter Comments, click the comment link.
Always validate your Rule before applying your changes. In most cases, the Editor will let you save incomplete changes in order not to interfere with your design workflow. However, at a later stage, any remaining placeholders, formulas incompatible with the opposite side operand, and other issues will alert you and require your attention.
To apply your changes to the Rule XML document, click the “Apply Changes” button or “Apply & Go Back” button. Your changes will appear in the Rules Browser. Note that your changes are not saved into the Database until you click the “Save Rules” button in the Rules Browser screen! However, should you loose your connection with RuleLab.Net Web site, the unsaved changes you made in the Editor will be available through an “unsaved session” alert upon the login.
To cancel changes and return back to the Browser screen click the “Ignore Changes & Go Back” button.
The Rules file must be locked if you wish to alter the Rules. For more information see Locking the Rules in the Rules Browser section. The Rule Editor has same Key/Lock icons as the Rules Browser screen. |
|
The Rule Condition is a logical expression that evaluates to true or false. It consists of a two side expression connected via the logical functions (And, Or, Not). You can nest AND’s and OR’s to reflect the logic of your business rule. Each “and” / ”or” links an expression consisting of a left side operand, a right side operand and a predicate (a function that determines how to compare the left side operand against the right side). For example:
Price Paid is GreaterThan $1200.00 and Customer Status is Equal To Frequent Customer
In this example:
“Price Paid” and “Customer Status” are the left side operands.
“$1200.00” and “Frequent Customer” are the right side operands.
“is Greater Than” and “is Equal To” are predicates
There are unary predicates that only work with left side operands, such as “is Empty”, “is Not Present”. They do not have the right side operands.
For example: Customer Profile is Not Empty
Left side operands can be Atoms and Formulas. Additionally, you have an option of applying system functions to operand data such as “text length”, “fraction” etc. You can also indicate how to process the loops if an Atom you selected is part of a loop structure in your XML data document.
Right side operands can be Data values (constants), Atoms, Facts and Formulas. The type of a right side operand must match the type of the left side. Unless the left side is a Formula, the RuleLab.Net will present you with the type matching choices for the right side data operand selection.
Building a Condition
The Rule Condition section
includes a toolbar and the condition expression. The toolbar has 
buttons
that let you create the new expressions and connect them logically. It also has
the X-button and NOTx button that allows deleting expressions.
When you click “AND” or “OR” button, a new line is added with the left and right side placeholders, for example:
and atom/formula is atom/fact/formula/value
You must click the placeholders to replace them with actual data operands.
The order of AND/OR buttons in the toolbar determines whether the new expression is added on the outside or inside of the logical “and” / ”or” of the same line. If the buttons are displayed as AND/OR on the “and” line and you would like to add another “and” then click the “AND” button:
Price Paid is Greater Than $1200.00
and Customer Status is Frequent
Customer
For example, you’d have to click the “AND” on the “price paid” line to add the “profile” expression:
Rule Condition:
Price Paid is Greater Than $1200.00
and Customer Status is Frequent
Customer
and Customer Profile is Not Empty
If you click the “OR” button then the nested “or” will be created to link the former “and” expression and the new expression. The new “or” will be connected to its parent via the “and”.
For example, if you click “OR” in the above instead of “AND” then you will change the condition to:
and
Price Paid is Greater Than $1200.00
and Customer Status is Frequent
Customer
or Customer
Profile is Not Empty
Note that once you click the “OR” button, the “AND” and “OR” buttons of the new expression will appear as “OR”/”AND”. This indicates that the “OR” button is now ready to concatenate a new expression with its own expression while the “AND” button would create a nested “and” within the “or”.
If you would like to negate an expression evaluation result,
please use the “NOT” button. Once you click it, the expression on the same line
will be prepended with “not”. This indicates that if the expression was
evaluated to true then false will be returned to the logical
connector, and vice versa. To remove the “not” operator click the 
button.
If you need to erase a logical connector along with its
expression, click the X button . Note that if the expression was nested
and was the last one in its group, then its logical connector is deleted. It is
no longer required because the expression can now join its parent’s logical
operator, for example:
Left Side Operand
You can set/change a left side operand by clicking the left placeholder in a new expression or left Atom/Formula in an existing. The dialog will popup letting you select an Atom or enter a Formula to compare against the right side operand. Use the radio buttons at the top to switch between the Atom and Formula sections.
The Atoms section lists all the Atoms in the currently loaded Atoms XML file. Each Atom line displays the data type of this Atom. Single-reference Atoms have the same data type as their XML Reference. Multi-reference Atoms show a type of “collection of…” (hover the mouse over the ‘collection of’ to see the underlying References). If you simply want to pick an Atom, select it and click the “Apply” button. The selected Atom name will replace the left side operand name or the placeholder.
By entering an Atom in the Condition, you are instructing the RuleLab.Net BRE to relate it to your XML data context at runtime. The BRE will use the Atom/Reference information to fetch data value(s) from your application XML data document.
Some Atom types such as Text and Numerics allow applying a function to data value. If a function is applied, the result of the function – rather than your corresponding XML data itself – will be compared with when the expression is evaluated. The applicable functions are displayed when you click an Atom row. Functions that make this list must be compatible with the Atom type. If a function you would like to apply is not part of the Product, please contact us for a suggestion/customization request.
To enter a Formula, click the Formula radio button.
Loops
If an Atom is defined as a Loop Atom, then the Atoms dialog allows you to specify how the loop data should be processed. The default selection is “Each” meaning that the expression will be evaluated for every related data value in the loop. In order for the expression to succeed, each iteration of the loop will have to succeed.
You, however, have other loop operators available to you including
Any – at least one iteration must succeed
First/Last – only first/last related data value in your XML document will be evaluated
Min/Max – for Numeric data types, only the min/max data value is evaluated
There are also aggregate operators that can process loop data:
Sum Of – the sum of the loop Numeric/Currency values
Average – average of the loop Numeric/Currency values
Number Of – loop item count is taking place of an actual data value(s)
“Sum Of” and “Average” allow you specify whether you want to apply them to All, First n-items or Last n-items.
Note that “Sum Of”, “Average” and “Number Of” will succeed (and return 0) even if corresponding data is not present.
Need to run a Rule separately on every group of loops? Simply check the “evaluate for each loop” box. Loop operators and aggregate functions will no longer apply. Instead, you will be instructing the BRE to read from and write into every loop independently from other loops. For example, by entering a formula tax = cost * 0.065 you could calculate the tax for every item in the following XML:
<items>
<item>
<cost>$100.00</cost >
<tax></tax >
</item>
<item>
<cost>$200.00</cost >
<tax></tax >
</item>
</items>
Saving changes
Once you have made the Atom selection as well as the function and loop choices, click the “Apply” button. Your selections and entries will be formatted and displayed as part of the left side operand name. You can always alter them later by clicking this name.
Note that if you edit/change your Atom selection or switch from an Atom to a Formula, your current expression might be reset depending on the type of a new selection. If it becomes incompatible with the current predicate or the right side operand then the predicate and/or the right side will change to “Equal To” and the placeholder correspondingly.
Right Side Operand
You can set/change the right side operand by clicking the right side operand in an existing expression or Atom/Fact/Formula/Data placeholder in a new. The dialog will popup letting you select an Atom, Fact or enter Data or Formula to compare against the left side operand. Use the radio button at the top to switch between the different operand types.
The right side operand heavily depends on the currently selected left side operand type. You cannot pick your right side operand until the left side is changed from a placeholder to a specific Atom or Formula. The Atoms and Facts listed in the popup are filtered through the left side Atom type. Only the compatible ones are presented.
Unless the left side type is a Numeric, Currency, Date or Time, you will not have an option to enter a Formula. For the Text-type and multi-reference Atoms there is simply no way to compare them against calculation formulas therefore the Formula radio button will not appear.
When choosing between the Data values, Atom and Fact options, consider where your data should be coming from. If you would like to relate to your XML data at runtime, choose an Atom. If you want to compare against a shared knowledge entity – a Fact – then pick one of the Facts. If you need to compare with hardcoded data values then choose “Data” and enter data values.
Atom
If you would like to compare the left side Atom/Formula against another Atom then select an Atom from the list. An Atom list displays Atom names from the currently loaded XML Atoms file. The lists consists of
- multi-reference Atoms that have the same set of XML References as the left side Atom
- single-reference Atoms that expose a Reference of the same type as the left side Atom
- single-reference Atoms that expose a Reference of a compatible type if the left side is a Formula or a Function
Atoms marked as Loops are not allowed on the right side of the expression unless the rule has been marked as “evaluate for each loop”.
Fact
To compare the left side with a Fact, pick a Fact from the Fact list. The Fact list displays the Facts from the currently loaded XML Facts file that match the left side type. The list of Facts includes:
- multi-reference Facts that have the same set of XML References as the left side Atom
- single-reference Facts that expose a Reference of a compatible type
To enter the specific Data values, click the “Data” radio button. The Atom’s References will be rendered according to their type. Simply enter values and click the “Apply” button. Note that you don’t have to enter ALL the values. At runtime, the BRE will only use the filled values for comparison against the right side.
By default, the loop operator (“Each”, “Any”, “Number Of “ etc) parses every data item in a loop. You can enter a filter that would limit the items being processed. The loop filter is a logical condition that applies to a loop item. Filter’s condition has the same format and flexibility as the Rule Condition. You can think of filters as sub-conditions within the main Condition, only a filter condition is evaluating one loop item at a time.
For example, let’s assume we have a list of Customer purchase transactions each containing the product, vendor, purchase date, and the price paid. We would like to give Customer a discount based on the transaction specifics:
If Customer has purchased 2 or more products from The New Vendor over the past 12 months then offer Customer 10% on the next purchase of The New Vendor’s product.
Basic condition required to implement this rule will apply “number Of” to the loop atom “Product”:
If number of Products is GreaterThan
2
Note that once you add a loop atom, the Editor displays the “add filter” button which allows you to enter a filter condition for this expression. In this case we’d want to exclude purchases beyond the 12 month period and only include the product bought from “The New Vendor”. When you click the “add filter” button, a “where” expression template is displayed. By selecting/entering the operands in the template we can build the following filter:
If number of Products is GreaterThan 2
where number of months since Purchase Date is Less Than or Equal To 12
and Vendor is The New Vendor
Filter expressions allow same commands as the main condition expressions. Using “AND”, “OR” buttons you can build fairly complex filters. Note that when choosing filter Atoms such as “Purchase Date” you will be limited to only the Atoms that belong to the outer Atom (“Product”).
Filters can also be used with calculation formulas that utilize loop Atoms.
Please remember that RuleLab.Net filters are intended to empower you with greater rule building flexibility. They are not meant as general purpose programming or query language. If you would like to build a rule with an additional functionality not supported by the RuleLab.Net please implement it in your application and provide the result as an XML field within the application XML document. You can then use that field in a Rule.
Using the Vocabulary of Natural Terms
If a Vocabulary of Natural Terms has been created and added to your Project, then the Terms lookup box will popup when you open a Rule. Using the Natural Terms, you can build a Phrase that replaces a logical expression. You can instantiate a Phrase by clicking the phrase link on a new expression line. This will create a text box where you can type a Phrase. Only the recognized Natural Terms will be extracted from your Phrase to translate it into a logical expression internally. The Natural Terms must be enclosed in square brackets. You can either type them in or copy from the Vocabulary Terms lookup box.
For more details please the Vocabulary of Natural Terms section.
Preconditions let you specify what Rules should be satisfied and/or what logical condition should evaluate to true in order to enable the Rule. Unless the Precondition is met, the Rule is ignored by the BRE therefore it will not fire in the given cycle.
Satisfied Rule Set
To enter a list of Rules that must be satisfied in order for the current rule to fire, click the “add Satisfied Rule precondition” link. A popup dialog opens letting you select the Rules from the list. Simply select the Rules and Copy them into the upper list of rule IDs. When finished click the “Apply” button.
To change a Satisfied Rule Set, click the “Satisfied Rules” link. You will be able to add/delete the Rule entries.
Logical Precondition
Optionally, you can specify a logical condition as a prerequisite for the rule. You may find this feature handy in many data validation scenarios. To add it, click the “add Logical Precondition” link and follow the Condition edit guidelines.
The Rule Action is where new values are assigned to your XML data. Actions are executed when rules fire. If the Condition was evaluated to true then “Rule Action – Then” clause is executed, and if it was evaluated to false then “Rule Action – Else” is executed.
Creating Actions
Actions consist of the “set” statements that assign Atom, Fact, Data or Formula result to an Atom. The left side of an assignment defines the destination while the right side defines the source. To add a “set” entry, click the “assign” link and choose your left side operand – the Atom. If this Action executes, then XML data references that this Atom consists of will guide the BRE to copy data into your XML document.
Unlike the assign link which only operates on the existing XML fields, the add link allows you to create XML fields within your document. The add link is specifically designed for appending XML elements associated with loop atoms. For example if your XML data document looks like this:
<products>
<prod>
<name>scanner</name>
<item>p100</item>
</prod>
</products>
and a 2-reference Atom xpaths are pointing to “/products/prod/name” and ‘/products/prod/item”
then adding a “product” Atom w/ “name” of “printer” and “item” of “p101” will result into adding a new “prod” node to your XML document
(the loop parent is set to “/products”):
<products>
<prod>
<name>scanner</name>
<item>p100</item>
</prod>
<prod>
<name>printer</name>
<item>p101</item>
</prod>
</products>
The clear link allows you to erase all instances of a loop atom. If XML parent nodes end up with no child nodes then they are erased too. For example, “clear product” will leave your XML document with just
<products>
</products>
You may find it handy to use the add/clear links for populating selection lists. Your rules could define the choices available to a user based the conditions. Your application would then copy the items from the updated XML document into the GUI’s listboxes and dropdown lists.
Building Actions
Action example:
Then set Customer Satisfaction to ‘happy’
In this example:
“Customer Satisfaction” is the left side operand
“happy” is the right side operand
The right side of the assignment can be an Atom, Fact, Data or Formula. At runtime, data is copied from the right side of the assignment into your XML document. For example, if you are assigning one Atom value to another:
Then set Amount Due to Deposit
the value of the “Deposit” atom is copied into your XML document at the XML path associated with “Amount Due” Reference.
To specify the right side of the Action, click the right side operand and choose between Data, Atom, Fact and Formula in the popup dialog. The Formula will only be available for the numeric, monetary, date and time single-reference Atoms. It will not show up if the left side Atom is a Text or multi-reference Atom.
Text field editor allows entering multi-line messages plus it lets you embed Atoms and Facts into a message body. When you select Data option in the Action popup, Atom and Fact listboxes come up just like with the Formula editing. Simply click an Atom/Fact and the arrow button to copy the name into the message text. Fact and Atom names must be enclosed in the square brackets, for example:
A non-refundable deposit in the amount of [Total Deposit] is due at the time of reservation ([Deposit per Person] per person).
Text string within a single-reference Atom can be used to pass User Messages back to the application. You can concatenate multiple messages within a single Atom. For example, if an Action is populating an Atom called “Discounts” then copy or type [Discounts] into the message text:
[Discounts] As a preferred customer, you received an additional [Return Customer Discount]% discount.
This will append the message to the value of “Discounts’ which may have already been populated by other rules offering other discounts.
If an Atom you are assigning to contains a Reference with no XML path into your data document then at runtime a target variable will be allocated in the BRE State XML document. You can still use this Atom like any other Atom. The absence of the path indicates a system variable that only exists in the BRE runtime environment.
To delete an assignment, click the X button on the corresponding line.
Both the right and left side operands allow calculation Formulas. Formulas can be used with the Numeric, Currency, Date and Time data types. You can use Atoms and Facts in formulas if they are composed of a single XML Reference of the following types: Numeric, Currency, Date or Time.
Formula syntax supports:
Parentheses: ()
Addition: +
Subtraction: -
Division: /
Remainder: %
Atom and Fact names must be enclosed in the square brackets.
To enter a formula expression, click the Formula radio button in the operand popup dialog. Note that not all right side operands support formulas (see the Right Side Operands section). Simply Type your Formula text in the box and use the Atom/Fact lists to Copy Atom/Fact names into the Formula text.
For example, the following expression could be entered to calculate the total price for a cruise/hotel package:
([Number of Nights in Hotel] * [Hotel Room Price Per Night]) + ([Number of Guests] * [Cruise Price Per Person])
For the left side operands, Atom and Fact lists display all Atoms and Facts compatible with the data type supported by Formulas, including loops. If you pick a loop Atom though, you will be required to select how the loop should be parsed. Your options are “Each, Any, First, Last”. The meaning of these choices is the same as with the regular Atoms (see “Left Side Operands”). They define whether a Formula will be applied to each, any etc data item. Formulas only allow mixing Atoms that belong to the same loop.
To insert your Formula into the Rule, click the “Apply” button. If your Formula syntax is okay the formula text will be copied into the Rule expression. The Syntax Checker does not validate the Formula result against the opposite side of an expression. Their compatibility will be checked when you Validate the Rule itself or the entire Rule set.
At runtime, the formula parser substitutes Atom and Fact names with the Application and Rule data values correspondingly.
An empty application numeric/monetary data value is interpreted as 0.
Functions that you can use in Formulas
Formulas support a number of functions that you can enter into the formula expression. The list of functions is displayed in a dropdown at the bottom of the Formula dialog. The dropdown shows the function calls with parameter placeholders so that you can copy them into the Formula and replace with the actual Atoms, Facts and constants.
For example, to copy dateDiffYears into the formula, select it from the dropdown and click the arrow button. The following string will be copied:
dateDiffYears([date1], [date2])
Assuming you have Atoms named dateOfBirth and filingDate, change the expression to:
dateDiffYears([filingDate], [dateOfBirth])
The following functions are supported:
dateDiffHours, dateDiffDays, dateDiffYears, dateDiffMonths, dateDiffWeekOfYear, dateDiffQuarters
Format: dateDiffYears([date1], [date2])
These functions return the numeric difference between date1 and date2 where date1 and date2 are date type Atoms. Alternatively, you can pass date constant in single quotes, for example:
dateDiffMonths(‘12/1/2006’, [date2]) – returns the number of months between 12/1/2006 and date2.
dateHoursSince, dateDaysSince, dateYearsSince, dateMonthsSince, dateQuartersSince
Format: dateHoursSince ([date])
ceiling - the smallest whole number greater than or equal to the specified number
Format: ceiling ([numeric1])
floor - the largest whole number less than or equal to the specified number
Format: floor ([numeric1])
round – the number with the specified precision nearest the specified value
Format: round([numeric], NumberOfDecimalPlaces) where NumberOfDecimalPlaces is a number between 0 and 4
sqrt – square root of a specified number
Format: sqrt ([numeric1])
min - the smallest of the two numerics
Format: min ([numeric1], [numeric2])
max - the largest of the two numerics
Format: max ([numeric1], [numeric2])
New functions can be added per your request.
Examples of formulas with functions calls:
2 * max (12, [num1])
floor([num1]) + ceiling([num2])
[num1] + round([num2], 3)
dateDiffYears([date1], [date2]) * 5
floor(max([num1], [num2]) / 2) + 1 + dateDiffYears([date1], [date2])
Mathematical and Text processing Functions
The Rule Condition supports a number of functions that can be applied to Atoms in the left side operands. Available functions are displayed in a popup box when you click the operand name. Only the functions applicable to the selected Atom are displayed. For example, to apply a function such as the “round number” to a numeric value you would:
1. Click the left side operand. Operand selection popup box comes up.
2. Switch to the Atoms.
3. Locate a single-reference Numeric Atom in the Atom list
4. Click the Numeric Atom. “Apply Function to Data” dropdown comes up.
5. Select “round number” from the dropdown, and while the Numeric Atom is still highlighted, click “Apply”.
6. The “round number” function will be inserted into the Rule. Now at runtime it will be the function result rather than the Atom’s value that the Rule Condition will evaluate.
The following functions are supported:
For the Numeric type Atoms
absolute value - the absolute value of a specified number
ceiling - the smallest whole number greater than or equal to the specified number
floor - the largest whole number less than or equal to the specified number
fraction - the fraction of the specified value
round number - the whole number nearest the specified value
For the Text type Atoms
text length - the number of characters in Atom’s text string
regular expression search – match regular expression pattern against Atom’s text string. The pattern is entered into the right side operand as data value.