Expression-Based User Filters

Overview

This page provides information on how to use the a!facet() and a!facetOption() functions to define user filters for service-backed records list, or in place of static user filters for process and entity-backed records.

Common Uses

The following examples represent some common uses of the a!facet() function.


Create a Filter Option for Every Item in an Array

The best use for expression-based user filters is generating filter options instead of manually creating and maintaining each one. For example, let's say you have an employee management system, and you want to filter the list of employee by the employee's department.

Every employee has a Department dropdown that refers to a constant (cons!EMPLOYEE_DEPARTMENT), which has the following values:

  • Corporate
  • Engineering
  • Finance
  • HR
  • Professional Services
  • Sales

In the below example, we have a user filter group called "Department," with several filter options, one for each department.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
a!facet(
  name: "Department",
  options: {
  	a!facetOption(
	  id: 1,
	  name: "Corporate",
	  filter: a!queryFilter(
 	    field: "department",
 		operator: "=",
  	    value: "Corporate"
		)
	),
  	...
  	a!facetOption(
	  id: 6,
	  name: "Sales",
	  filter: a!queryFilter(
 	    field: "department",
 		operator: "=",
  	    value: "Sales"
		)
	)
  },
  isVisible: true		
)

This works, but if we decide we want to add a Department, like "IT," or "Pre-Sales", we'd have to come and change these user filters manually.

So, instead of manually creating an option for each status, we can use the a!forEach() function to write those options for us based on the constant (cons!EMPLOYEE_DEPARTMENTS).

The a!forEach() function will take an array of values and pass them to an expression one at a time, creating the a!facetOption expression for each item in the array.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
a!facet(
  name: "Department",
  options: a!forEach(
    items: cons!EMPLOYEE_DEPARTMENTS,
    expression: a!facetOption(
      id: fv!index,
      name: fv!item,
      filter: a!queryFilter(
        field: "department",
        operator: "=",
        value: fv!item
      )
    )
  )
)

As you can see, in the options parameter we're using the a!forEach function for every value in the status constant. In order to give each one an ID, we use a!forEach's function value index (fv!index), which keeps track of which value should appear in the array.

The the array of deparment values in cons!EMPLOYEE_DEPARTMENT is passed into the expression, one at a time, which will result in three facetOption expressions, one for each status.

The result will perform exactly the same as the first example in this section.


Filter Options for Users in a Group

In this case, you have a user group and you want to create a filter option for every member of that group. For this, we'll be using the a!forEach() function write our options for us, as we did in the previous example.

To get the list of users for the a!forEach function, we'll use getdistinctusers(), which returns a list of every user within a group.

In the below example, you'll notice that instead of passing the group ID to the getdistinctusers() function, we referenced a constant; that constant points to the group object.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
= with(
  local!acctExecs: getdistinctusers(cons!ACCT_EXECS),
  a!facet(
    name: "Account Executives",
    options: a!forEach(
      items: local!acctExecs,
      expression: a!facetOption(
        id: fv!index,
        name: user(fv!item, "firstName") & " " & user(fv!item, "lastName"),
        filter: a!queryFilter(
          field: "accountExec",
          operator: "=",
          value: fv!item
        )
      )
    )
  )
)

This expression will be added to the options parameter of the facet function for each user in the list.


Filter Options for Values in a Lookup Table

In this case, you have a lookup table of issue statuses in your database, and you want to create a filter option for each status. For this, we'll be using the a!forEach() function to write our options for us, as we did in the first example.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
= with(
  local!statuses: rule!getIssueStatuses(),
  a!facet(
    name: "Status",
    options: a!forEach(
      items: local!statuses,
      expression: a!facetOption(
        id: fv!item.id,
        name: fv!item.status,
        filter: a!queryFilter(
          field: "status.id",
          operator: "=",
          value: fv!item.id
        )
      )
    )
  )
)

Where rule!getIssueStatuses() is a query rule that returns the contents of a lookup table of issue statuses. Here, instead of fv!index being used as the id for filter option, we are assuming that fv!item.id is the primary key value of the lookup table.


Filter Options from Unique Values in the Data

In this case, you have a table of data and you want to create a filter option for each unique value in a specific field in that table. For this, we'll be using the a!forEach() function write our options for us, as we did in the first example.

This method is not recommended for large data sets, which may perform poorly. When possible, we recommend creating a lookup table and using the method described in the previous example.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
=with(
  local!employeeTitles: a!queryEntity(
    entity: cons!EMPLOYEE_ENTITY,
    query: a!query(
      aggregation: a!queryAggregation(
        aggregationColumns: {
          a!queryAggregationColumn(
           field: "title",
           isGrouping: true
          ),
          a!queryAggregationColumn(
            field: "id",
            alias: "count",
            aggregationFunction:"COUNT"
          )
        }
      ),
      pagingInfo: a!pagingInfo(
        startIndex: 1,
        batchSize: -1,
        sort: {
          a!sortInfo(
            field: "count",
            ascending: false
          )
        }
      )
    )
  ),
  a!facet(
    name: "Title",
    options: a!forEach(
      items: local!employeeTitles.data,
      expression: a!facetOption(
        id: fv!index,
        name: fv!item.title,
        filter: a!queryFilter(
          field: "title",
          operator: "=",
          value: fv!item.title
        ),
        dataCount: fv!item.count
      )
    )
  )
)

Where cons!EMPLOYEE_ENTITY is a data store entity mapped to a table of employees.

FEEDBACK