Working with Rule Editors

Key Points: Working with Rule Editors

1. The rule editors
integrate includes various rule editors, including:

Price file editor
Validation editor
Timber cutting list
Estimated labour time
Fitting units (installation labour time)
Default ironmongery
Part allocator
Duplex bar selector
Custom rule editor - conditions in this editor are written differently from those in the other editors, refer to the separate guidance document

2. Differences between the rule editors
There are differences between the different editors, but fundamentally they all work in the same way. The system checks each rule to see if its condition is met, and if so performs a certain action. 

3. Creating rules
There must be at least one group. Groups are simply a way of organising rules. To create a new group, click the blue groups button in the top right, type the name of the group, click add new. The number is the sort order - a lower number will make that group appear higher in the list.

Note: The exception is the estimated labour time editor which uses processes instead of groups.

4. How rules are listed
Rules are listed under their respective groups, according to sort order, where:

1. The loop the rule triggers on
2. The name of the rule
3. The condition which decides when the rule triggers
4. The action the rule performs when it triggers

In the given example from the default ironmongery editor, 

The given example is from the default Ironmongery editor, where the action is to add an ironmongery part to a drawing. The edit, copy, and log buttons allow rules to be changed or duplicated. History of previous changes can be checked.

When a rule is created, it needs to be decided which loop it should trigger on. This determines how many times the system will 'loop' through its code when checking if the condition in the rule is true.

For example, a rule on the frame loop will be run once per frame, whereas a rule on the ironmongery part loop will be run once for each part - sash lift, pulley wheel, casement stay, etc. This allows the price file to add a charge for each piece of hardware on a drawing, or the timber cutting list, to specify a piece of timber for each cill on a bay window. If N/A is selected, the rule is run on the item level, so will be checked once per item, or drawing.

The list of available loops will be different in different editors.

6. Quote level rules
In the price file and validation editors, rules can be run at the quote level. This is another loop above the item level, which is run once per quote. These rules must belong to a group specifically designated for quote level rules. The quote level for a group can be marked using the tick box when the group is created or edited.

Rules can then be toggled to quote level.

This loop contains variables which can check the number of items on the quote which meet certain criteria, for example, the number of free-text items on the quote (free_text_item_qty).

Quote level pricing groups are displayed as separate entries below the individual items on a quote.

Quote level validation messages appear on the quote matrix page. 

7. Conditions
After running quote level rules, the condition is specified which decides when the rule will trigger. A condition consists of one or more expressions, each of which is evaluated as either true or false. Multiple expressions are combined using and/or operators. for example, needs_draughtsealing and is_sw and frame_area < 2.0

8. Variables
Variables are essential for writing conditions, they enable information to pull from the drawing and check whether it meets certain criteria.  Each expression is based around at least one variable.

Different variables are available depending on which loop is selected. The same variable may refer to different values on different loops, for example, area refers to frame area on the frame loop, and sash area on the sash loop. The two main types of variables are:

a. Numerical - Quantity/Amount
These variables return a number. For example, frame area in square metres, or number of door leaves in a drawing. In expressions, numerical variables must be compared against another number (which could itself be a variable) using mathematical operators:

== Equals - Note that double = must be used
+    Plus
-     Minus
*     Multiplication
/     Division
<     Less than
>     Greater than
<=  Less than or equal to
>=  Greater than or equal to
()     Brackets

b. Flags
These check whether something is true or false, for example, whether a sash opens. They normally have the word 'is' at the start of the variable name, for example, is_opening. Flags cannot be combined with numerical values; a flag variable by itself is a complete expression.

c. Combining and negating expressions
integrate recognises three logical operators:

and - Allows multiple expressions to be combined. They must all return true for the condition to trigger.

or - Allows multiple expressions to be combined. Only one needs to return true for the condition to trigger. or statements should be enclosed within brackets to separate them from the rest of the condition.

not - Negates the following operator or expression. For example, not is_installation_included would return true on a supply only job, and sash_thickness not == 48 would return true if the sash thickness was anything other than 48mm.

The given example above on the sliding sash loop, uses four variables in order to assign one sash lift to a pair of sashes if certain conditions are met:

is_bottom_sash - Is a flag
Cannot be combined with any numerical value, and can only be either true or false. This variable returns true when the sash being checked is the bottom sash of a sliding pair. On a single pair of sashes, rules on the sliding sash loop will be checked twice (once for each sash), but is_bottom_sash will trigger only once.

to_be_replaced - Is a flag variable
Returns true if the sliding sash is set to be replaced. The rule would not trigger for repair jobs.

is_opening - Is a  flag
Returns true if the sash is set to opening. Exactly the same thing could be achieved using not is_fixed instead of is_opening.

width - Is an amount variable.
Since it is used on the sliding sash loop, it returns the width of the sash in mm. For example, a rule for width >= 500 will only trigger if the sash width is greater than or equal to  500mm.

d. Brackets
For more complex conditions using longer calculations, or a combination of or/and statements, brackets will be needed. The contents of brackets are always evaluated first, and the result of that calculation treated as an individual expression.

Example - Frame loop
The frame loop is designed to trigger for oak single doors with no top-light or side-light:

First set of brackets
Checks the sash quantity plus the direct glazed unit quantity is exactly 1, excluding double doors, and single doors with a top-light or side-light.

Second set of brackets
Takes into account several oak options are available in the system. If any of these are selected for the door leaf material,  the bracketed section will return true.

Example - Casement sash loop
The casement sash loop is designed to trigger for fixed casements with a frame area 0.9-1 m². On the casement sash loop, area will calculate the sash area, not the frame area. Therefore, a formula inside brackets to calculate frame height is multiplied against another formula in brackets to calculate frame width, to give frame area in mm².

e. Conditional outputs
Flag variables can be combined with a question mark to return two possible values for a rule based on whether the variable returns true or false. The syntax is variable?x:y, where x is the output if the variable returns true, and y is the output if the variable returns false.

Example - Conditional statement to the markup section of pricing rules
If different markups were required for two different ranges, for example, Classic and Bespoke, one way to do this would be to have separate pricing rules for each range. However, this means double the total number of pricing rules are needed.

A better way would be to add a conditional statement to the markup section of each pricing rule: is_bespoke_range?3.5:2.5 The value will be 3.5 when the Bespoke range is selected, and 2.5 the rest of the time.

f. Custom variables
Custom variables allow a customisable figure to be inserted into multiple rules, that can be easily updated at once by changing the variable.

Example - Markup custom variable
In the price file, instead of inserting a numerical markup figure into each rule, a custom variable called markup can be created. If the markup figure needs to be adjusted, only the markup variable needs to be edited, rather than hundreds of pricing rules. After adjusting a custom variable, a new price file must be published for the change to take effect.

Example - Add free text to conditions
The conditions field only accepts numbers, functions, mathematical/logical operators, and variables. In the given example below, if a condition is needed to check for accoya frames, frame_material == accoya will not normally work, because accoya is not a variable recognised by the system:

However, if a custom variable is created called accoya and the value of the variable is set to accoya, the rule will save. This is because the condition editor cannot read text directly, but can check the contents of the variable called accoya and read the text from that.

Custom variables can also contain a list of figures separated by commas, which can be used with the contains() and in_list() functions, as shown in the given example below.

9. Functions
Functions are as follows:

round(A, B) - Rounds A to B decimal places
round_up_to_nearest(A, B) - Rounds A up to nearest multiple of B, where B is an integer
min(A, B) - Returns the lowest value out of A and B
max(A, B) - Returns the highest value out of A and B
ceil(A) - Rounds up to the nearest integer
floor(A) - Rounds down to the nearest integer
contains(A, B) - Checks if text in variable A contains any of the items in variable B.  This doesn't have to be an exact match, for example, the phrase lead weight contains the text weight.  B can be a single value or a list of values separated by commas.
abs(A) - Converts negative numbers to positive numbers, while positive numbers remain the same
empty(A) - Returns True if variable A is empty
concatenate(A, B, C...) - Glues several textual variables together to make a new variable. May be useful in conjunction with contains()
lowercase(A) - Converts variable A to lowercase

Example - Pricing rule to add an uplift for any window painted black
First, a custom variable is created in the price file editor called black_finish, and the value of the variable set to black.
 
Next, write a pricing rule on the item-level loop using the following condition.


This rule will trigger if either the internal or external finish contains any of the text in the variable black_finish. Since the variable has been set to black, the rule will trigger if the internal or external finish contains the word black.

Example - Pricing rule for vacuum glazing, when part list contains different vacuum glass types
in_list(A, B) checks if text in variable A matches any of the items in variable B exactly. B can be a single value or a list of values separated by commas.

First, create a custom variable in the price file editor for vacuum_glazing, and add the part numbers for each type of vacuum glass, separated by commas. 

Next, write a pricing rule on the glass-unit loop, using the following condition.

This rule triggers if the glass unit is single glazed, and if its glass part number matches any of the values in the list called vacuum_glazing.

10. Testing rules
Each editor allows rules to be tested using a sample quote and/or order. Input the details of the desired sample quote/order at the top of the page, then click save.

It is possible to see whether each rule triggers for each item, and depending on the editor, what value is calculated.

For the TCL, allocation rules are run when the drawing is saved. When testing pricing rules that use values from the TCL, you should make sure you have saved the drawing since making the rules.