The Rule Editor
The Rule Editor is where you write a rule. You build the rule from menus instead of typing it, so every field name is spelled right, every value has the right type, and a rule that cannot work is caught before it is saved. The finished rule reads like a sentence, such as "Check if Status is Active and Total is greater than 1000", so anyone can read what it does.
You meet the Rule Editor on the Rule Editor tab of every dialog that holds a rule: the New Rule and New Draft dialogs, the Draft dialog, and the Rule Version dialog, where it shows a saved version that can no longer be changed.
The components it uses:
- The Rule Area: the box where the rule is written. Each word or value in it is a rule element that you can click.
- The Help String: the grey line over the Rule Area. It always tells you what you can do next, and it explains why a rule cannot be saved.
- The menus: a menu opens next to the element you are working on and lists only what can come next at that point.
- The value inputs: boxes and pickers for typing a number or a text, picking a date or a time, or choosing from a list.
- The facts line: the line above the Rule Area, such as Rule Type: Evaluation · Reusable? No · Rule Definition: Editable. Editable means you can change the rule here; Immutable means it is a saved version and can only be read.
- Two icons in the Rule Area's corners: Copy the rule as text copies the whole rule as one sentence, and View in Full Mode opens the editor in a larger dialog. Close the larger dialog to return.
Starting a Rule
- Click anywhere in the Rule Area. The Help String says "Click anywhere in the Rule Area to begin creating a rule" until you do.
- The editor writes the first words: Check if for an evaluation rule, If for an execution rule. A menu opens with what can come first: the source object's fields, ( to start a group of conditions, and Collections... for conditions on a list.
Writing a Condition
A condition compares one thing with another: a field, an operator, and a value.
- In the menu, select a field. Reusable rules that you may use appear in the same menu by their names.
- The menu now lists the operators that suit that field. A number offers is equal to, is not equal to, is greater than, is greater than or equal to, is less than, is less than or equal to, is between, is not between, is in and is not in. Text, dates, times, durations, yes-or-no values and lists each offer their own. Select one.
- The menu now lists what the field can be compared with: a value you enter, other fields of the same kind, and, for numbers, Add a calculation.... Select what you want:
- Enter a number... or Enter a string... opens a box. Type the value and press Enter.
- Select a value... opens a list, such as True and False, or the members of a list of choices.
- Pick a date... opens a calendar, and a time field opens a time picker. A field that holds a length of time, such as "3 days 4 hours", opens a duration picker with a box for each unit.
- A field name compares the two fields with each other.
- For is between and is not between, enter both ends of the range. Both ends are included. For is in and is not in, select or enter the first value, select Add another value for each one after it, and select ) to close the list.
The menu then offers and and or, to add another condition. In an execution rule it also offers then.
Groups of Conditions
To decide which conditions belong together, put them in parentheses, just as in arithmetic: "Check if A and ( B or C )".
- Where a condition can start, select ( from the menu.
- Write the conditions inside.
- Select ) to close the group.
Conditions on a List
When the source object holds a list of things, such as the lines of an order, Collections... asks a question about the list:
- Exists...: at least one item matches the conditions you write next.
- Does not exist...: no item matches.
- All...: every item matches. A condition on all items of an empty list is false.
- First... and Last...: the first or the last item matches.
- Count with...: how many items match, compared with a number.
- Count...: how many items the list holds, compared with a number.
After you select one, the menu lists the source object's lists. Select one, then write the conditions about its items. The editor writes them in parentheses after the list's name.
Calculations, Joined Text and Date Shifts
A value does not have to be fixed. It can be worked out when the rule runs:
- Add a calculation... builds arithmetic from numbers, number fields and +, –, × and ÷, written in braces, such as "{ Weight × 2 }".
- Concatenate... joins texts and text fields into one text, such as "{ Region + -A }".
- A date can be shifted by a number of days, months or years, with the Add ... items the menu offers for dates, such as Add years....
The Then Part of an Execution Rule
After then, else if or else, the menu lists what the rule can do:
- Set... gives a field a new value. Select the field, then its value.
- Execute... runs another execution rule as one of this rule's actions. Only rules that allow it, and that have a live version, are listed. See Reusable and Inline Rules.
- The actions your application offers, listed by name. An action that needs details asks for them in parentheses after its name.
Join several of them with and. After the actions, the menu offers else if and else for the other branches.
Changing What You Wrote
- Click an element to change it. The menu opens with what can take its place.
- Press the Spacebar to open the menu for the selected element when it is hidden. If you are not sure where you are, click the empty space after the rule's last element and press the Spacebar: the menu lists every valid next step.
- Arrow keys move from element to element, or through the menu when it is open. Enter selects the highlighted menu item, finishes a value you are typing, or, with no menu open, starts a new line. Home and End go to the start and the end of the line, Page Up to the first element and Page Down to the last one you can see.
- Delete removes the selected element. Backspace removes the element before it. Esc closes the open menu or picker.
- Tab at the start of a line indents it. New lines and indents only change how the rule looks.
- Ctrl+click selects several elements; Ctrl+C, Ctrl+X and Ctrl+V copy, cut and paste them. Paste puts the elements after the one selected.
On a phone or tablet, tap an element to change it, swipe down to open the menu, swipe right to delete the selected element and swipe left to delete the one before it.
When a Rule Cannot Be Saved
The repository checks every rule when you go on from the editor (Next →) or save it. If the rule is empty, unfinished, or uses something that is not valid, nothing is saved: the editor highlights the elements that need attention, and the Help String says "This rule is invalid. Hover over the highlighted elements for details." Hover over each highlighted element to read what is wrong, fix it, and try again.
In a draft you can keep an unfinished rule and come back to it later. See Drafts.