Using filtration for lookup fields. Examples

Introduction

There are two methods of using the filtration in bpm'online for lookup fields of the edit page:

1. The [FILTRATION] business rule.
2. Explicit indication of filters in the column description of the attributes model property.

The use of the [FILTRATION] business rule is expedient if a simple filter by a specific value or attribute must be used for the field. The business rules are detailed in the Setting the edit page fields using business rules. The detailed case for using the [FILTRATION] business rule is set forth in the The FILTRATION rule use case article.

If arbitrary filtration (sorting and addition of supplementary columns to a query when a drop-down list is displayed) is required, the explicit description should be used in the attributes model property.

Setting lookup field filters in the attributes model property:

1. The name of the column for which filters are set must be added to the attributes property of the view model.
2. The lookupListConfig property must be declared for this column. It represents a configuration item containing the following properties (not required):

   • columns – an array of column names to be added to a request in addition to Id and the primary display column.

   • orders – an array of configuration objects determining the data sorting when displayed.

   • filter – the method for returning the object of the Terrasoft.BaseFilter class or its inheritor, will be applied, in turn, to a request.
   • or filters – an array of filters (methods for returning collections of the Terrasoft.FilterGroup class).

Filters are added to a collection using the add() method which has the following parameters:

The object of the Terrasoft.BaseFilter class or its inheritor is the item parameter. The methods for creating filters with descriptions are given in Table 1 of the EntitySchemaQuery filters handling article.

Case description

When a value is added to the [Owner] field of the account edit page, display only those contact lookup values for which the following conditions are fulfilled:

• a system user associated with this contact is available
• this user is active.

Source code

You can download the package with case implementation using the following link.

Case implementation algorithm

1. Create a replacing account edit page

A replacing client module must be created and [AccountPageV2] must be specified as the parent object in it (Fig. 1). The procedure of creating a replacing page is covered in the“Creating a custom client module schema” article.

Fig. 1. Properties of the replacing edit page

2. Add the attribute with filtration to the attributes property of the view model

Specify the type of column data – the Terrasoft.DataValueType.LOOKUP in the configuration object, in the [Owner] attribute and describe the configuration object of the lookupListConfig lookup field. Add the filters property to lookupListConfig, which represents the function for returning the filters collection. Add a function that returns a collection of filters to the array.

The replacing schema source code is as follows:

define("AccountPageV2", [], function() {
    return {
        // Name of the edit page object schema
        "entitySchemaName": "Account",
        // List of the schema attributes.
        "attributes": {
            // Name of the view model column.
            "Owner": {
                // Attribute data type.
                "dataValueType": Terrasoft.DataValueType.LOOKUP,
                // The configuration object of the LOOKUP type.
                "lookupListConfig": {
                    // Array of filters used for the query that forms the lookup field data.
                    "filters": [
                        function() {
                            var filterGroup = Ext.create("Terrasoft.FilterGroup");
                            // Adding the "IsUser" filter to the resulting filters collection.
                            // The filter provides for the selection of all records in the Contact core schema
                            // to which the Id column from the SysAdminUnit schema is connected, for which
                            // Id is not equal to null.
                            filterGroup.add("IsUser",
                                Terrasoft.createColumnIsNotNullFilter("[SysAdminUnit:Contact].Id"));
                                                        // Adding the "IsActive" filter to the resultant filters collection.
                            // The filter provides for the selection of all records from the core schema.
                            // Contact to which the Id column from the SysAdminUnit schema, for which
                            // Active=true, is connected.
                            filterGroup.add("IsActive",
                                Terrasoft.createColumnFilterWithParameter(
                                    Terrasoft.ComparisonType.EQUAL,
                                    "[SysAdminUnit:Contact].Active",
                                    true));
                            return filterGroup;
                        }
                    ]
                }
            }
        }
    };
});

When the schema is saved and the system web-page is updated, only values from the contact lookup which comply with custom conditions will be displayed on the account edit page when adding a value to the [Owner] field on the account edit page (Fig. 2, Fig. 3). I.e:

• a system user associated with this contact is available
• this user is active.

Fig. 2. Account profile with the owner

Fig. 3. The owner is disable in the filtered contact lookup