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 article. The detailed case for using the [FILTRATION] business rule is set forth in the Adding the [FILTRATION] rule to the edit page 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

The name of the column for which filters are set must be added to the attributes property of the view model.

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. These columns will be also displayed additionally in the drop-down list;

• 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 article EntitySchemaQuery filters handling.

NOTE Filters are combined by default in the collection using the AND logic operator. If the OR operator is to be used, this must be indicated explicitly in the logicalOperation property of the Terrasoft.FilterGroup object.

Below is an example of using the filtration via explicit description of filters in the attributes object.

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.

Case implementation algorithm

1. Create a replacement account edit page

A replacement client module must be created and [Account edit page] must be specified as the parent object in it (Fig. 1).

The procedure for creating the replacement page is described in the article Creating a custom client module schema.

Fig. 1. — Properties of the replacement edit page

2. Add the [Owner] column to the attributes property of the view model

Specify the type of column data (dataValueType property), namely the Terrasoft.DataValueType.LOOKUP in the configuration object, in the [Owner] column 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.

Below is the code of the replacement page schema

define("AccountPageV2", ["BusinessRuleModule", "ConfigurationConstants", "ProcessModuleUtilities"],
    function (BusinessRuleModule, ConfigurationConstants, ProcessModuleUtilities) {
        return {
            // Name of the edit page object schema.
            entitySchemaName: "Account",
            // List of the schema attributes.
            attributes: {
                // Name of the view model column.
                "Owner": {
                    // Type of this attribute data.
                    dataValueType: Terrasoft.DataValueType.LOOKUP,
                    // The configuration item 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 core schema.
                                // Contact 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;
                            }
                        ]
                    }
                }
            },
            details: /**SCHEMA_DETAILS*/{}/**SCHEMA_DETAILS*/,
            methods: {},
            diff: /**SCHEMA_DIFF*/[]/**SCHEMA_DIFF*/
        };
    });

3. Save the created replacement page schema

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.