Numeric-type Data Items in Questetra BPM Suite can be configured with [Expression]. A Data Item configured with [Expression] is automatically populated with the calculation result derived from the values of other Data Items. Process assignees cannot manually enter values into this Data Item.
In this article, using an Equipment Purchase Request App as an example, we will explain how to write [Expression], handling decimals, calculation timing, behavior in Steps where referenced Data Items are set to [Not Displayed], and calculations that cannot be written with [Expression]. Basic operations on the Data Item settings screen are explained in “Chapter 6: Handling Data in Various Formats” of the First-Time Workflow App Design guide.
Workflow App Used in This Article
This is an App where employees request equipment purchases and their manager approves them. Steps progress in the order of “Application” (Start Step) and “Approval”.
The Data Items and their settings for each Step are as follows:
| Data Item (Field Name) | Data Type | “Application” | “Approval” |
|---|---|---|---|
| “Unit Price” (q_unit_price) | Numeric | [Editable] | [Display Only] |
| “Quantity” (q_quantity) | Numeric | [Editable] | [Display Only] |
| “Amount” (q_amount) | Numeric | [Editable] | [Display Only] |
| “Amount with Tax” (q_amount_with_tax) | Numeric | [Editable] | [Display Only] |
Because “Amount” and “Amount with Tax” are configured with [Expression], process assignees cannot enter values even though they are set to [Editable] in “Application”. The reason for setting them to [Editable] is explained in the section “Calculation Timing”.
The [Expression] expressions configured for “Amount” and “Amount with Tax” are as follows. In both cases, [Number of decimal places] is set to 0 on the Data Item settings screen.
| Data Item | [Expression] |
|---|---|
| “Amount” | #q_unit_price * #q_quantity |
| “Amount with Tax” | #q_amount * 1.1 + 0.5 |
The reason for adding 0.5 in the [Expression] for “Amount with Tax” is explained in the section “Handling Decimals”.
How to Write [Expression]
[Expression] is configured on the settings screen of a Numeric-type Data Item.
Values of other Data Items are referenced by prefixing their Field Name with #. Write it like #q_unit_price. Clicking the icon on the far right of the [Expression] input field displays a list of referencable Data Items. Selecting one from the list inserts its reference into the input field.
Referencable items are Numeric-type, Select-type, and Table-type Data Items. String-type and Date-type Data Items cannot be referenced. Because the reference syntax for Select-types and Table-types differs from Numeric-types, insert them from the list described in the previous paragraph. For Table-type Data Items, you can reference the aggregated value of a numeric table column that has [Show total value at the bottom of list] configured. Using references to Select-types is explained in “Adding Properties to Select-Type Data Item Choices“.
If a referenced Data Item has no entered value, it is calculated as 0.
Calculations use +, -, *, /, and parentheses. Fixed numbers like 1.1 can also be written.
A Data Item configured with [Expression] can also be referenced from the [Expression] of another Data Item. The [Expression] for “Amount with Tax” uses the calculation result of “Amount”.
When [Expression] is configured, [Initial Value], [Required], [Minimum Value], and [Maximum Value] can no longer be set.
Handling Decimals
In calculation results, places below [Number of decimal places] are truncated. When “Unit Price” is 105 and “Quantity” is 3, “Amount” is 315. In the [Expression] for “Amount with Tax”, if we take only #q_amount * 1.1 without + 0.5, the calculation result is 346.5; since [Number of decimal places] is 0, it becomes 346.
When the calculation result is a positive value, add 0.5 to the end of the [Expression] to round to the nearest whole number. In the [Expression] #q_amount * 1.1 + 0.5 for “Amount with Tax”, adding 0.5 to 346.5 gives 347.0; truncating its decimal portion results in 347. For [Expression] expressions where the calculation result evaluates to a negative value, rounding cannot be performed using this method.
Calculation Timing
On forms, calculation results update when the value of a referenced Data Item changes. Entered values are reflected when the cursor leaves the input field. Entering “Unit Price” and “Quantity” in “Application” immediately displays the calculation results in “Amount” and “Amount with Tax”.
Calculation results update on the form when the Data Item configured with [Expression] is set to [Editable] in that Step. Although this Step does not exist in this article’s App, in a Step where “Unit Price” and “Quantity” are [Editable] and “Amount” is [Display Only], changing “Unit Price” or “Quantity” will not update the display of “Amount”. The value saved when opening the Step will remain displayed. In this article’s App, “Amount” and “Amount with Tax” are set to [Editable] in “Application” so that process assignees can verify calculation results on the form.
Saved values are recalculated upon Step completion. Saved values for “Amount” and “Amount with Tax” are calculated from the values of “Unit Price” and “Quantity” saved at that moment. Even if an automated Step such as [Update Data] overwrites “Unit Price” or “Quantity”, “Amount” and “Amount with Tax” are recalculated when that automated Step completes processing.
Steps Where Referenced Data Items Are [Not Displayed]
In form calculations, Data Items set to [Not Displayed] in that Step are treated as 0. Although this Step does not exist in this article’s App, if you create a Step where “Quantity” is [Not Displayed] and “Amount” is [Editable], the “Amount” displayed on the form will be 0. Conversely, the “Amount” saved upon Step completion is recalculated from the previously saved “Quantity”, leading to a discrepancy with the form display.
In Steps where a Data Item configured with [Expression] is set to [Editable], do not set Data Items referenced by [Expression] to [Not Displayed].
Calculations That Cannot Be Written in [Expression]
[Expression] cannot change calculation expressions conditionally. Calculations such as applying a discount if “Amount” is 100,000 yen or more are performed by splitting paths with an [Exclusive Gateway (XOR)] and calculating using [Update Data] placed on each respective path. For setup instructions, refer to “Automatically Calculating Total Amounts (Coming Soon)”.
