Arithmetic operations in form fields

Applies to version: 2022 R4 and above; author: Łukasz Maciaszkiewicz

Introduction

In WEBCON BPS system applications, processing values entered by end users in forms is a fundamental function, alongside data gathering and analysis. The system offers several solutions to quickly and easily define arithmetic operations on values entered in form fields. This article provides examples on how to configure form fields to execute operations and display their results.

NOTE: this article does not cover the configuration of the : ”Item list” form field, which includes a special column type called “Calculated floating-point value” that allows users to define arithmetic operations quickly. Detailed information on the “Calculated floating-point value” column is available here: https://community.webcon.com/posts/post/using-calculated-columns/196

Rule editor

You can easily create arithmetic operations in the WEBCON BPS system using the rule editor. To access the rule editor, click the ellipsis button in the upper-right corner of the fields where you can enter rules. This tool is not required to create arithmetic operations, but makes it much easier, especially in the case of more complex operations.

The rule editor window

The rule editor window provides four tabs: “Operations”, “Functions”, “Values”, and “Objects”. With those you can quickly choose and add various elements to the rule by double clicking or dragging and dropping. Such elements can be also added directly in the edition field – when entering the characters a context menu appears that suggests elements whose name starts with characters entered.

Note that for a number of elements contained under the “Operations” and “Functions” tabs, it is required to insert specific values or elements (chosen, e.g. from the “Values” or “Objects” tabs). Such elements must be inserted inside the square brackets with attention being paid to preserving the sequence required by a selected function or operation.

An example of the “Set Focus” function inserted in the edition field – it is necessary to insert a chosen form field inside the square bracket.

Detailed information on specific functions and operations that can be accessed in the rule editor is available in the following article: https://community.webcon.com/posts/post/function-dictionary-for-business-rules-and-form-rules/237.

Business vs form rule

For the purpose of this article, form rules are used to execute arithmetic operations in the presented examples. It is one of the possible methods, but not the only one – a different one is to use business rules. There are certain differences between the aforementioned rule types. Those are discussed in the article linked above. In general, you need to be aware that the business rules are more “rigid” in nature and cannot be changed by the end user in any way. A set of rules defined by the administrator is in such case applicable not only to the content of the form, but also to all system elements, e.g. actions, starting new instances, etc.

On the other hand, form rules generally form more flexible framework and give end user more freedom. The rules, which apply only to the form, potentially enable experienced end users with sufficient knowledge to make their own modifications through a console.

Thus, the primary distinction between the first and second approach revolves around the issue of increased control and safety. When dealing with sensitive data, it is advisable to utilize business rules for enhanced data security. Conversely, for situations where data safety is not the top priority and the focus is on optimizing the user experience, form rules may be more suitable.

Example 1: summing up values from the form fields

In the discussed example, the application form contains three “Floating-point number” form fields. Of the three fields in the form, two ("Field 1" and "Field 2") are designed to collect numerical values inputted by the user, while the third field ("Total") calculates the sum of these values.

Window of a demonstrative form

To create a form rule that performs an arithmetic operation, launch Designer Studio and select the form field that will be used in the operation. In the example being discussed, the procedure is applied first to the "Field 1" form field, followed by the "Field 2" field. Next, open the “Style and behavior” tab and locate the “Form rule to be executed on value change” field. To define a rule for this field, click the ellipsis button located in the upper-right corner of the field. The rule editor window opens.

Opening the rule editor window

Once in the rule editor, create a rule that incorporates the “SET” function to define the desired behavior. To do that, open the “Function” tab and select the “SET” function from the “Behavior” node. The function changes value of the selected form field. You can edit the rule in the edition field by filling out relevant fields with values obtained from specified form fields. To specify where the result of the arithmetic operation should be inserted, enter the relevant form field name (the "Total" form field in this example) in the first empty field after the "SET" keyword. Then, enter the actual arithmetic operation in the next field. To do that, select the first form field (the “Field 1” in this example) whose value is to be added, and then enter the arithmetic operator (“+” in this example) and the second form field (“Field 2” in this example). The rule used in this example is shown in the screenshot below. It is important to note that arithmetic operations can involve more than two form fields and can be more complex than the one shown here.

The rule that performs the defined arithmetic operation

Once you complete editing the rule, save the new configuration by clicking the “Save & publish process” button or the “Save all” icon.

To test the rule, open the form in the Portal and ensure that the relevant form fields are set as "Visible" in the "Field Matrix".

Entering any value in the “Field 1” or “Field 2” form field results in transferring it to the “Total” form field. Entering values in both fields results in summing them up.

The result of the arithmetic operation is transferred to the “Total” form field.

It is important to mention two additional matters regarding configuration of the form fields themselves, i.e. visibility of the “Total” form field and the ability to place form fields in different form tabs.

• The form field in the “Read-only (cannot be modified except by JavaScript)”

In the example discussed above, the “Total” form field, where the result of the arithmetic operation is presented, is configured as “Visible” in the “Field matrix”. Such setting allows the end user to modify the result manually. To prevent this, the form field can be configured as “Read-only (cannot be modified except by JavaScript)” in the “Field matrix”. With this setting enabled, the result is transferred to the form field and the end user cannot modify it in any way.

The “Total” form field in the “Read-only (cannot be modified except by JavaScript)”

• Placing form fields in different tabs

In the case of more complex forms, part of the form fields can be placed in separate tabs. It is important to remember that such configuration in no way affect the rule operation and the values inserted in the form fields placed in separate tabs can still be summed up. Like in the previously discussed case, the result is transferred to the dedicated form field.

The “Total” form field (blue frame) is filled out with the result of adding the value from the “Field 1” form field (red frame) and the “Field 2” field (red frame) placed under a separate tab.

Example 2: business case: calculating the cost of insurance policy

In this example, the application is used by an insurance company to calculate the cost of insuring a car belonging to a requesting person. A number of variables specified in individual form fields is taken into consideration when calculating the cost of insurance policy. The final price is displayed in the “Cost of insurance” form field after entering all required data.

• Good practice for creating frequently used rules

Before proceeding to the actual configuration, it is necessary to make a small digression regarding good practices for creating rules. When dealing with highly complex forms or complicated arithmetic operations where values from a number of form fields are used, it is often necessary to insert the same rule in many places. To avoid creating the same rule from scratch each time, it is recommended to create rules in the “Form rules” node (selection tree → application name → process name → “Configuration” → “Form rules”) by clicking the “New rule” button and creating it in the newly opened editor window.

The “Form rule” node allows you to create and store rules that are inserted in various places in the system

A different method for saving rules in the “Form rules” node is to create the rule in the target location, e.g. placing it in the “Form rule to be executed on value change” (available in the “Style and behavior” section), and right-clicking it and selecting the “Create rule” option from the drop-down menu. Once you insert the name and possibly description in the newly opened window “Rule creation” and clicking the “OK” button, the rule is saved under the aforementioned node and can be used in many places.

Creating a rule in the rule editor available at the form field level

To insert such a rule, e.g. in a form field, just enter its name in the rule editor window and select it from a drop-down list. The rule is inserted in the form of a light green tile with its name displayed in the middle of it.

A huge benefit of creating and inserting rules with that method is reduced insertion time. An additional advantage is that a change to the rule is automatically applied to all places it was inserted in. This means that you do not have to change each instance of the rule, which is the case when it is created from scratch each time.

• Configuration

A simple process with two-step workflow has been created. The workflow form contains a number of form fields designed to collect data on the person requesting the car insurance. The data is grouped under three tabs: “Vehicle owner data”, “Car information”, and “Numerical data”. The first two tabs are designed to collect data from the requesting person, whereas the third one is filled out automatically using rules that process previously collected data. For the purpose of this presentation the last tab and all the form fields contained in it are visible on the form. Nevertheless, it is worth noting that they could be set as invisible or as technical fields that are not used by the end user for the request.

The form used for requesting car insurance

• Configuration of form fields grouped under the “Numerical data” tab

Since the rules themselves are not the primary topic of this article, only a brief description is provided below regarding how data is transferred to the form fields in the 'Numerical data' tab. This is intended to give the reader a general understanding of which data is used and in what situations it is applied in the final rule that contains the arithmetic operation.

[All the rules described below are inserted in the “Form rule to be executed on value change” (form field name → the “Style and behavior” tab → the “Form rule to be executed on value change”)].

• The “Age”, “Experience in years”, and “Vehicle age” form fields are filled out with numerical data (the floating-point number form fields) once you enter dates in the “Date of birth”, “Date of first driving license issuance”, and “Date of manufacture” (the “Date and time” form fields) respectively. The form rule with the “DATE DIFF” function is used to translate dates to years. The function is inserted inside the “SET” function that insert data to the form field specified in it.

The rule with the “SET” function and the “DATE DIFF” function inserted in it. The first one assigns a value to a form field, the second one translates dates into numerical representation of years.

• The values in the “Additional risk if older than 26”, “Experience discount”, and “Involvement in a road accident?” are taken into account in the final arithmetic operation conditionally (the condition is specified in the rule in which the aforementioned operation is inserted). To indicate which values are used in the arithmetic operation, a rule that highlights the relevant form fields with a colored frame using the “SET CONTROL BACKGROUND” function is applied. The rule is inserted in the following form fields: “Date of birth”, “Date of first driving license issuance”, and “Involvement in a road accident?”.

An example of application of the “SET CONTROL BACKGROUND” function in the “Date of birth” form field

• The 'Fixed cost' is a form field that has a default value of 300 inserted into it. This is a fixed value included in every insurance policy and does not depend on any variables.

• Configuration of a rule including arithmetic operation

A form rule that includes an arithmetic operation determining the final insurance cost is saved under the “Form rules” node under the name “Arithmetic operation”. Beside arithmetic operations, the rule includes two functions:

• “SET” – assigns value to specified form field.
• “IF THEN” – the function introduces conditional selection of a specific value.

Operation of both functions is described in detail in the following article: https://community.webcon.com/posts/post/function-dictionary-for-business-rules-and-form-rules/237

The created rule is shown in the below screenshot:

The rule calculating final insurance cost

In this case, the “SET” function opens the rule and specifies the form field whose value is to be modified with it, i.e. “Cost of insurance”.

The value of the “Fixed cost” (300) is a fixed value that is always included in the insurance cost. The value is calculated by multiplying each year of the vehicle's age by 10 and adding the result to the base value. Both values (“[Fixed cost]” and “[Vehicle age] * [10]) are always included in the operation.

Other elements of the rule and the arithmetic operation are conditional clauses introduced by the “IF THEN” function. Those conditions are described below:

• if a requesting person is under 26, 5% is added to the abovementioned amount [fixed cost + (vehicle age * 10)],
• 6% is added to the amount [fixed cost + (vehicle age * 10)] if a requesting person was involved in road accident,
• 10% is subtracted from the amount [fixed cost + (vehicle age * 10)] if a requesting person has had driving license for more than 5 years.

Such rule/arithmetic operation is inserted in the four form fields (the “Style and behavior” tab → the “Form rule to be executed on value change”) whose value, when changed, can affect the final insurance cost, i.e.  “Date of birth”, “Date of first driving license issuance”, “Involvement in a road accident?”, and “Date of manufacture”. It is necessary to include the rule in the four specified form fields to maintain accurate insurance cost calculations. This will ensure that the presented insurance cost is updated on each value change, such as when correcting a wrongly inputted date of birth.

After completing the abovementioned actions, the new configuration has been saved with the “Save & publish process” button (it is also possible to hit the “Save all” button).

• The rule/arithmetic operation in practice

Once you complete all the described actions, open the relevant request form in Portal.

In this example, we are considering a scenario where a person born in 1998 completes the request form. As this person is under 26 years old, the value of the "Additional risk if older than 26" form field applies. Additionally, as they have held a driving license since 2016, the value of the "Experience discount" form field applies. Lastly, since this person has been involved in a road accident in the past, the value of the "Involvement in a road accident" form field also applies. All of these factors will be taken into account when calculating the final insurance cost. The vehicle to be insured was manufactured on March 22nd, 2015, making it 7 years old. The calculated insurance cost for the requesting person is 373,70 PLN.

A form displaying the calculated insurance cost, with relevant variables highlighted by a colored frame

Summary

The ability to use rules for creating arithmetic operations is a highly useful functionality that enables users to configure form fields to automatically recalculate inserted values. A well-designed form with correctly configured arithmetic operations can provide end users with fast and easy access to information that is dynamically calculated based on the data they enter.