Calculation rule – keep a field up to date¶
A calculation rule computes the value of a field from an expression and writes it again whenever something the value depends on changes. This page describes its settings and behaviour. It is intended for administrators who configure business rules.
1. At a glance¶
| Purpose | Computes a field from other fields of the record or from related records, for the whole life of the record |
| Typical use | Totals, net and gross amounts, durations, derived statuses, concatenated texts |
| Related | Default value rule (once on creation), Set before save rule (on every save) |
The field is effectively owned by the rule: a user can type into it, but the next change of a trigger overwrites the value. If users should be able to correct a computed value, use a default value rule instead.
2. Settings¶
| Setting | Meaning | Default / required |
|---|---|---|
| "Field" | The field of the entity that receives the computed value | required |
| "Value" | The expression that computes the value. It is evaluated against the record being edited. | required |
| "Trigger on any change" | The trigger fields are taken from the "Value" expression: the rule runs when a field the expression reads changes. It does not mean "on every change of the record". | off |
| "Trigger fields" | The fields whose change starts the rule, chosen by hand. Only available while "Trigger on any change" is off. The target field itself cannot be selected. | empty |
| "Trigger on record creation" | The rule additionally runs once when a new record is created, after all default values have been applied | off |
| "Disabled" | The rule does not run | off |
Plus "Display Name", "Description" and "Tags" (see Business rules).
Recommendation: switch on "Trigger on any change" in most cases. The list of triggers then follows the formula when you change it later. Choose trigger fields by hand only if the rule should react to fewer fields than the formula reads, or to a field the formula does not read at all.
3. Behaviour¶
When the rule runs¶
| Situation | The rule runs |
|---|---|
| A trigger field gets a new value | yes |
| A relationship that the "Value" expression reads changes – a related record is added, linked, unlinked or removed, or a field of a related record is changed through this record | yes, in both modes of "Trigger on any change" |
| A new record is created | only with "Trigger on record creation" |
| An existing record is opened | only if one of its trigger fields has the field setting "Run Business Rules on load" |
| The record is saved | no |
A value that the rule writes is a normal field change: it is validated, and it can start further calculation rules and event based rules. A rule is not started again by the value it has just written itself.
Run Business Rules on load¶
"Run Business Rules on load" is a setting of an entity field (see Entities and fields). For every record that is opened, nexxcite runs the calculation rules triggered by such a field, as if the field had just changed. Use it for values that depend on something besides the stored fields – typically today's date. It costs one rule run per opened record, and grids of the entity then read their records completely instead of only the columns they show. Use the setting sparingly on entities with many records.
Validation of the result¶
After writing, the validation rules of the target field check the new value. A value they reject is not kept; the field keeps its previous value.
Errors and incomplete rules¶
A rule without "Field" or "Value", or with an expression that no longer exists, does nothing. The reason is written to the application log. An expression that returns an empty value empties the field.
Order¶
Calculation rules have no priority. If several of them are triggered by the same change, they run in no defined order. A calculation that reads the result of another calculation still gets the right value, because it is triggered again when that result is written.
4. Examples¶
Gross amount. Entity Invoice line, "Field" = Gross, "Value" = Net × (1 + VAT rate / 100), "Trigger on any change" on. Changing Net from 100 to 200 with a VAT rate of 19 sets Gross to 238.
Order total over related records. Entity Order, "Field" = Total, "Value" = sum of Amount over the relationship Order items, "Trigger on any change" on. Adding an item with the amount 50 to an order with the total 120 sets the total to 170 – while the user is still editing the order, before anything is saved.
Age in years. Entity Person, "Field" = Age, "Value" = duration from Birth date to the current date in years, "Trigger on any change" on. The field Birth date has "Run Business Rules on load", so the age is recalculated every time a person is opened and is correct again after a birthday.
5. Limitations¶
- Existing records are not recalculated when you create or change a rule. Their value changes only when the rule is triggered for them the next time.
- Changes made elsewhere do not reach the parent record. A change of a related record counts only if it is made through this record (for example in a sub-grid of its form). If a related record is changed on its own – by another user, an action on that record or a background job – the calculated field of this record is not updated until the rule is triggered again.
- No priority. The order of several calculation rules cannot be set.
- Loops are not reliably detected. Two rules that write each other's trigger fields with values that keep changing can block the operation (see Business rules, section 7).
- A calculated value that a validation rule of the target field rejects is dropped without a message.