Rules

docs model reference
1

Rules are simple or complex functions that define what you would sometimes call “calculated fields”. They are what a formula would be to a spreadsheet. A rule mostly depends on other fields, e.g. a total price = quantity * unit price. As you always want price to equal to this formula, you can call it a rule.

There are different ways how to calculate data:

  • Manual data entry (through UI)
  • XSLT transformation
  • Custom function
  • Rule

How do you know if your formula should be a rule?

  1. If it should calculate automatically during UI data entry — it must be a rule. There is no other way to interactively calculate anything in the user interface.
  2. If the same formula would be used inside multiple transformations — it is most probably a rule as rules prevent repeating logic. Once you define a rule, it is always being applied, no matter which way you touch the data (unless you access them without applying the rules, then you can overwrite anything you wish).

Rule examples:

  • Total price
  • An address loaded when user selects a customer from a dropdown box (although the address could be updated manually later without being overwriten — see below)
  • Price loaded by a combination of product and customer and an order date

No matter how many rules you define, they will always calculate untill all of them are satisfied. This greatly simplifies how you define your business logic. You just define how different fields should be calculated and the engine just manages it. So when you change the customer, the price (which is dependent on it) will recalculate automatically. Since the unit price just changed, the total price will be recalculated subsequently but you dont’t have to care about that much. It will just work.

In order to differentiate the rules from the other data changes, we will call those Actions.

Action examples:

  • Change order status
  • Generate invoice
  • Update paid amount

As you can see, actions change thata on purpose at some point in time. The rules keep the data constrained all the time.

You should think carefully about your business logic and define well what rules are and what actions are.

Calculating data with possible manual update

Let’s have the use case where “default” data load in the UI but you want the user to change them anyway. And as this is a UI, you must use rules. So this is only a partly-rule. At some point you want it to behave like a rule and at another point you don’t.

There are two ways:

  1. Define a new field in the entity, based on which you decide whether the rule will work or not and then put this field as a condition to the rule. E.g. IsManualPrice field in the invoice price line would define if the user is changing the price or not. The upside is that not only the rule (which will only evaluate if the flag is set to false) will work as expected, you also have a clear way how to see in your data that the price is rule based or manual. So the user will first have to mark the “manual” flag and then they would be able to change the price. It’s great to combine this with a row level security rule that reacts to the “manual” flag, too. The price firld is read only with manual=false and writeable when true. You will be grateful fot this approach later.

  2. A special case is when you want the rule to work when the user is editing the record through UI but want to keep data intact using subsequent actions as with every action all rules are re-checked and recalculated for many reasons. So you do not want to reload the customer’s address again at some point when the user could have changed it already. But you always want to reload it after the user changes the customer interactively.

    In such a case you do the following: Define a field dependency between the desired fields (in our case add a dependency to the address field pointing to the customer id) and make the address rule conditional, so it only evaluates if the address (yes the rule’s target field) is empty. The entity dependency will always reset the address field, so the rule will fire. Then the user can change the address freely and as it is filled in, it won’t be touched again. Not in the UI and not by any subsequent actions.