Choices in Select-type Data Items in Questetra BPM Suite have a Choice ID and a Display Label. In addition to these, values fixed per choice—such as unit price or category—can be stored as choice properties. The choice properties of a selected choice can be used in other Data Items.
In this article, using an Equipment Purchase Request App as an example, we will explain how to define choice properties, copy them to String-type Data Items, and reference them in [Expression] expressions of Numeric-type Data Items. For a list of setting items for Select-type Data Items, refer to Select-type.
Workflow App Used in This Article
This is an App where employees select equipment to request a purchase, and their manager approves it. Steps progress in the order of “Application” (Start Step) and “Approval”. The unit price and category of each piece of equipment are stored as choice properties of the choices in “Equipment”. When an employee selects “Equipment” and enters the Quantity, the Category field is populated by copying the choice property, and the Amount is populated with the value calculated by [Expression] from the unit price and the Quantity.
The Data Items and their settings in each Step are as follows:
| Data Item (Field Name) | Data Type | Application | Approval |
|---|---|---|---|
| Equipment (q_item) | Select (Select Box) | [Editable] | [Display Only] |
| Category (q_category) | String (Single line) | [Editable] | [Display Only] |
| Quantity (q_quantity) | Numeric | [Editable] | [Display Only] |
| “Amount” (q_amount) | Numeric | [Editable] | [Display Only] |
Category and Amount are not items entered by the process assignee. They are set to [Editable] in the Application step so that the values displayed in Category and Amount on the form updates when Equipment or Quantity changes. If set to [Display Only], the values present when the form was opened remain displayed.
The choices for Equipment are as follows. [Type of data source] is [Fixed choice list], and [Form Type] is [Select Box]. unitPrice and category are choice properties.
| Choice ID | Display Label | unitPrice | category |
|---|---|---|---|
| P01 | Ballpoint Pen (Black) | 120 | Stationery |
| P02 | Copy Paper (A4, 500 sheets) | 550 | Consumables |
| P03 | USB Flash Drive (64GB) | 1980 | PC Peripherals |
Defining Choice Properties
How choice properties are defined depends on [Type of data source]. In this article, a column corresponding to a single choice property is called a “Property Column”, following the terminology on the settings screen.
Choice property values are stored as strings. How to use them as numbers in calculations is explained in the section “Referencing in the [Expression] Field of Numeric-Type Data Items”.
Defining in [Fixed choice list]
In the [Fixed choice list], choice properties are defined alongside choices on the Select-type Data Item’s settings screen. Click [Add Property Column] below [Choices], and enter the name of the choice property (unitPrice and category in this article) in [Column Name]. A column is added to the choice list, so enter values for each choice. It is acceptable for some choices to have no values.
Choice property values can also be entered via CSV. Because Property Columns cannot be added or deleted in [Edit in CSV format], create the Property Columns beforehand using [Add Property Column]. Write one choice per line, separated by commas in the order of Choice ID, Label, and choice property values. Writing the choices for Equipment in [Edit in CSV format] looks like this:
P01,Ballpoint Pen (Black),120,Stationery
P02,"Copy Paper (A4, 500 sheets)",550,Consumables
P03,"USB Flash Drive (64GB)",1980,"PC Peripherals"In [Edit in CSV format], values containing spaces are displayed enclosed in double quotation marks.
Defining Property Columns reduces the maximum number of choices that can be defined. Without Property Columns, up to 1,000 choices can be defined; when Property Columns are defined, the maximum is 1,000 divided by the number of Property Columns. For example, if there are 5 Property Columns, up to 200 choices can be defined.
Defining in Choice Masters
When [Type of data source] is [Add-on file] or [App-Shared Add-on file], choice properties are defined in the Choice Master XML. For how to create Choice Master XML files, refer to Creating Choice Master XML with a Text Editor / Modeler. A Choice Master can contain up to 150,000 choices, and a Choice Master XML file can be up to 20 MB. Because adding Property Columns increases file size, the 20 MB limit may be reached with fewer than 150,000 choices.
Common Restrictions
Use letters, numbers, and underscores for Property Column names ([Column Name] on the settings screen). The first character must be a letter or an underscore. Japanese characters cannot be used. Names must be 64 characters or fewer and cannot be duplicated within the same Data Item.
Up to 50 Property Columns can be defined per Data Item.
Property Columns cannot be configured on table columns of Table-type Data Items.
Copying to String-Type Data Items
The choice property value of the selected choice can be copied to a String-type (Single line) Data Item. On the settings screen for Category, select Equipment for [Source of Choice Property Copy (Select-type Data Item)] and Category for [Property Column to Copy]. When the process assignee selects “USB Flash Drive (64GB)” in Equipment, “PC Peripherals” is populated into Category.
The destination Data Item cannot be edited on the form regardless of the Step’s data edit settings. The saved value is determined by the selected choice. In a Step where Category is [Editable], changing the selection in Equipment immediately overwrites it. If Equipment is unselected or if the selected choice has no value for category, Category becomes empty.
Only Select-type Data Items whose [Form Type] is [Radio Button], [Select], or [Search Select] can be used as the copy source. [Checkbox] cannot be used as a copy source. [Type of data source] must be [Fixed choice list], [Add-on file], or [App-Shared Add-on file].
Only String-type (single line) Data Items can be used as the copy destination. Values cannot be copied to String-type (multiple lines) or String-type (Markdown) Data Items, nor to table columns of Table-type Data Items.
[Required], [Initial Value], [Minimum Length], [Maximum Length], [Regular expression to be satisfied], and [Placeholder] cannot be configured on the copy destination.
Referencing in the [Expression] Field of Numeric-Type Data Items
The choice property value of the selected choice can be referenced from [Expression] of a Numeric-type Data Item. The [Expression] for “Amount” is as follows:
#q_item.property('unitPrice') * #q_quantity#q_item.property('unitPrice') is the unitPrice value of the choice selected in Equipment. #q_item is a reference to Equipment, written as # followed by its Field Name. #q_quantity references Quantity in the same manner. Selecting “USB Flash Drive (64GB)” and entering 2 for Quantity yields 3960 for Amount.
Although choice property values are stored as strings, if they are written in a format readable as a number, they are calculated as numbers in [Expression]. Examples include 120 and -1.5. Values containing thousands separators such as 1,980, or non-numeric values, are calculated as 0. If Equipment is unselected, it also evaluates to 0.
Choice IDs and Display Labels can also be referenced by appending to #q_item. The Choice ID is #q_item.value, and the Display Label is #q_item.display.
References such as #q_item.property('unitPrice') can be inserted using the icon on the far right of the [Expression] input field. How to write [Expression] and calculation timing are explained in “Automatically Calculate the Value of a Numeric-type Data Item Using an Expression“.
