Record Picker Component

About the record picker component

a!pickerFieldRecords( label, labelPosition, instructions, helpTooltip, placeholder, maxSelections, recordType, filters, value, saveInto, required, requiredMessage, readOnly, disabled, validations, validationGroup, accessibilityText, showWhen, showRecordLinks, marginAbove, marginBelow )

Displays an autocompleting input for the selection of one or more records, filtered by a single record type. Suggestions and picker tokens use the title of the record.

Parameters

Using the record picker component

The following sections cover important details about the record picker component.

Suggestions and permissions

• Maximum suggestions: The record picker can display a maximum of 25 suggestions.
• Search basis: Suggestions are based on the fields used in the record title. However, if you use a service-backed record type with direct data access, the search is based on the search property configured in the record data source expression.
• Permissions: Only records that the user has permissions to see appear in the suggestions list, as determined by the record-level security or the default filters in the record type.

Record title performance

Because suggestions rely on the record title, the record picker must evaluate the record title expression for each potential suggestion. If the record title uses queries, integrations, or other complex expressions, the picker can be significantly slower.

For best performance, use record fields or related record fields in the record title. If you need to display data from a related record in the title, create a relationship and reference the related record field directly rather than querying for it with a!queryRecordType().

Selections and placeholders

• Nulls: Any nulls in the array passed to selected records are not displayed. A [Not Available] token is displayed for any invalid identifiers in the selected records array.
• Array output: The component always saves an array regardless of how many selections have been made.
• Record links: By default, all selected records include a link to the record's summary view unless showRecordLinks is false. Consider setting showRecordLinks to false when selecting reference data from the picker. See Select a record from a record type without a link to the record for an example.
• Placeholder behavior: Whether placeholder text clears on focus or input varies by device and browser.

Web service load with service-backed record types

If you use a record picker with a service-backed record type, the picker places more load on the web service than a record list or read-only grid does. Understanding this difference can help you design your record data source to avoid performance issues.

• Search calls: Each character a user types into the picker triggers a separate call to the web service. Unlike the record list, where a search only executes after the user presses Enter, the picker generates significantly more web service calls during a single search.
• Label retrieval: The component makes one web service call per selected record to retrieve label information. Keep the expected number of selections low to avoid excessive calls.
• Filters: Filters applied in the component are processed the same way as default filters and user filters. Handle any picker-specific filters in your record data source expression and data retrieval rule.

If the record picker does not meet your needs, use a custom picker instead.

Examples

The following examples demonstrate the record picker component.

These examples reference record types from another environment and will error if you try to use them in yours. Use them as a reference only.

Select a record from a record type

1
2
3
4
5
6
7
8
9
10
11
12
a!localVariables(
  local!storedRecord,
  a!pickerFieldRecords(
    label: "Choose an Employee Record",
    /* For the "recordType" parameter below, replace the record type reference (recordType!Employee)  
     * with a valid record type reference in your environment. 
     */
    recordType: recordType!Employee,
    value: local!storedRecord,
    saveInto: local!storedRecord
  )
)

Displays the following:

Select a record from a record type with filters

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
a!localVariables(
  local!storedRecord,
  a!pickerFieldRecords(
    label: "Choose an Employee Record",
    /* For the "recordType" parameter below, replace the record type reference (recordType!Employee)  
     * with a valid record type reference in your environment. 
     */
    recordType: recordType!Employee,
    filters: a!queryLogicalExpression(
        operator: "AND",
        filters: {
          a!queryFilter(
            field: recordType!Employee.fields.department,
            operator: "=",
            value: "Engineering"
          ),
          a!queryFilter(
            field: recordType!Employee.fields.startDate,
            operator: ">",
            value: date(2022, 1, 1)
          )
        }
      ),
    value: local!storedRecord,
    saveInto: local!storedRecord
  )
)

Displays the following:

Select a record from a record type without a link to the record

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
a!localVariables(
  local!storedRecord,
    a!pickerFieldRecords(
      label: "Choose a Case Priority",
    /* For the "recordType" parameter below, replace the record type reference (recordType!Priority)  
     * with a valid record type reference in your environment. 
     */
      recordType: recordType!Priority,
      value: local!storedRecord,
      saveInto: local!storedRecord,
    /* Since the Priority record type only contains reference data (the different case priority levels), 
     * we can hide the record links to prevent users from navigating to their summary views.
     */
      showRecordLinks: false,
    )
)

Displays the following:

Feature compatibility

Old versions

There are older versions of this interface component. You can identify older versions by looking at the name to see if there is a version suffix. If you are using an old version, be sure to refer to the corresponding documentation from the list below.

To learn more about how Appian handles this kind of versioning, see the Function and Component Versions page.

Feedback