Actions on the Item list

Applies to version: 2023 R3 and above; author: Krystyna Gawryał

Introduction

In WEBCON BPS, it is now possible to perform automated operations on the rows, columns, and values of the Item list. Previously, these operations were executed using the Change item list values action, with the final result determined by the mode chosen by the configurator. However, version 2023 R3 introduced significant changes to this area, with the existing action updated and additional actions on the Item list added.
This article aims to provide a comprehensive overview of the available actions on the Item list, outlining their respective functions and highlighting the differences in operation based on practical examples.

List and characteristics of available actions

The group of actions associated with the Item list currently includes five actions. The definitions of these actions, along with examples of their use, are provided below. Table 1. illustrates the changes that have taken place in recent versions of WEBCON BPS in this regard.

Table 1. Actions on the Item list by version

All of these actions are available in the Form group and can be triggered:

• On entry,
• On exit,
• On timeout,
• On browser opening (except for the Update item list value action),
• Under a Menu button,
• On path,
• Upon instance saving.

For the purposes of this article, an Item list called “List of spare parts” was prepared that contains two Single line of text columns (Serial number, Name), one Choice field column (Manufacturer), and one Floating-point number column (Price per unit):

Once completed, the Item list may look as follows:

For presentation purposes, all actions were configured as being triggered through a Menu button with a name corresponding to the action name.

Add item list rows

This action adds all rows from the specified Data source to the indicated Item list, without checking for duplicates, but taking into account the values specified in the Columns mapping section. Executing this action may result in duplicate rows of the Item list.

The Column mapping option is used to map data source columns to the Item list columns. Based on this mapping configuration, Item list columns will be filled according to their order on the form in the given step. If column mapping is not configured, the column will be skipped when setting values. If the data source fails to return a column (despite mapping), the column will be skipped as if it was not configured. Item list initialization and the action will be logged as missing column configuration.

The action may serve as an alternative to the Update item list values action with the Add new rows from the data source option enabled. In that action, only unique rows from the specified Data source are added to the Item list, taking into account the Unique value mapping (see below).

• Action configuration and execution example

The action was configured with the “Spare part price list” data source, whose columns correspond to the columns of the “List of spare parts” Item list. The overlapping columns of the Item list and the data source were indicated in the Column mapping section:
 

After pressing the menu button under which the action is configured, all rows available in the data source are added.
 

As intended, the Item list is populated with all rows from the data source without applying additional uniqueness conditions. As a result, some of the rows are duplicated, as indicated in the figure above.

Additionally, the log available in the instance History informs that 15 rows were added as a result of the action.

Clear item list

This action removes all rows from the Item list specified in the configuration. The action also removes rows that are not visible in approval mode. This action is not available from the global automation level.

• Action configuration and execution example

The action configuration window simply requires the user to indicate the Item list to be removed.

Once the menu button is pressed, the action removes all data from the Item list.

This is confirmed in the log that informs that three rows of the Item List were deleted by the action.

Replace item list

The execution of this action results in the complete removal of all existing rows in the Item list and the addition of new rows populated with the specified values in the selected columns. Unlike the Update item list values action, the configuration window of this action does not have a section dedicated to unique value mapping, as it results in the loading of all rows from the data source into the Item list. Therefore, it can be concluded that the Replace item list action is a combination of the actions described above: Clear item list and Add item list rows. The log displays the number of rows that have been replaced.

• Action configuration and execution example

The action was configured with the “Spare part price list” data source, whose columns correspond to the columns of the “List of spare parts” Item list. Accordingly, the overlapping columns of the Item list and the data source were indicated in the Column mapping section.
 

Once the menu button is pressed, the rows of the Item list are overwritten with all the rows that are available in the data source. In this case, the rows may be repeated.
 

In addition, the log available in the instance History shows that a total of 15 rows were replaced (including added) as a result of the action.
 

Remove item list row

The action, as the only one described here, is available only in the context of the For each operator, where the defined Collection type is Item list. The action's operation is limited to removing the current Item list row, so there is no configuration window available for it. It is possible to create action patterns based on it. The action log in Admin mode shows exactly which Item list row has been removed.

• Action configuration and execution example

As defined above, the Remove item list row action was defined under the menu button within the automation based on the For each operator:

Given that no additional condition has been defined for the action execution, upon pressing the button, all rows of the Item list are deleted. This aligns with the functional assumptions of the For operator, which executes the action for each row.
 

This is evidenced, among other things, by the log available in the instance History:

Update item list values

This is an updated version of the previous Change item list values action that allows users to more clearly and flexibly specify the type of change to values in the Item list. The action is a compilation of three other actions: Add item list rows, Clear item list, and Replace item list, but a uniqueness condition is taken into account when it is executed. The action configuration window in Designer Studio has been modified – the Change type section now contains the following three options to choose from:

• Update existing rows – updates values in the Item list rows whose data source and Item list identifiers provided in the Unique value mapping field are matching. 
  The identifier of an Item list row is a unique value of one of its cells. This value originally defines the row and makes it unique, even if the values of other cells of this row overlap with the values of analogous columns of the Item list. A Social Security number (SSN), Tax Identification number (TIN), identification card number, school/student identification card number, product serial number/code, Vehicle Identification Number (VIN), vehicle registration plate number, file reference, or accounting invoice/contract designation, etc. are just a few examples of the potential row identifiers.
   Columns whose values are repeated within the list should not be used as the Item list row identifier.

However, if the Item list is to include all the rows from the data source without checking for duplicates, it is advisable to use the Add item list rows action.

• Add new rows from the data source – adds rows to Item list that exist in the data source, but are not available in the Item list. The rows to be added are identified on the basis of unique values provided in the Unique value mapping field,
• Remove rows that don’t exist in the data source – removes the rows that are not found in the data source from the Item list. The rows are identified on the basis of unique values specified in the Unique value mapping field.

At least one of the above options must be selected for the action to be executed. Depending on the type of changes made to the Item list, the action log displays data on the number of rows updated, added, or removed.

• Action configuration and execution example

The action was configured with the external MSSQL database data source named “Spare part price list”, whose columns correspond to the columns of the “List of spare parts” Item list. The action execution assumption in the presented case is to adjust the Item list in such a way that it accurately reflects the state of the data source, while ensuring that it does not contain duplicate items that may exist in it. From a business perspective, an employee of an online store would like to download and enter into the system the updated list of spare parts they received from their franchisor. Some items on the list duplicate those available in the data source. The store offers the same spare parts, but at changed prices. The franchisee requests that data be available in the system only for those products that are actually in the store's offerings, along with current prices. Consequently, the overlapping columns of the Item List and the data source were indicated in the Column mapping section, all available variants were indicated as the Change type, while the Unique value mapping was based on the serial number, which in this case is the unique identifier of each spare part / each row of the Item list.
 

After pressing the menu button under which the action is configured, the Item list values are updated with the values available in the data source, while no row of the Item list is repeated.
 

According to the log available in the instance History, the Item list now contains 8 rows, of which 4 rows have been updated, 4 rows have been added, while no rows have been removed from the Item list.
 

The above example illustrates the cumulative effect of the action on a small sample of data. However, it is possible to configure it with the exact type of change expected, as well as using a Filter to narrow down the values returned from the data source.

Summary

The actions on the Item list largely automate the work with this form field. Depending on the configured action, the availability of data sources, as well as the defined filters and additional column mapping options, users can complete, overwrite, and update Item list values with confidence that no information they wish to include in it will be missed. Those in charge of configuring the process can choose from actions that will include unique values or not, depending on the desired effect. Additionally, users can now swiftly delete all or selected rows of a form field, eliminating the need for manual intervention and offering significant time savings in the case of extensive Item lists.