Business rules – logic that runs with every record¶

This chapter explains what business rules are, when each kind of rule runs in the life of a record, in which order rules run and how the Business Logic view of an entity shows all of this at a glance. Every kind of rule has its own reference page, linked from the table in section 1.

It is intended for administrators who configure the logic of a nexxcite application.

1. Business rules at a glance¶

Summary¶

A business rule is a piece of logic that nexxcite runs by itself for the records of one entity. Nobody calls a rule explicitly – changing, creating or saving a record triggers it.
Every rule belongs to exactly one entity. Its fields, conditions and values always refer to the record of that entity that is being edited.
Most rules work on one field: they set its value, check it or make it mandatory. Event based rules start an action instead.
A rule can be switched off with "Disabled" without deleting it.

The kinds of rules¶

Kind	What it does	When it runs	Reference
Default value	Fills a field of a new record	Once, when the record is created	Default value rule
Calculation	Computes a field from other fields or related records	Whenever a field or relationship it depends on changes	Calculation rule
Set before save	Writes a field on every save	Immediately before the record is written	Set before save rule
Required for save	Refuses the save while a field is empty	When the record is saved	Required for save rule
Expression validation	Accepts a value only if a condition is true	When the field is set	Expression validation rule
List validation	Restricts a field to a fixed list of values and offers them for selection	When the field is set	List validation rule
Lookup validation	Restricts a field to values from records of another entity and offers them for selection	When the field is set	Lookup validation rule
– Population rule	Fills further fields from the record a lookup found	Part of a lookup validation rule	Population rules
– Sorting rule	Orders the values a lookup offers	Part of a lookup validation rule	Sorting rules
Event based UI action	Runs an action in the user's session	When a field changes, before or after the save	Event based UI action rule
Event based background action	Runs an action as a background job	After the record was saved	Event based background action rule
Event based workflow	Starts a process per record that waits for a time or a change and runs actions	When the record is saved with a matching change, then at the time it waits for	Event based workflow rule
Threshold based background action	–	Not executed in the current version	Threshold based background action rule

Threshold based background action rules exist as a rule type, but nexxcite does not execute them and the editor does not offer them. Use an event based background action rule or a scheduled action instead.

Which rule for which requirement?¶

You want to …	Use
prefill a field when a record is created, and let the user change it afterwards	Default value
keep a field up to date while other fields change (totals, durations, statuses)	Calculation
stamp a value at the moment of saving (for example "last changed by")	Set before save
make a field mandatory, always or under a condition	Required for save
reject values that break a rule (ranges, formats)	Expression validation
offer a fixed set of values	List validation
offer the values of another entity and copy details from the selected record	Lookup validation with population rules
react in the user interface when something changes (dialog, navigation, further changes)	Event based UI action
run follow-up processing on the server after a save (mails, records in other entities)	Event based background action

2. Creating and editing business rules¶

Where business rules are created¶

Admin Studio → Entities → entity: the group Business Rules in the second column lists the rules of the entity. The + next to the group opens the business rule manager for this entity.
Admin Studio → Automation → Business Rules: all rules of all entities, grouped by entity.
The Business Logic view of an entity (section 8): "+ Add rule" or the + of a rule kind.

In the business rule manager, one button per kind creates a new rule: "Required For Save Rule", "Default Value Rule", "Calculation Rule", "Set Before Save Rule", "Expression Validation Rule", "List Validation Rule", "Lookup Validation Rule", "Event Based UI Action Rule", "Event Based Background Action Rule" and "Event Based Workflow Rule". A rule is always created for the entity selected in the manager. The kind of a rule cannot be changed later.

Settings every rule has¶

Setting	Meaning	Default
"Display Name"	Name of the rule in lists and in the Business Logic view	empty
"Description"	Free text for administrators	empty
"Tags"	Keywords for filtering in the Admin Studio	none
"Disabled"	The rule is ignored at runtime. Use it to switch a rule off temporarily instead of deleting it.	off

The settings of the individual kinds are described on their reference pages. Fields and conditions are expressions (see Expressions); in the editor you can either pick a stored expression or define one directly in place.

When changes take effect¶

A saved rule is published like any other definition and applies to every operation that starts afterwards. While you work in a sketch, the rule only applies inside the sketch (see Sketches).

A record that is already open in a form keeps the required for save and validation rules it read when it was opened. Close and reopen the record to work with the changed rules.

Permissions¶

Task	Permission
Open the business rule manager	"Open Business Rules Manager"
Create, change, delete rules	"Add Business Rules", "Edit Business Rules", "Delete Business Rules"
Open the Business Logic view	"View Entity Business Logic Overview"

By default, only system developers have these permissions (see Roles and permissions).

3. When rules run – the life of a record¶

Creating a record¶

When a new record is created – in a form, by an action, through the REST API – nexxcite runs in this order:

Calculation rules that depend on a field with the setting "Run Business Rules on load".
All default value rules. Each value that is written counts as a normal field change (see "Changing a field" below) – it is validated and can trigger calculations and event based rules.
Calculation rules with "Trigger on record creation".

Event based UI action rules with the timing "On Change" run during steps 1–3, each time a field their trigger matches is set – once per change. They do not run a second time when the record is complete.

Opening an existing record¶

Only the calculation rules that depend on a field with "Run Business Rules on load" run (see Calculation rule). No other rule runs when a record is opened. A value that such a calculation changes is a change of the record like any other and is saved with the next save.

Changing a field¶

Whenever a field gets a new value – typed by a user, set by an action, a rule, an import or the REST API – nexxcite runs:

Validation of the new value with the expression, list and lookup validation rules of the field. If no applicable rule accepts the value, the previous value is restored and nothing else happens. Should the rules reject the previous value as well – it was stored before a rule was tightened – the field is marked as invalid and the record cannot be saved until it holds an accepted value. A lookup rule that found a record fills its population fields.
Lookup validation rules of other fields whose selectable values depend on this field apply their "Limit Behavior".
Calculation rules that depend on this field, and calculation rules that read a relationship whose records depend on this field.
Event based UI action rules with the timing "On Change" whose trigger matches, ordered by "Priority".
Event based background action rules whose trigger matches are noted. They run only after the next successful save.

Setting a field to the value it already has is not a change: nothing of the above runs.

Saving a record¶

Event based UI action rules with the timing "Before Save", ordered by "Priority". If an action ends with an error, the save is aborted and the following rules do not run.
Required for save rules and fields with an invalid value are checked. If a required field is empty, the save is refused. Required fields that a set before save rule fills are left out here.
Related records that are saved together with this record are saved (with their own rules), and attached files are stored.
Set before save rules write their fields. Then the required fields they fill are checked; if one of them is still empty, the save is refused.
The record is written to the database.
Event based UI action rules with the timing "After Save" whose trigger matches a field this save wrote. An error is reported to the user but does not undo the save.
Event based background action rules noted since the last save are handed to the background processing.
The history action of the entity runs, if one is configured.

Deleting a record¶

No business rule runs when a record is deleted. Only the delete permission and the delete limits of the user's roles are checked. If something has to happen when a record is deleted, put it into the action that deletes it.

What the user sees¶

Situation	What the user sees
A value is rejected by a validation rule	The field shows its previous value again. No message is shown.
The previous value is rejected as well	The field shows it, but the save is refused with "Error occurred while saving" and "The value … is not valid for field …"
A required field is empty while the form is open	The field is highlighted, unless the form switches this off.
The save is refused because of required fields	"Error occurred while saving" with "Field(s) … must be filled in for …"
A Before Save action ends with an error	"Error occurred while saving" with the name of the rule and the error messages of the action
An After Save action ends with an error	"The record was saved, but a follow-up rule failed" with the name of the rule and the messages
A background action fails	Nothing in the form. The run is listed under Admin Studio → Monitoring → Background Processes.

4. Where rules run: in the session or in the background¶

Rule	Where it runs	Consequence
Default value, calculation, set before save, validations, required for save	In the operation that changes or saves the record	They work the same way in forms, actions, background jobs, mailbox listeners and the REST API.
Event based UI action	In the operation that changes or saves the record, synchronously	In a form, the user waits for the action and the action can open dialogs or navigate. When the record is changed by a background job or the REST API, there is no user interface: commands that need one cannot work there.
Event based background action	As a separate background job after the save	The user does not wait. The job runs under a configured user and is listed in the execution history.

Recommendation: use an event based UI action rule only for logic that belongs to working in a form. Logic that must run no matter where a change comes from belongs into an event based background action rule.

5. Order of execution¶

Between the kinds, the order of section 3 applies. It is fixed and cannot be changed.
Event based rules of the same timing run by "Priority", ascending: a rule with priority 1 runs before a rule with priority 5. Rules with the same priority run in no defined order.
All other kinds have no priority. Two default value rules or two calculation rules run in no defined order. Do not build logic in which one of them must run before the other – instead, compute the value in one rule, or let the second rule depend on the field the first one writes (a calculation runs again when a field it depends on changes).
Several validation rules on the same field are alternatives: the value is accepted as soon as one applicable rule accepts it. An empty value is always accepted.
Background actions are handed to the background processing in priority order. They then run as independent jobs; in our assessment you should not rely on the order in which they finish.

6. Triggers of event based rules¶

Event based UI action rules and event based background action rules have a list of triggers on their tab "Triggers". The + adds a trigger; the rule runs when any one of its triggers matches. A rule without triggers never runs.

"Event Type"	The rule runs when …	Further settings
"Any Change"	any field of the record changes	–
"Any Field Change"	the selected field changes, whatever the values are	"Field"
"Change From Value"	the field changes away from a value	"Field", "From"
"Change To Value"	the field changes to a value	"Field", "To"
"Change From/To Value"	the field changes from one value to another	"Field", "From", "To"
"None"	never	–

"From" and "To" are expressions. Their result is compared as text and without regard to upper and lower case with the value the field stores. Compare with what is stored – for a lookup field this may be a code or a record id, not the text the user sees.
The "Execution Condition" on the tab "Action" is checked after a trigger matched. The rule only runs while it is true. Use it for conditions on other fields; a condition on the changed field itself belongs into the trigger.
For the timing "Before Save", a field trigger matches when the field was changed since the record was last saved. For "From", the value at the last save counts. "Any Change" matches on every save, also when nothing was changed.
For the timing "After Save", a field trigger matches when this save wrote the field. For "From", the value before the save counts, for "To" the value that was saved. "Any Change" matches on every save.

Example: A ticket rule should run when the status changes from "New" to "In progress". Trigger: "Change From/To Value", field Status, "From" = New, "To" = In progress (if the field stores these texts).

7. Execution limits and loops¶

Limits you can configure¶

Limit	Where	Effect
"Disabled"	every rule	The rule does not run at all.
"Execution Condition"	event based rules	The rule only runs while the condition is true.
"Execution Limit"	event based background action rules	`OnlyOnCreation`: only for changes while the record is new. `OnlyOnUpdate`: only for records that already exist.
"Condition"	list and lookup validation, required for save	The rule only applies while the condition is true.

An event based background action rule starts at most one job per save, even if several of its triggers matched or the field changed several times.

"Max Executions" limits how often the rule runs for the same record in total (0 = unlimited). nexxcite counts every start of the rule per record in a table of its own, so the count survives the retention of the execution history and goes with the record when it is deleted. LimitedNumberOfTimes behaves like None; only "Max Executions" limits the runs.

Loops¶

A loop occurs when rules keep triggering each other: rule A writes a field that triggers rule B, and rule B writes a field that triggers rule A again. nexxcite protects against some, but not all loops:

A calculation rule does not trigger itself through the value it has just written.
Setting a field to the value it already has does not trigger anything. A chain of rules therefore ends as soon as the values stop changing.
While the calculation rules of a relationship run, their own writes do not start them again.
A general limit applies to every chain of field changes. A change and everything it starts – validations, calculations, the actions of On Change rules, the calculations of a parent record that reads the changed record through a relationship – form one chain. Within it, the same rule may set the same field of the same record at most 5 times nested in its own changes, and at most 50 changes may be nested within one another. A change beyond these limits is not made: the field keeps its value, and the skip is written to the application log. Changes that run one after another – an action that sets several fields that all start the same calculation – do not count as repetitions.

Both limits can be changed in the configuration of the application (BusinessRuleRuntime, see Installation and configuration). Two rules that write each other's trigger fields with values that keep changing – for example "B = A + 1" and "A = B + 1" – are stopped by them, but the values they leave behind depend on where the chain was cut off. Avoid circular dependencies; the Business Logic view shows them as follow-up triggers (section 8).

8. The Business Logic view of an entity¶

The Business Logic view draws all business rules of an entity on one canvas, in the order in which nexxcite executes them. It is generated from the definitions and is always up to date.

How to open it: Admin Studio → Entities → entity → Business Logic. It requires the permission "View Entity Business Logic Overview".

What the canvas shows¶

The canvas is divided into columns, one per phase in the life of a record:

Column	Sub-title	Contains
"Create"	"Record is created"	Default values, calculations with "Trigger on record creation", UI actions "On Create" (not executed)
"Open"	"Form is loaded"	Calculations that run because of "Run Business Rules on load", UI actions "On Open" (not executed)
"Field changes"	"While editing"	Validations, calculations, UI actions "On Change", background actions, workflow processes
"Before save"	"Check and complete"	UI actions "Before Save", required fields, set before save
"After save"	"Record is written"	UI actions "After Save"
"Scheduled"	"Without a form"	Threshold based rules – shown like active rules, although they are not executed

Each rule appears as a row of three cards: the trigger (what starts it), the rule and its effect (for example "Sets the field value", "Blocks saving", "Action: …"). A rule that depends on several fields appears once per field, so each trigger shows everything it starts. Colours distinguish rules that set values, rules that can block the save, UI actions, background actions and disabled rules.

Working with the view¶

Element	Purpose
"Field" filter	Shows only the rules that read, write or check one field ("All fields" shows everything).
"Show follow-up triggers"	Draws dashed lines from a rule that writes a field to the rules that this field triggers again. This is how you find chains and loops. Only the first ten lines are drawn.
"−", "+", "Fit"	Zoom out, zoom in, fit the canvas into the window.
"Edit entity"	Opens the entity editor.
"+ Add rule"	Opens the business rule manager of this entity.
"Data model"	The entity and the entities related to it, with the number of their rules. A click opens their Business Logic view.
"Rule kinds"	Number of rules per kind; the + creates a new rule of that kind.
Click on a rule	Shows its details in a side panel; "Open in editor" opens the rule.

Notes at the bottom of the panel tell you if rules could not be placed on the canvas or if not all follow-up triggers are drawn.

9. Frequently asked questions¶

Does a business rule run when a record is changed through the REST API or by a background job? Yes. All rules run wherever a record is changed or saved. Event based UI action rules run as well, but without a user interface (section 4).

Can a rule react to a record being deleted? No. No business rule runs on deletion.

Can a value written by a rule satisfy a required field? Yes, if it is written before the check: default values, calculations and Before Save UI actions do. No for set before save rules: the required fields are checked before they run.

Can I control the order of two calculation rules? No. Only event based rules have a priority. Design calculations so that each depends on the fields it reads; nexxcite then runs the second one when the first has written its field.

A value is rejected without any message. Why? A validation rule of the field did not accept it, and nexxcite restored the previous value. Check the validation rules of the field in the Business Logic view with the "Field" filter.

Why does my rule not run? Check in this order: is it "Disabled"? Does it have triggers or trigger fields? Is its "Execution Condition" true? Does the trigger compare with the stored value rather than the displayed text? For event based UI action rules: is the timing "On Change", "Before Save" or "After Save" – and does an "After Save" rule use the trigger "Any Change"?