Rule Rule Set Business Objects

Introduction

In an Application, Business Rules allow handling decisions based on a specific situation or users' data, e.g. determining which documents should be printed at the end of an onboarding process. Business Rules take the form of Decision Trees. A Decision Tree starts with a root node, and from the root node decision paths ascend to the leaf nodes of the tree. The leave nodes are actions that are executed if all conditions in the path are true, while the intermediate nodes which build the decision path are condition-, loop- and scope-nodes.

The Business Objects involved in the rule handling are Rules, and Rule Sets.

Rules may be organized in a Rule Set. Rule Sets, in turn, can contain both Rules and additional Rule Sets. When executing a Rule Set, each Rule which is part of the Set — or part of one of its included Rule Sets — is evaluated once. The order of Rule evaluation is the order in which the rules are listed in the Rule Set.

Rule Handling

Rule

The Rule Business Objects are managed in the Business Object Library. The list of available Rules is displayed in the central area of the Studio screen.

Creating a Rule

Right-click on Rule in the Library, and choose New Rule from the context menu. Alternatively right-click an existing Rule and select New Rule from the context menu.

A dialog opens. Give a unique ID for the Rule, enter a name and give a description if needed. Click on the Save button to save the rule.

Editing a Rule

The default properties ID, Name and Description, can be edited in the Properties tab on the right side of the Studio screen. Select a Rule in the central area to edit default properties.

To open the Rule Editor in a new window, right-click a Rule and choose Open In Editor. Alternatively double click the Rule.

Deleting a Rule

Right-click the Rule you wish to delete and choose Delete. If the object can be deleted — that is, no dependencies for the object exist — a dialog box opens to confirm deletion.

If there are still dependencies on the object the deletion cannot be performed. You must first make sure that the object does not have any incoming (Used by) dependencies, i.e. that no other Business Objects use the Object you are trying to delete.

Rule Set

The Rule Set Business Objects are managed in the Business Object Library. The list of available Rule Sets is displayed in the center frame of the Studio screen.

Rule Sets are container objects which may contain Rules and other Rule Sets.

Rule Editor

The Rule Editor allows composing a Rule to meet your business needs.

A Rule is, basically, a decision tree. The tree may start with a root Scope, although it is not necessary as variables can be assigned in the Variablestab.

Note on Rules created in Appway 10.1 and lower: A root Scope was added by default in Appway 10.1. and lower, therefore all Rules created in versions previous to 11 will still display this item. However, you can manually remove it through the context menu by clicking on the Remove, Keep Children button.

The leaf nodes of the decision tree are Actions that must be executed, while the intermediate nodes that build the decision path are Branches, Conditions, Loops (For, For Each) or Scopes. The Rule Editor is divided into four resizable areas:

1. Dependencies
2. Composition Area (includes the Variables tab)
3. Components Library
4. Property Editor

Dependencies

The left side of the Editor displays the dependencies. Double-clicking on a dependency entry opens the corresponding Business Object in its Editor.

Composition Area

The elements displayed in the Composition Area define the rule. Each element is a node in the decision path.

Changes to the decision tree can be made using drag-and-drop. When you start dragging an element, the areas where you can drop your element (called "drop targets") are displayed as gray boxes. When you drag an element over a drop target, this changes its color to blue, indicating that the element can be dropped.

Following is a list of possible actions in the Composition Area:

• Add a new element — You can add a new element to the decision tree by dragging and dropping the desired element from the Components Library to a drop target in the decision tree.
• Move an element — You can move an element by dragging it to its new location. Moving an element is the default drag behavior.
• Copy an element — You can copy an element by dragging it to its new location and pressing the Alt key when dropping the element. The copy operation includes all of the descendants of the element you are dropping. Alternatively, you can right-click an element and select Copy. Paste by right-clicking an element and selecting Paste Before, Paste Inside, or Paste After to define the exact location to paste to. This method also supports copying and pasting between different Rule Business Objects.
• Delete an element — Select the element and press the Delete key or select and right-click the element and choose Remove from the menu. The delete operation removes the selected element and all of its descendants.
• Deactivate an element — Select the element and choose Deactivate from its context menu. Elements that are deactivated prevent the evaluation of the decision path, that is, the element and its children are ignored.
• Edit the properties of an element — Select the element. Its properties are displayed in the Property Editor below the Composition Area.

Variables Tab

The Variables tab allows defining variables to be used in the elements of the decision tree. You can only define variables of typeLocal and Assigned from the Variables tab.

The Scope element still allows defining variables of type Local and Inherited.

Components Library

The Components Library shows the Business Objects and Rule Elements that can be dragged into the Composition Area. When selecting one of these elements in the Composition Area, you can edit its properties in the Property Editor below.

Rule Elements

The following sections illustrate the Rule Elements displayed in the Components Library and their properties.

Scope

A Scope Rule Element allows structuring the Rule visually and defining variables to be used in the descendant elements. The variables defined in a Scope node will be visible in all the child nodes of the Scope itself.

The properties of the Scope Rule Element are:

• Label — Text displayed above the element in the Rule Composition Area.
• Active — If selected, the element is active; if deselected, the element is inactive.
• Scope name — Name of the Scope
• Variable Definition — The Scope variable definitions, accessible from the Scope sub-elements. Only Local and Inherited variables can be defined. The Scope Element context menu also allows the following option:
• Toggle Children Visibility — Convenience option to show/hide all nested child elements in the editor.

For

A For Rule Element allows defining a loop in a Rule. The For Rule Element defines the Integer loop variable and evaluates its child elements. Each of the loop's iterations increments the given loop variable by the given increment value. The re-evaluation of the elements attached to a For Rule Element will continue as long as the loop variable is smaller than the End value. The loop variable is visible to all child nodes of the For Rule Element.

The properties of the For Rule Element are:

• Label — Text displayed above the element in the Rule Composition Area.
• Active — If selected, the element is active; if deselected the element is inactive.
• Variable — Name of the loop variable.
• Start — Start value of the loop variable.
• End — End value of the loop variable.
• Increment — Value added to the loop variable at the end of each loop iteration.

The For Rule Element context menu also allows the following option:

• Toggle Children Visibility — Convenience option to show/hide all nested child elements in the editor.

For Each

A For Each Rule Element allows defining a loop in a Rule. While a For Rule Element defines a loop of an Integer value over a given Integer interval, a For Each Rule Element allows the user to define a loop over a collection of objects.

The re-evaluation of the elements attached to a For Each Rule Element will continue as long as there are unvisited items in the loop object collection. There will be as many iterations as elements in the given Collection, and each iteration will use one element from the Collection. The loop variable is visible to all child nodes of the element.

The properties of the For Each Rule Element are:

• Label — Text displayed above the element in the Rule Composition Area
• Active — If selected the element is active, if deselected the element is inactive
• Variable — Name of the loop variable
• Variable Type — Type of the loop variable
• Collection — Collection of elements that will be traversed in the loop
• Loop Counter — Name of a variable of type Integer to be used to get the current iteration number inside the nested elements.

The For Each Rule Element context menu also allows the following option:

• Toggle Children Visibility — Convenience option to show/hide all nested child elements in the editor.

Branch

The Branch Rule Element is used to fork the condition paths of the decision tree.

The Branch Rule Element can only have children of type Condition. Two modes of executions are supported:

• Execute All — Executes all child elements of the Branch Rule Element
• Until First 'True' — Stops the execution of the child list when the first child condition that evaluates to true is met

The properties of the Branch Rule Element are:

• Label — Text displayed above the element in the Rule Composition Area.
• Active — If selected, the element is active; if deselected, the element is inactive.

The Branch Rule Element context menu also allows the following option:

• Toggle Children Visibility — Convenience option to show/hide all nested child elements in the editor.

Condition

The Condition Rule Elements represent the actual decisions in the tree. The expression associated with a Condition Rule Element must return a boolean value. If the value is false, the execution of the child elements is aborted.

Like the Branch Rule Element, the Condition Rule Element supports two modes of execution:

• Execute All — Executes all child elements of the Condition Rule Element.
• Until First 'True' — Stops the execution of the child list when the first child of type Condition that evaluates to true is met.

Note: The Condition Rule Element can have children of any type. If Until First 'True' execution is activated, only the child elements of type Condition are taken into account for aborting evaluation. All other child elements are executed as long as no Condition has returned the value true.

The properties of the Condition Rule Element are:

• Label — Text displayed above the element in the Rule Composition Area.
• Active — If selected, the element is active; if deselected, the element is inactive.
• Expression — Boolean expression of the condition; it determines whether the path must be followed further or the evaluation of the path can be aborted.
• Description — Text description of the expression.

The Condition Rule Element context menu also allows the following option:

• Switch Negation — When the option is set, a letter N is shown on the condition and the evaluated condition is negated.
• Toggle Children Visibility — Convenience option to show/hide all nested child elements in the editor.

Actions

The Action element is the leaf node of the decision tree. It is the last element in the decision path. If an Action is met during the evaluation of a Rule, the action is executed. The result of the action execution may be a data entity of type "Action." When an action produces an "Action Data Entity," this data entity is added to the list of already generated Actions (See more information about Action lists in the Best Practices section).

DataClass Action Begin
2       // the type of the action, i.e. outputform, inputform, etc.
3       Property[type, String, None];
4       // id of the element representing the Action being returned, i.e. id 1234, may be null
5       Property[source, Any, None];
6       // map of parameters list of parameters
7       // handles action parameters of different action types
8       Property[params, String, Named];
9       // (deprecated) map of expressions used for variable assignments
10       Property[expressions, String, Named];
11       // map of data entities that can directly be used for constant parameter bindings
12       Property[bindingValues, Any, Named];
13       // (for Data Actions only) the Data Class Instance or Primitive value that is returned by the Action
14       Property[dataResult, Any, None];
15       End

Document

The result of the Document Action is an instruction to determine which document must be generated. The resulting Action object has the type "outputform."

The properties of the Document Action are:

• Label — Text displayed above the element in the Rule Composition Area.
• Active — If selected the element is active, if deselected the element is inactive.
• Description — Human-readable description.
• Document — ID of the Document that must be generated.
• Document title — Expression that returns the generated document title.
• PDF language — Expression that returns the language code that must be used for document generation.
• Text language — Expression that returns the language code that must be used for document content translation.
• Copies — Number of copies of the document that must be generated. The default is 1, meaning that there is one instance of the document generated.
• Report Text Pattern — This is relevant in the context of custom actions from the Actions extension when using the RULETEXT function. In short, this field allows specifying a pattern for the text to be extracted for a given Rule Business Object. If provided, the given text pattern is used, otherwise the default value Execute Action <action.function> is applied.
• Variable Assignments — (Variable Assignments tab) List of variables that can be assigned in order to specify the document content.

Screen

The result of a Screen Action is an instruction to determine which Screen must be displayed. The resulting Action object has the type "inputform."

The properties of the Screen Action are:

• Label — Text displayed above the element in the Rule Composition Area.
• Active — If selected the element is active, if deselected the element is inactive.
• Description — Human-readable description.
• Document — ID of the Document whose Screen must be displayed.
• Screen — ID of the Screen that must be displayed.
• Document title — Expression that returns the Screen title.
• Report Text Pattern — This is relevant in the context of custom actions from the Actions extension when using the RULETEXT function. In short, this field allows specifying a pattern for the text to be extracted for a given Rule Business Object. If provided, the given text pattern is used, otherwise the default value Execute Action <action.function> is applied.

Script

The Script Action does not produce a result by default. The user determines the effect of the Script Action by writing a Script which is executed when the Script Action is triggered.

The properties of the Script Action are:

• Label — Text displayed above the element in the Rule Composition Area.
• Active — If selected, the element is active; if deselected, the element is inactive.
• Description — Human-readable description.
• Script — Script that must be executed if the action is triggered.
• Report Text Pattern — This is relevant in the context of custom actions from the Actions extension when using the RULETEXT function. In short, this field allows specifying a pattern for the text to be extracted for a given Rule Business Object. If provided, the given text pattern is used, otherwise the default value Execute Action <action.function> is applied.

Data

The result of a Data Action is a Data Class Instance or Primitive Value. The resulting 'Action' object is of type 'Data'.

The properties of the Data Action are:

• Label — Text displayed above the element in the Rule Composition Area.
• Active — If selected, the element is active; if deselected, the element is inactive.
• Description — Human-readable description.
• Result — The Script that returns the desired Data Class Instance or Primitive Value. Note that each Data Action must return one single Data Class Instance or Primitive Value. If multiple elements must be returned, you can use multiple Data Actions or a For/ForEach loop. If this script is empty or returns null or nothing, no Action 'object' is returned for the Action.

Consider the following information:

• The Data Class Instance or Primitive Value returned by the Action are available in the dataResult property of the resulting Action 'object'.
• The Data Class Instance or Primitive Value returned by the Action must be compatible with the Return Type.

Property Editor

Return Type

Each Rule has a Return Type (Return Type tab), which defines the type of the result returned by the Rule. This setting clearly defines what the Rule exposes as an interface to its consumers.

The Return Type tab allows specifying the following properties:

• Collection Type — Specifies whether the Rule returns one single value (Single Element) or multiple values (Indexed Elements). Note that, if you set Single Element, the execution of the Rule stops at the first Action that returns a result, and the following Actions are not executed.
• Type — Specifies the type of result among the available Data Classes and recommended Primitive Types.

The default value for the Return Type is Indexed Action, which allows using any type of 'Rule' Actions with no restriction. If a different Return Type is specified, only the following Actions can be used in the Rule (if other Actions are found, the Rule execution fails):

• 'Rule' Actions with a compatible Type value (exactly the same type or a child Data Class)
• 'Data' Actions that return a Data Class Instance or Primitive Value whose type is compatible with the Return Type of the Rule (see Data Actions section)
• 'Script' Actions

Best Practices

Evaluating Rules

Evaluating Rules via Script Language

Rules can be evaluated using the script functions EVALUATERULE or EVALUATERULESET. The result of either of these functions is an indexed collection of Action data entities. This collection contains all Actions that have been triggered during the evaluation of the rules.

Local Indexed Action $actions;
2    // evaluate a rule set
3    $actions := EVALUATERULESET($ruleSetId);
4    // evaluate a single rule
5    $actions := EVALUATERULE($ruleId);

Evaluating Rules inside a Process

Rules can be evaluated inside a Process by assigning variables through the Evaluate Rule Activity. More information can be found in the aProcess Business Object article.

Rendering PDF Documents

To render PDF documents, you need to create a list of Outputform Actions and hand this list over to the GENERATEPDF function.

Script
2       // the actions produced by the rules
3       Local Indexed Action $actions;
4       // the render configuration
5       Local PdfRenderConfiguration $config;
6       // generated document's location
7       Local String $location;
8       // create a default configuration
9       $config := NEW(PdfRenderConfiguration);
10       // evaluate the rules
11       $actions := EVALUATERULESET($ruleSetId);
12       // generate the document
13       $location := GENERATEPDF($actions, $config);
14    End