Applies to version 2016.1.x; Author: Jacek Język
Newly featured in the 2016 version of WEBCON BPS are Business Rules, which enable the creation of universal expressions and conditions to control the behavior of processes.
Rules can be created using the visual editor by dragging and dropping the appropriate items available from the menu on the right.
The business rules editor also enables use of constants, form fields, values entered directly into the editor, and other business rules that return values. In this way, users can create complex expressions that operate using all these values.
Business rules can be used in conditions determining:
- Visibility and editability of form fields.
- Visibility of transition paths on steps.
- Execution (activation) of actions.
- Path selection in “Workflow control” type steps
- The default value of a form field.
Invoking a business rule results in the return of a specific value. This could be a string, decimal, Boolean value, date or user list.
The returned value type must be configured depending on where the rule is used, and the expression defined in the rule. If the rule should calculate a date, then the returned data type should be set to Date.
The business rules engine allows for some freedom in configuring the returned data type, and automatically converts the values of one type to another. However, configuration of the correct data type facilitates quick diagnosis and detection of potential errors in created rules. During the evaluation of a rule, the engine verifies that the format of the returned value matches that of the set data type, and informs the user in case of a discrepancy. Such configuration is therefore strongly recommended.
Business rules can be edited in SQL edit mode, which enables definition of expressions using SQL or CAML.
This feature is analogous to that available in previous versions of WEBCON BPS, where Boolean expressions could be created using these scripting languages. SQL mode will not be described in this article. However, it is worth pointing out that SQL mode and Business rules mode work independently of each other, which means that switching between them will not result in conversion of an expression created in one to an expression in the other.
Business rules editor – useful tips
A useful feature of the business rules editor is the ability to test a defined expression without having to activate the entire process. Users can therefore quickly verify created rules, and check whether they work as intended.
In the example below, a rule has been created to verify the total value of the order (the quantity of ordered good multiplied by the unit value). If the value of the order exceeds the defined maximum value (the maximum value defined as a process constant), the rule will return the Boolean value “true“.
Filling in the Instance ID field for the given test and subsequently clicking “Show” will retrieve the values for the workflow instance with that ID and insert them into the expression.
Clicking the “Test” button will evaluate the rule and display the corresponding returned values.
It is also worth noting that every function available in from the menu has context-sensitive help with a short description of its operation and an example of its use. This feature is sure to help those new to the business rules editor.
If, when editing an expression, it becomes necessary to change operators (e.g. to the comparison operator), this can be done quickly without having to reconfigure the entire phrase. All you have to do is choose a new operator from the context menu to insert it into the expression.
Defining basic data types
With the business rules editor, users can easily define values which are used, for example, in the configuration of a form field and its default value. The principles according to which the values of specific types must be defined generally concern the business rules editor, and refer to all expressions created using the editor.
From version 2016.1.1.104 onwards, the editor will recognize syntax and format values in the following way: Floating-point value (blue color) Date (yellow color) Text (italic, does not require apostrophes)
In order to define a number, simply enter the required value (without commas separating thousands or any other symbols). Definition of a floating-point number requires the use of periods as decimal separators. Commas may not be used as separators.
Definition of a text value within a rule requires the use of an apostrophe at the beginning and end of the defined text.
From version 2016.1.1.104 onwards, the editor will recognize syntax and does not require apostrophes.
Business rules allow definition of dates in ISO 8601 format; however, also possible are the following formats: YYYY-MM-DD; MM/DD/YYYY. When defining the value of a date in one of the supported formats, using an apostrophe at the beginning and end of the defined string is not necessary.
If the date in a business rule needs to be transmitted in a different format, the TEXT TO DATE conversion operator must be used, which allows free conversion of text to a date in any format. Please be advised that in this case, both the date and the format to which it will be converted must be entered as text, and thus require the use of apostrophes.
True/False values can be defined in two ways. One is by directly entering true or false into the rule edit window. The other is by using predefined constants POSITIVE (true) or NEGATIVE (false), accessible from the rule menu on the right. Both notations are correct and yield the same effect in terms of rule operation. They can therefore be used interchangeably.
Correct use of variables representing Dates and Floating-Point Numbers
The business rules referred to earlier unambiguously interpret dates and floating-point numbers. For this reason, the values of dates and floating-point numbers must be defined in a certain way and transmitted in a specific format.
In case of dates, the recommended format is ISO 8601 (although other formats are also acceptable). An example of a date in this format is “2017-07-30T14:50”.
In case of floating-point numbers, the only possible format is a number without commas separating thousands, and periods (decimal points) as decimal separators. An example of such a number is “12500.89”.
Of course, business rules can use values found on the SharePoint form, from where they must also be obtained in the correct format. To make this possible, date form fields have access to an “ISO (Date Time)” variable, representing the ISO format,
whereas floating-point numbers have a “(number)” variable, representing the value in the correct standardized format.
This separates the operation of business rules from regional SharePoint settings used by the system, and thus avoids variations in date and number formats in different regions of the world.
Should it be necessary, conversion of values to text in other formats is of course possible. To do this, use the dedicated function to convert the date to any format…
…or to convert numerical values to text. Conversion is then made to a format compatible with regional SharePoint settings.
Operations for values of different types
The business rule editor allows creation of complex expressions through the use of arithmetic and logical operators, as well as dedicated functions. An example of an addition operation will illustrate the operational principles of the business rules engine, how different data types are converted, and how the values of form fields are interpreted.
All operators and functions of the business rules editor require entry of a specific type of value (text, number). Likewise, values returned by these functions are of a specific type. In certain cases (for example, in the addition operation), these functions allow entry of values in any format, but then their operation depends on the type of data used. Let us take a look at some examples of how this affects operation of the business rules engine.
The addition of two numbers will yield their arithmetic sum.
Entering numbers in text format (using apostrophes) will cause the operator to connect the two texts together.
More thorough explanation is required if one of the arguments has been provided in text form, while the second has been provided as a number. In this case, the result of the addition will depend on the values of the arguments provided.
As mentioned before, the business rules engine will automatically convert the value of one data type to another if necessary and possible. In the example below, the text containing the number will be converted to a number, and the sum of the two numbers will be returned.
This behavior of the engine is particularly significant when using business rules with variables referencing form field values, especially numerical ones. Floating-point form fields have multiple variables representing their values.
The result of the operation will differ depending on the type of variable used (text or number). To demonstrate this, we will use the Value form field, which is a number and contains the value of an order (6000.00). When using the (number) variable will, adding two value form fields together will yield 12000 as the result.
For the same form field, when we use the acc. SharePoint settings (text) variable, which returns the value in text form, the result of the addition is joined text.
As we can see, the result is totally different in each case. In the first case, the business rules engine received the value in a number format as a parameter for calculation; and in the second, a text representation of the same value. This is why the engine behaved differently, yielding an arithmetic sum in the first case, and joined text in the second.
The above example shows how important it is to understand the principles governing interpretation and conversion of types using the business rules engine.
The creation of conditions using the business rules editor requires use of the IF THEN operator, available in the editor toolbar under Functions->Conditional Choice. The IF THEN operator enables creation of conditions containing multiple levels of decision. To add another level to the condition, simply click the “plus” icon.
In case of multiple levels, conditions are checked one after another until one of them has been met. If none of the conditions have been met, the rule will return the value defined as ELSE.
The order of the conditions can be changed, as they can be moved up or down the tree by clicking the arrow icons.
Please keep in mind that the IF THEN operators, as well as the Comparison (<, >, <=, >=, =, <>) and Logic (AND, OR, NOT) operators require their input parameters to be Boolean values (POSITIVE, NEGATIVE).
The business rules engine will automatically convert the value of one data type to another if possible. If entry of Boolean values (POSITIVE, NEGATIVE) is required, such conversion is also performed. Conversion takes place according to the principles described below.
Text – Boolean values
Texts ‘1’ and ‘true‘ (case-insensitive) are treated as POSITIVE.
Texts ‘0’ and ‘false‘ (case-insensitive) are treated as NEGATIVE.
Every other text (e.g. ‘Category’) is interpreted as NEGATIVE.
Numbers – Boolean values
A value of 1 is treated as POSITIVE.
A value of 0 is treated as NEGATIVE.
All other numbers aside from 1 and 0 (e.g. 100) entered into fields where Boolean values are required will cause an error during business rule evaluation.
Dates – Boolean values
Dates are never converted into Boolean values. Entry of dates into fields where Boolean values are required will cause an error during business rule evaluation.
Rules with parameters and nested rules
When using business rules, it is possible to use the same definition of a rule multiple times and in many places in the process. A collection of defined rules is available in the rule editor menu (Divided into rules defined locally for each process, and global rules available for the entire system), where they can be selected and used directly, for example as a condition of form field visibility, or in creating a new, more complex rule. In this way, complex, multi-level expressions can be created based on existing rules.
A helpful feature when creating universal, reusable business rules is the ability to define Parameters that transmit specific values to those rules.
Let us see how these features can be used in practice by taking a look at a Requisition Process in which an order total is verified using a business rule.
We begin creating a rule by defining the “Amount to accept” parameter.
Then, in the business rule editor, we create an expression verifying whether the value transmitted in the parameter is lower than the threshold determining whether or not the order requires approval from the board. It is also worth noting that this order value threshold is not constant, but rather calculated by another rule called “Acceptance threshold”.
A rule created and saved in this way can be used in many places in a process. Among other things, this rule will determine the whether the “Supervisor opinion” form field is required, this field must be filled in by the supervisor if board approval is necessary. For this purpose, the entire rule is inserted into the visibility configuration of the “Supervisor opinion” form field on the appropriate step. The “Value” form field containing the total order value is transmitted as a parameter to the rule.
As a result of the operation described in such example, the supervisor will be required to fill in the “Supervisor opinion” field if the total value of the order (saved in the “Value” form field) exceeds the acceptance threshold, which is calculated using “Acceptance threshold” rule.