Overview
A basic Business Rule is composed of the following parts:
Name: A unique name for the business rule
Context: A developer-provided string that identifies the context in which a group of business rules are executed - see more details below
"If" Expressions: One or more expressions that are evaluated to determine if the Business Rule applies for a given set of data (These expressions are concatenated with AND logical separators)
"Then" Expressions: One or more expressions which are evaluated if all "If" Expressions are true
Module code fetches Business Rules (usually by a Context) and evaluates them using APIs in Java and Javascript - they can run in both the server and UI (only ExtJS pages are supported as of Neo 3.6).
Contexts
A Business Rule Context is registered by module code, and it has 1 or more Sub Contexts associated with it.
Each Sub Context:
contains a set of Variables
is associated with either a single record or multiple records
Through this structure, a Context can be used to represent any number of related Models, but they can also represent additional Variables not part of any Model, which allows rules to be more flexible.
Example #1
Let's say we want to develop a Context specifically for writing rules against the models Shipment & ShipmentLine.
Context: Shipment
Sub Contexts:
ShipmentHeader (single)
ShipmentLine (multiple)
What the user would see:
What these 3 Sub Contexts signify:
Shipment: "If" Expressions would use Variables from the ShipmentHeader level and be evaluated against a Shipment record
ALL ShipmentLine: "If" Expressions would use Variables from the ShipmentLine level and must evaluate to true for ALL ShipmentLines under a Shipment record
ANY ShipmentLine: "If" Expressions would use Variables from the ShipmentLine level and must evaluate to true for AT LEAST ONE ShipmentLine under a Shipment record
Support for Loops
Business Rules do not have support for loops through Functions (e.g. for() or while()). To evaluate an expression over N records, you must use the multi-Sub Context outlined above.
Expressions
Expressions make use of Variables and Functions to return some value. Every Expression has an associated Sub Context, and "Then" Expressions have some additional metadata associated with them, documented below.
The Expression itself has:
Variables: Provided by the Sub Context, these are populated at runtime when the Business Rule is evaluated
Functions: Functions which are implemented in Java and Javascript; some are globally accessible and some are created for a specific Context
Return Value: Values passed through Functions and returned by the Expression use simple types only (Integer, Boolean, String, Float, Double)
"Then" Expressions
As mentioned above, Expressions have the expression itself and also an associated Sub Context. "Then" Expressions have some additional metadata:
Rule Sub Type
Indicates what should be done with the expression result. There are a few different types:
Full Context Validation: The original type, this performs validation; the expression returns true or false. If the expression returns false for a record, an error (see Validation Error below) is associated with the record in the result.
The following are field-specific, and require the Field (see below) to be populated:
Field Validation: Similar to Full Context Validation, except the error applies to a specific field from the associated Sub Context. This is used in the UI to provide field-level error messages for a better user experience.
Field Editability: Sets a mask for a specific field. The expression should return one of the following values:
"REQUIRED": The field is editable and required
"OPTIONAL": The field is editable and optional
"IGNORED": The field is non-editable
Field Enumeration Rule: Designed to be used specifically with enumeration fields, which have a fixed set of values. The expression should return a string which is a subset of one or more enumeration values, separated by comma. In the UI, the field will limit its dropdown options to those returned by the rule (if it's active).
Field Default Value: When the rule is active and the field is empty, it will set the return value of the expression as a default value.
Field Computed Value: When the rule is active, it will set the return value of the expression as the field's value, and the user cannot change it.
Field
The name of a field from the associated Sub Context for this "Then" Expression. This is required if one of the field-specific Rule Sub Types above are used.
Validation Error
If the Rule Sub Type is "Full Context Validation" or "Field Validation", this can be used to optionally specify the validation error message that the user will see. If this is not populated, the Description on the Business Rule is used as a fallback.
Example #2
Here's a simple example of a Business Rule running inside a Create Site page (left). The rule configuration is shown on the right - note that this is not the real Business Rule UI, it's a simplified demo which hides the Context / Sub Context concept.
