Event based UI action rule – run an action while the record is edited or saved¶
An event based UI action rule runs an action when a field changes, before the record is saved or after it was saved. The action runs directly in the operation that changes the record – in a form this is the user's session, so it can show dialogs or navigate. This page describes its settings and behaviour. It is intended for administrators who configure business rules.
1. At a glance¶
| Purpose | Runs an action synchronously when a trigger matches |
| Typical use | Ask the user a question when a status changes; fill several fields at once; check something before the save and stop it with a message |
| Related | Event based background action rule (runs on the server after the save), Actions |
2. Settings¶
The editor has three tabs.
Tab "General"¶
| Setting | Meaning | Default / required |
|---|---|---|
| "Disabled" | The rule does not run | off |
| "Priority" | Order among rules of the same timing, ascending: lower values run first | 0 |
| "UI Action" | When the action runs: "On Change", "Before Save" or "After Save" (see section 3). "On Create", "On Open" and "None" are offered but not executed. | "None" – must be set |
Plus "Display Name", "Description" and "Tags" in the header (see Business rules).
Tab "Triggers"¶
The list of triggers. The + adds one, the minus button removes one. The rule runs when any one of them matches; a rule without triggers never runs. Each trigger has an "Event Type" and, depending on it, a "Field", "From" and "To". The event types are described in Business rules, section 6.
Tab "Action"¶
| Setting | Meaning | Default / required |
|---|---|---|
| "Execution Condition" | Optional condition, checked after a trigger matched. The rule only runs while it is true. | empty – always |
| "Action" | The action that runs against the current record | required |
3. Behaviour¶
The timings¶
| "UI Action" | When the action runs | If the action ends with an error |
|---|---|---|
| "On Change" | Immediately when a field is set and a trigger matches – once per change. | The change stays. Further rules run. |
| "Before Save" | At the start of every save, if a trigger matches a field that was changed since the last save. "Any Change" matches on every save. | The save is aborted. Following Before Save rules do not run. The user sees "Error occurred while saving" with the name of the rule and the error messages of the action. |
| "After Save" | After the record was written, if a trigger matches a field that this save wrote. "Any Change" matches on every save. | The save is not undone. Following After Save rules do not run. The user sees "The record was saved, but a follow-up rule failed". |
- The action runs synchronously: the operation that changed or saves the record waits until it is finished.
- Several rules of the same timing run by "Priority", ascending.
- An action that only recorded an error message but finished normally does not count as "ended with an error".
- A Before Save action can still change fields of the record – for example fill a field that is required. The required fields are checked afterwards.
- If the "Execution Condition" refers to an expression that no longer exists, the condition is ignored and the rule runs. A rule without an action, or whose action no longer exists, is skipped. The reason is written to the application log.
New records¶
For a new record, an "On Change" rule runs when a default value or a creation calculation sets a field its trigger matches – once per change, like for every other change. It does not run a second time when the record is complete.
After Save¶
The triggers of an "After Save" rule are checked against the fields this save wrote, with the values before and after the save: "Change From Value" compares with the value the record had before the save, "Change To Value" with the value that was saved. The action runs afterwards, when the record is written; it can change the record and save it again.
Without a user interface¶
The rule also runs when the record is changed or saved by a background job, a mailbox listener or the REST API. There is no user interface then: commands that open dialogs, ask questions or navigate cannot work. For logic that must run regardless of where a change comes from, use an event based background action rule.
4. Examples¶
Confirm closing a ticket. "UI Action" = "On Change", trigger "Change To Value" on
Status with "To" = Closed. The action asks the user for a closing comment and writes it
into the field Resolution.
Stop the save above the credit limit. "UI Action" = "Before Save", trigger "Any Field Change" on Order total, "Execution Condition" = Order total > Credit limit of the customer. The action ends with the error "The order exceeds the credit limit of the customer". The save is refused, and the user sees this message.
5. Limitations¶
- "On Create" and "On Open" are offered in the editor but not executed. Use "On Change" with a trigger on a field that a default value rule fills, or a calculation rule with "Run Business Rules on load".
- An action that changes fields can trigger further rules and, in the worst case, itself again (see Business rules, section 7).