This page describes how to create user filters for the record list.

• To display a list of records, see Configure the Record List.
• To create related actions to display on your records or the record list, see Create Record Actions.
• To define what the user will see on each record, see Define Record Views.

Overview

When you configure the record list, you are providing users with a list of multiple records from a record type, and allowing them to add new records to the list using a record list action. Now that they can see and add to the list of records, users should also be able to control which records appear in the list.

To allow users to filter the record list, you can create user filters. User filters offer the ability to filter subsets of record data by selecting options in a list or using a date range style filter. You can configure multiple user filters on a record list.

For example, in a Customer Support record type, users may want to know, of all the submitted cases, how many are open? To allow users to quickly find this answers, you could create a user filter on the Case Status record field to filter the record list by the status type of "Open", "In Progress", or "Closed".

If you choose to use your record type to power a read-only grid, the same user filters configured on the record type can be used as filters on the grid.

You can configure a user filter in one of two ways:

• Guided Configuration: Allows you to create a list or date range filter through a guided experience.
• Expression: Allows you to use an expression to dynamically generate the filter's options.

Guided user filters

Selecting Guided Configuration allows you to easily create list type or date range type filters. The section below explains how to configure each type of user filter.

If your record type uses a web service as the data source, the guided configuration of user filters is slightly different. For steps to configure a user filter, see User filters for record types that use a web service.

List user filter

List style user filters can have one or more filter options. For example, a filter named Region might contain five options:

• Africa
• Asia and Pacific
• Europe and Middle East
• North America
• South America

Depending on the filter configuration, users can select one or more of the filter options to view records that meet the filter criteria. By default, multiple filter options can be selected at a time from a single user filter, and all records that match at least one of the selected options will be returned.

To change the filter setting to allow a single selection only, disable the "Users can select multiple options" field. When there are more than 11 filter options, the filter includes a search box to help users find filter options.

To create a list user filter:

1. In your record type, go to the User Filters page.
2. Click New User Filter.

3. Under Type, select List.

   

4. In Name, enter a name for the user filter. This is the name it will display in the record type, in the User Filters table.
5. In Label, enter the name you want users to see for the filter on the record list.
6. In the Field dropdown, select the field you want to filter against.
7. In the Visibility section, click Only show when… to restrict the filter visibility and enter an expression that displays the filter when the expression evaluates to true.

8. Under List Configurations, click New Option to create a filter option. Each option will display under the filter dropdown at the top of the record list.

   

9. In Option Label, enter a name for the filter option. This is the name users will see in the filter dropdown.
10. Choose the appropriate condition from the Operator dropdown. This is how your chosen record field will be compared.
11. In Value, enter a value the condition must meet. This is the value your record field will be compared against.
12. Under Default Option(s), you can choose one of your options to apply as a filter by default when a user first loads the record list. The user can clear the option by clicking on it.
13. Click SAVE FILTER OPTION.
14. Click OK.

Date range user filter

You can also add date range filters, which allow precise record filtering between two dates or an open-ended range where only a start date or end date is provided.

When multiple user filters are present on the record list, users can select filter options for each of the defined user filters. The records returned are based on the records that meet the criteria of all the user filters combined.

For example, a Customer Support Case record list may have both a Status and Submitted Date filter. The Status filter has the "Open" and "In Progress" options selected. The Submitted Date filter has a date range of "1/1/2019 - 12/31/2020" selected. The records returned will be the support cases that have a status of "Open" OR "In Progress" AND fall between "1/1/2019 - 12/31/2020".

To create a date range user filter:

1. In your record type, go to the User Filters page.
2. Click New User Filter.

3. Under Type, select Date Range.

   

4. In Name, enter a name for the user filter. This is the filter name it will display in the User Filters table within the record type.
5. In Label, enter the filter name you want users to see.
6. In the Field dropdown, select the field you want to filter against.
7. In the Visibility section, click Only show when… to restrict the filter visibility and enter an expression that displays the filter when the expression evaluates to true.
8. Under Date Range Configuration, you can add a default From or default To value to apply as a filter by default when a user first loads the record list. The user can clear the option by clicking on it.
9. Click OK.

User filters for record types that use a web service

When you configure a user filter for an unsynced record type that uses a Salesforce object or other web service as the source, you will have a slightly different guided configuration experience when creating list and date range user filters.

Although configuration is slightly different, the same filter behavior for list and date range filters still apply.

List user filters

List style user filters can have one or more filter options.

To create a list user filter:

1. In your record type that uses a web service, go to the User Filters page.
2. Click New User Filter.
3. Under Filter Type, select List.
4. In Name, enter a name for the user filter. This is the name developers will see in the User Filters table within the record type.
5. In Label, enter the name you want users to see. This is the name your users will see on the record.

6. In the Rule Input dropdown, select a rule input from the Record Data Source expression rule to pass filter selections to the integration.

   If you don't see any rule inputs in the dropdown, enable filtering by adding rule inputs to the Record Data Source expression rule. See Enable paging, search, and filtering for more information.

7. In the Visibility section, click Only show when… to restrict the filter visibility and enter an expression that displays the filter when the expression evaluates to true.

8. Under Choices, enter an expression using a!recordFilterChoices to define the user filter choices. These choices will display under the filter dropdown at the top of the record list.

   

9. Under Default Choice, you can enter an expression that evaluates to one of the choice labels defined in the user filter so that it is applied by default when a user first loads the record list. The user can clear the option by clicking on it.
10. In Filter Preview, select the choice(s) from the filter dropdown and the value(s) associated with the choice(s) to preview how they will be displayed beside the dropdown. Click Update Filter Preview to preview any recent changes to the user filter configuration.
11. Click OK.

Date range user filters

Date range filters allow precise record filtering between two dates or an open-ended range where only a start date or end date is provided.

The rule input associated with the date range filter must be of type List of Date. The value for the user filter will always be a list of two values. If there is a start and end date, the user filter value would be {startDate, endDate}, where the start date is passed to index 1, and the end date is passed to index 2. When there is no selection for the start or end date, the value of the associated index will be null. For example, if you enter a startDate but leave the endDate blank, the user filter value would be {startDate, null}.

To create a date range user filter:

1. In your record type that uses a web service, go to the User Filters page.
2. Click New User Filter.
3. Under Filter Type, select Date Range.
4. In Name, enter a name for the user filter. This is the name developers will see in the User Filters table within the record type.
5. In Label, enter the name you want users to see. This is the name your users will see on the record.

6. In the Rule Input dropdown, select a rule input from the Record Data Source expression rule to pass filter selections to the integration.

   If you don't see any rule inputs in the dropdown, enable filtering by adding rule inputs to the Record Data Source expression rule. See Enable paging, search, and filtering for more information.

7. In the Visibility section, click Only show when… to restrict the filter visibility and enter an expression that displays the filter when the expression evaluates to true.
8. Under Date Range Configuration, you can add a default From or default To value to apply as a filter by default when a user first loads the record list. The user can clear the option by clicking on it.
9. Click OK.

Expression-based user filters

For record types that use an entity or process as the data source, you can construct a user filter with an expression. Simply use the a!recordFilterList() or a!recordFilterDateRange() 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 employees 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 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 the a!forEach function value index (fv!index), which keeps track of which value should appear in the array.

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.

Create 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 to 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 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.

Create filter options for values from 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.

In the example below, rule!getIssueStatuses() is a query that returns the contents of a lookup table of issue statuses. 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.

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
        )
      )
    )
  )
)

Create 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 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
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
      )
    )
  )
)

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. You can also optionally add 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
)

User-saved filters

Once you create user filters for the record list, users can save and manage their own user filter selections. Users can save their filters by first choosing values from the existing user filters, then selecting Save filters as… from the Filters menu.

The Filters menu allows each user to name their filters and choose which filter they want to load by default when they navigate to the record list or the grid that uses the record type as a data source. The Filters menu also allows users to view, remove, or rename their saved filters by selecting Manage my filters….

Each saved filter will display with a shortcut at the top of the page next to My Filters.

When a record type is used to power a read-only grid, the saved filter set will appear on grids that use the same combination of user filters as the record list. Read-only grids that use different combinations of user filters can save different filter selections on the grid.

All saved filters are also visible by selecting Manage my filters… from the filters menu. Here users can remove or rename existing filters. Users can save up to 10 unique filter combinations.

Users can save values for any filters visible on the record list. However, some changes to the record type may affect user-saved selections. If you deploy any of the following changes to the record type, the corresponding saved filter is affected:

• A user filter is removed
• A user filter option is removed from the list of options
• A user filter is changed from list to date range (or vice versa)
• A user filter is changed from multiple to single select and the user saved multiple values

In all of these cases, users may need to update the saved values. A warning message will display to describe what happened.