Create User Filters for the Record List

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

Overview

When you configure the record list, you are providing users with a list of records from a record type, and allowing them to add, update, or remove records from the list using record actions. Now that they can see and interact with 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 Support Case 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 caseStatus record field to filter the record list by the status of "Open", "In Progress", or "Closed".

If your record type has a relationship with another record type, you can also create user filters on related record fields. Say the Support Case record type in our example has a relationship with the Customer record type. Using the relationship, you can easily reference the related record field customerName in the Support Case record list; then create a user filter to filter the record list by customer names retrieved from the Customer record type—all without creating expression rules or complex queries.

User Filters on Customer Support Record List

To speed up your design experience, a user filter is automatically generated whenever you define a new many-to-one relationship. This user filter is created on the related record field used to define the relationship (the common field), and uses the first non-primary key Text field on the related record type as filter options. The auto-generated user filter will appear on the User Filter page of the record type and can be modified at any time.

To configure a user filter, you can use one of the following:

  • 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.

Once you create user filters on the record type, you can use them in the record list and in records-powered grids.

If you are working with an existing record type created in 20.2 or earlier, update the record type to use new record type object components, features, and functions.

Guided user filters

Selecting Guided Configuration allows you to easily create list type or date range type filters without building an expression. 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 user filter configuration is slightly different. For more information, 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

Each filter option will display in a filter dropdown at the top of the record list. When there are more than 11 filter options, the filter includes a search box to help users find filter options.

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

    screenshot of a blank "Create New User Filter" dialog

  4. In Name, enter a name for the user filter. This is the name that will display on the User Filters page of the record type.
  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 record field or related record field you want to filter against.
  7. Under Visibility, 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, choose whether a user can select one or more filter options using the Users can select multiple options checkbox.
  9. If you selected a common field or a related record field in the Field dropdown, select one of the following options under Choice Options:
    • Related Record Values: Use values from a related record field as the filter options. If you selected a common field, you can choose the related record field. Otherwise, the values from the selected related record field are used as filter options.
    • Fixed Values: Enter each filter option and define the option label, operator, and value.
  10. If you selected a record field or choose to use Fixed Values as your filter options, click New Option.
  11. In Option Label, enter a name for the filter option. This is the name users will see in the filter dropdown.
  12. Choose the appropriate condition from the Operator dropdown. This is how your chosen record field will be compared.
  13. In Value, enter a value the condition must meet. This is the value your record field will be compared against.
  14. Click SAVE FILTER OPTION. Repeat steps 10-14 for each filter option.
  15. 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.
  16. 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.

    Date Range User Filter Creation

  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 record field or related record 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.

Expression-based user filters

In addition to the Guided Configuration, you can use an expression to construct a user filter. Simply use the a!recordFilterList() or a!recordFilterDateRange() function.

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.

If your record type has data sync enabled, you may only need to create an expression when working with record data that does not have a many-to-one relationship, or when you want to add customizations to your filter options.

When your record type has a many-to-one relationship with another record type, you can easily create a user filter with filter options from a related record field using the Guided Configuration. Simply select a related record field, or a record field that defines the many-to-one relationship, and the related record field values will automatically populate the filter options.

If you want to manipulate or customize those filter options, you can switch to Expression mode and generate an expression that reflects the current Guided Configuration. Now, all you have to do is add your customizations instead of building your entire expression from scratch.

The following section provides examples of user filters created from an expression.

When using a dynamic user filter, Appian recommends defining the user filter expression in a rule for version control and testing purposes, and calling that rule in the User Filters field.

Create a filter option for every item in an array

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 called "Department". Instead of manually creating an option for each status, we will 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.

Although this works, if your Employee record type has data sync enabled, you could create another record type called Department that contains the id, label, and description of each department.

By establishing a many-to-one relationship with the Department record type, you could then easily create a user filter on the departmentId field of the Employee record type and use the related record field label as the filter options–all from the Guided Configuration.

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

Although you can use Expression mode to build this user filter, if your record type has a many-to-one relationship with another record type, you can easily create the same user filter using the Guided Configuration. Simply select the record field that defines the relationship (the common field) and choose which related record field to use as the filter options.

For example, say the Support Case record type has a many-to-one relationship with the Issue Status record type, which contains the id and label of each issue status. On the Support Case record type, you can create a user filter on the customerId field, and use the related record field label to populate filter options from the Issue Status record type.

Not only is it faster to build these user filters in the Guided Configuration, you can avoid creating expression rules and experience better performance.

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.

This method may perform poorly with large data sets. We recommend that you create a lookup table and use the method described in the previous example when possible.

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

This section does not apply to record types that use a Salesforce object or other web service and have data sync enabled. Record types with sync enabled will have the same guided configuration experience listed above in the List user filter and Date range user filter sections.

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.

    User Filter for Records that Use a Web Service

  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.

User-saved filters

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.

Save Filters Dialog

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….

Manage Filters Dialog

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.

Saved Filters with Tags

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 20 unique filter combinations.

Manage Filters Dialog

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.

Open in Github Built: Tue, Sep 14, 2021 (01:01:54 PM)

On This Page

FEEDBACK