Expression-Based User Filters

Overview

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

List examples

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


Create a filter option for every item in an array

The best use for expression-based user filters is generating filter options from data stored in a constant, variable, or data store entity 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 example below, 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!recordFilterList(
  name: "Department",
  options: {
    a!recordFilterListOption(
      id: 1,
      name: "Finance",
      filter: a!queryFilter(
        field: recordType!Employee.fields.department,
        operator: "=",
        value: "Finance"
      )
    ),
...
    a!recordFilterListOption(
      id: 6,
      name: "Sales",
      filter: a!queryFilter(
        field: recordType!Employee.fields.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!recordFilterListOption function for each item in the array.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
a!recordFilterList(
  name: "Department",
  options: a!forEach(
    items: cons!AT_DEPARTMENT_LIST,
    expression: a!recordFilterListOption(
      id: fv!index,
      name: fv!item,
      filter: a!queryFilter(
        field: recordType!Employee.fields.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 department values in cons!EMPLOYEE_DEPARTMENT is passed into the function, one at a time, which will result in three recordFilterListOption functions, 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 example below, 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
a!localVariables(
   local!acctExecs: getdistinctusers(cons!ACCOUNT_OWNERS),
   a!recordFilterList(
     name: "Account Executives",
     options: a!forEach(
       items: local!acctExecs,
       expression: a!recordFilterListOption(
         id: fv!index,
         name: user(fv!item, "firstName") & " " & user(fv!item, "lastName"),
         filter: a!queryFilter(
           field: recordType!Customer.fields.AccountOwner,
           operator: "=",
           value: fv!item
         )
       )
     )
   )
 )

This expression will be added to the options parameter of the recordFilterList 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
a!localVariables(
  local!statuses: rule!getIssueStatuses(),
  a!recordFilterList(
    name: "Status",
    options: a!forEach(
      items: local!statuses,
      expression: a!recordFilterListOption(
        id: fv!item.id,
        name: fv!item.status,
        filter: a!queryFilter(
          field: recordType!Issues.fields.status.id,
          operator: "=",
          value: fv!item.id
        )
      )
    )
  )
)

Where rule!getIssueStatuses() is a query 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
a!localVariables(
  local!employeeTitles: a!queryRecordType(
    recordType: recordType!Employee,
    fields: a!aggregationFields(
      groupings: {
        a!grouping(
          field: recordType!Employee.fields.title,
          alias: "title"
        )
      },
      measures: {
        a!measure(
          field: recordType!Employee.fields.id,
          function: "COUNT",
          alias: "count"
        )
      }
    ),
    pagingInfo: a!pagingInfo(
      startIndex: 1,
      batchSize: 5000
    )
  ),
  a!recordFilterList(
    name: "Title",
    options: a!forEach(
      items: local!employeeTitles.data,
      expression: a!recordFilterListOption(
        id: fv!index,
        name: fv!item.title,
        filter: a!queryFilter(
          field: recordType!Employee.fields.title,
          operator: "=",
          value: fv!item.title
        ),
        dataCount: fv!item.count
      )
    )
  )
)  

Date range example

The following example represents a common use of the a!recordFilterDateRange() function.


Create a date range filter with default options

Date range filters are easy to configure. They simply require a name and field to filter your data on, and optionally a starting and ending default configuration.

When using date range filters you have the flexibility of being able to filter on fields that are type date or date and time. The date and time type is acceptable as the filter's field type or as either default value. In both cases, the date and time values are interpreted as dates.

In the example below, the default filter values are configured to filter for matching dates within the last year.

1
2
3
4
5
6
7
a!recordFilterDateRange(
  name: "Start Date",
  field: recordType!Employee.fields.startDate,
  defaultFrom: "today() - 365",
  defaultTo: "today()",
  isVisible: true
)
Open in Github Built: Fri, Nov 04, 2022 (07:10:52 PM)

On This Page

FEEDBACK