Configure the Picker

A picker enhances a regular list of values field so that users can quickly find the record they need. Depending on setup, pickers can display either a list of saved searches to pick from, or a list of results most relevant to the user's context. Pickers are already available on certain standard fields and can't be modified, although you can configure new pickers for those fields, if needed. You can also configure pickers for custom list of values fields. Use the cx-picker fragment in Oracle Visual Builder Studio to configure new pickers.

Here's an example of a field without a picker. Without a picker, the field has a button that users can click to view a list of values.

This basic list of values makes it possible to filter on a value that the user enters into the field. For example, if the user enters pi, then a list of accounts whose names include pi display for selection.

This basic filtering functionality is helpful, but for better user experience, use the cx-picker template to enable a wider range of search features on a field.

What's a CX-Picker?

A cx-picker is a special kind of picker on a dynamic choice list field. With cx-pickers, users can search on more than one attribute of a record, not just on a single attribute. For example, in an Account picker, users can search not just on account name, but also on address, and contact name. The screenshot below illustrates a search on city name.

In addition, pickers are more powerful than the standard search on a field because, depending on setup, pickers can display either a list of saved searches or a list of results most relevant to the user's context.

In Sales in the Redwood UX, pickers can be based on either Adaptive Search or ADF REST.

• Adaptive Search Pickers

  Provide enhanced keyword searches on an object and support saved searches.

• ADF REST pickers

  Provide limited keyword searches and don't support saved searches.

CX-Picker Fragment Parameters

The following two tables list the required and optional parameters that you can use to configure the picker.

Required Parameters

Parameter	Sample Value	Description
dynamicLayoutContext	[[ $dynamicLayoutContext ]]	This parameter is set by default and you don't have to change it, provided the field displays on a create or edit page. The default value is $dynamicLayoutContext.
resource	[[ {"name": "accounts","displayField": "OrganizationName", "endpoint":"cx-custom","primaryKey":"PartyId" } ]]	Use this parameter to pass the target object name and end point: name: Specify the REST API name for the picker object. endpoint: The prefix used in the service connection of the resource. The endpoint can have values such as: cx, cx-custom, and so on. displayField: the field value that's displayed in the picker field after the user makes a selection. If not provided, then the picker displays the first field in the picker layout. additionalFields: Array that specifies additional fields shown in the picker.

Optional Parameters

Parameter	Sample Value	Description
extensionId	[['oracle_cx_salesUI']]	Application ID used in VB Studio that provides prefix for the endpoint. Values can be one of the following: oracle_cx_salesUI oracle_cx_fragmentsUI site_cxsales_Extension
pickerLayoutId	PickerLayout	This parameter points to the rule set whose layout controls how the picker looks at runtime. The default value, which you don't have to change, is PickerLayout, the ID of the Picker Layout rule set that's predefined for each object including custom objects. If you need to create a custom rule set, then create the rule set as a dynamic table and ensure that the values for the Label and ID fields are identical. Then add the ID to this parameter.
context	[[{'defaultSavedSearchId': 'cd899dfd-e671-4ba3-8e89-a27558494ea9', 'hideSavedSearches': false}]]	Controls the behavior of saved searches in cx-pickers that use Adaptive Search. When you configure a picker to display a list of saved searches, then the user can speed up searches by selecting a saved search in the picker to filter the records for the search. By default, the picker filters the records using the default saved search enabled for that object using the Manage Saved Searches UI. The list of saved searches shown is dependent on which saved searches the logged in user can access. You can use the following properties in the context parameter to control the behavior of the saved searches and specify which saved search is selected as the default when the picker is loaded: hideSavedSearches Use this property to show or hide the saved searches in a picker when you're using the query parameter: A value of false displays the list of saved searches and the saved search selected by default is the one identified in the defaultSavedSearchId parameter. A value of true displays no saved searches and the picker doesn't use the default saved search identified in defaultSavedSearchId. If you don't provide a value, then no saved searches are displayed in the picker for the object. defaultSavedSearchId Use this property to specify which saved search is used by default to show data on initial load. You can provide either the ID of a saved search or enter listDefault to display the default for the object. If you don't enter a value, or provide an incorrect one, listDefault is used. If you use the query parameter and don't use this property, then the picker uses the custom query. Note: If you don't use the query parameter, then the picker: Always displays saved searches. If defaultSavedSearchId isn't mentioned, then the application displays "Default Search View" as the default. This list shows user relevant items for the given object. If another foreign key is available, then the picker displays Related <object name>s as the default list. For example, if you select and account on the Create opportunity page, then the Contact picker shows the Related Contacts list with contacts belonging to the selected account. persistSelectedSavedSearch You can use this Boolean property to remember the previously-selected saved search.
createConfig	[[ {"enabled": false}	Use this parameter to specify whether you want the Create option in the picker list. This parameter is enabled by default and applies to both ADF and Adaptive Search pickers.
isDefaultSavedSearchEnabled	"true"	If true, then the application uses the List Default saved search by default. A defaultSavedSearchId supersedes this setting. This parameter isn't applicable if the “query” parameter is used to provide a custom query.
label	"Custom Picker"	Label for the picker field. If not provided, the field's label is used.
pickerNameField		Field name displays when a row is selected. If not used, the picker displays the field you specified when you created the DCL in Application Composer.
query	Adaptive Search Query Example: [[ {"type": "qbe", "provider": "adaptive", "label": "Created after June", "adaptiveQuery" : true, "params": [{  "op": "$gt", "attribute": "CreationDate", "value": "2025-06-30T00:00:00.000+0000"  }] } ]] Note: The time stamp must use the format: YYYY-MM-DDTHH:MM:SS.sss+TZ. ADF REST Query Example: [[ [{"type": "qbe", "provider": "adfRest", "params": [{"key": "PartyNumber", "operator": "equals", "value": "CDRM_2345" }]}] ]]	You can provide one or more custom queries to filter the data shown on the picker. The query can accept either a single JS object or an Array of objects. Each object corresponds to a separate custom query. When an array is provided, each query show up as a separate entry along with the other Saved searches in the saved search menu (the 3 dots icon next to the picker). The JS object takes the following properties: type Use the type qbe (query by example) to form a custom query. For complex queries you can use conjunctions like AND and OR. provider To use Adaptive Search as the data source, use: "provider": "adaptive" To use ADF REST as the data source, enter: "provider": "adfRest" adaptiveQuery Set to true when using Adaptive Search as the provider. You can use the same query as the one used in Adaptive Search REST APIs. params: Uses an array of JS objects with the following properties. If more than one object is provided, then the filters in them are combined at runtime using the AND operator. When provider = adaptive and adaptiveQuery = true: attribute: field to be used for the filter op: operator that can be used are the following: $eq(equals), $in(in), $ne(not equals), $gt (greater than), $lt (less than), $wi (within) value: Value of the field for filtering data values : Use with operators such as $in when more than one values are provided value2: Use only if the operator is $wi When provider = adfRest: key: ADF REST Field name operator: Supported operators: equal, notequals, startswith, endswith, contains, between, isblank, isnotblank, gt(greater than), lt (less than), ge (greater than or equal to), le (less than or equal to), and in value: Value for the filter criteria. For the in operator, pass the value as a comma-separated string: "OPEN,CLOSED" value2: To be used if the operator is between. label This is used to give a label to this query option. If not specified, the default value shown is “Filtered <object name>s”. For example, the label displays Filtered Accounts if the query is on the Account object. default: Value is either true or false. The custom query with a default of true, is the default when more than one custom queries are specified and when defaultSavedSearchId isn't provided in context.
sortCriteria	[[ [{ attribute: 'Name', direction: 'ascending' }] ]]	Specifies the default sort criteria used for the default view: attribute: name of the field that you're using to sort the data direction: sort direction, either 'ascending' or 'descending'
value		Use this parameter to specify the default value to be preselected when the picker is loaded. The parameter value is the value of the primary key of the object row.

Picker Example Scenario

This topic illustrates the setup of a picker based on Adaptive Search. In this example, we'll add an Account picker to a Create Payment page so that users can search for and associate an account with a payment record.

In this example, you'll do the following:

1. In Application Composer, create a custom dynamic choice list field.

2. In Visual Builder Studio:

   1. Add the dynamic choice list field to a page layout.

   2. Associate the field with a field template that uses the picker fragment.

   3. Configure the picker layout.

Prerequisites

Before creating the custom Account field, you must:

1. Complete the Adaptive Search setup, if working with a custom object.

   If you're configuring a picker for a field on a custom object, then make sure that you've enabled the custom object for Adaptive Search. The operation of a picker depends on what's already set up in Adaptive Search.

   A picker searches against all Adaptive Search fields that are enabled for keyword search. To enable additional attributes for search, see the topic Make Additional Fields Searchable.

2. Create your own workspace in Visual Builder Studio if you don't yet have one.

   If you're configuring a picker for a custom dynamic choice list field that's not yet published, then make sure your workspace is associated with your Cloud Applications sandbox.

3. Add the Common Application Components dependency to your workspace.

   To add a dependency, click the Dependencies side tab in Visual Builder Studio.

   Use the search field to find the Common Application Components dependency and then click Add.

4. This example assumes that you've got a custom Payment object with pages already configured in Visual Builder Studio.

   You can use the CX Extension Generator to set this up quickly. See Create a New Application Using the CX Extension Generator.

1. Create the Custom Dynamic Choice List Field

To get started, create a custom dynamic choice list field on a custom object, Payment, in Application Composer. This dynamic choice list field displays account records.

Note:

Creating a custom field is a data model change. Create all data model changes in Application Composer before creating application extensions in Visual Builder Studio. You don't have to publish your sandbox before working in Visual Builder Studio, however, since your workspace is associated with your current sandbox.

To create the custom dynamic choice list field:

1. Ensure you're in an active sandbox.

2. In Application Composer, navigate to the Payment object > Fields node.

3. Create a custom dynamic choice list field with these values:

   Field	Value
   Display Label	Account
   Name	Account
   Related Object	Account
   List Selection Display Value	Organization Name

Note:

For pickers that don't use Adaptive Search, you can use Application Composer to add a filter to the dynamic choice list field to constrain the values that users see in the picker. For example, you might want the picker to display only accounts that are based in a specific country or city. This type of filter isn't supported in Adaptive Search, so Adaptive Search pickers won't honor them.

When you create a dynamic choice list field in Application Composer, two fields are created:

• A field for use with classic, non-Redwood Oracle applications. The naming convention for this standard field is customfield_c.

  In this example, the Account_c field is automatically created. You can see and modify this field in Application Composer and Visual Builder Studio.

• A field for use with Redwood Sales. The naming convention for this standard field is customfield_Id_c.

  In this example, the Account_Id_c field is automatically created and displays in Visual Builder Studio only. This is the field that you add to Redwood Sales page layouts.

You can now add the Account_Id_c field to a page layout in Visual Builder Studio. We'll do that in the next section.

2. Add the Field to a Page Layout

Let's add your custom field to a page layout. In this example, we'll add the field to a create page. Typically, you'd also add the field to an edit page.

1. In the Sales in Redwood UX, navigate to the page that displays the area you want to extend. In this example, navigate to the Payments list page.

2. Under the Settings and Actions menu, select Edit Page in Visual Builder Studio.

   

3. Select the project that's already set up for you. If only one project exists, then you will automatically land in that project.

4. Visual Builder Studio automatically opens your workspace. If more than one workspace exists, however, then you must first pick your workspace.

5. When you enter into your workspace in Visual Builder Studio, click the Layouts side tab.

6. On the Layouts side tab, click the Payment_c node.

   

7. On the Payment_c tab, Rule Sets tab, click the Create Layout rule set.

   Note:

   Optionally repeat these same steps for the Edit Layout rule set.

8. Click the Open icon to edit the default layout.

   

9. Scroll through the list of fields to find your custom dynamic choice list field. Visual Builder Studio shows the internal API name, not the display name.

   Tip:

   To find your field more quickly, use the Filter field. For example, enter account into the Filter field.

   

10. Select the field, Account_Id_c, from the field list.

    When you select a field, it displays in the list of fields to the right, at the bottom of the list. You can optionally use the field's handle to drag the field to the desired location.

    

    If you were to preview the create page at this point, then the Account field that displays is a simple list with only basic search filtering.

    

    To add a picker to the field, you must associate the field with a field template that uses the picker fragment. Let's do that next.

3. Associate the Field with a Field Template

Let's add a picker to your custom dynamic choice list field to give users enhanced searching functionality. To do this, you associate the field with a field template that uses the picker fragment.

Note:

The following steps illustrate the required picker parameters, but you can set other parameters, as well. See OLD Parameters for the cx-picker Fragment.

1. Make sure that you're still on the Rule Sets tab, viewing the default layout.

2. Click the Account_Id_c field.

   

3. On the Properties pane, above the Template field, click Create.

   Note:

   If you're doing these steps a second time for the Edit Layout rule set's layout, then in the Template field, you don't need to create a field template. Instead, you can select the template that you're about to create in the next step.

4. In the Create Template dialog, in the Label field, enter a label for the template.

   In this example, enter AccountPickerTemplate.

   

5. Click Create.

   Visual Builder Studio creates a placeholder template with a basic structure, including an Input Text node which you can see on the Structure pane.

   

6. Delete the default Input Text node from the Structure pane by right-clicking the node and clicking Delete.

7. Click the Code button.

   

8. In the template editor, select the accountPickerTemplate template tags.

   

9. On the Components palette, in the Filter field, enter cx-picker.

10. Drag and drop the cx-picker fragment to the template editor, between the template tags.

    

11. Make sure the fragment code is selected, as illustrated in this screenshot.

    

    Tip:

    On the Structure pane, selecting the Fragment Container node for the picker template accomplishes the same thing.

    

12. On the Properties pane for the cx-picker fragment, in the Input Parameters section, set values for the required picker parameters.

    For additional parameters that you can set for the cx-picker fragment, see CX-Picker Fragment Parameters section.

4. Configure the Picker Layout

Finally, select which fields display in the picker by modifying the Picker Layout rule set. This rule set's layouts control how the picker looks at runtime.

The Picker Layout rule set and default layout are predefined for each object, including custom objects.

In this example, we're adding an Account picker which means we must modify the Picker Layout rule set for the Account object.

1. On the Layouts side tab, click the CX Sales > Accounts node.

   

2. On the Accounts tab, Rule Sets tab, click the Picker Layout rule set.

3. Duplicate the default layout and then click the Open icon to edit the default_copy layout.

   

4. Scroll through the list of fields to add any desired fields to the picker layout.

   Tip:

   To find your field more quickly, use the Filter field. For example, enter city into the Filter field.

5. Select the field, City, from the field list.

   When you select a field, it displays in the list of fields to the right, at the bottom of the list. You can optionally use the field's handle to drag the field to the desired location.

   

Test the Picker Flow

You can now test the picker that you added to the list of values field.

1. From the payment_c-list page, click the Preview button to see your changes in your runtime test environment.

   

2. The screenshot below illustrates what the list page looks like with data.

   

3. In the Action Bar, enter Create Payment.

4. Click Create Payment.

   The Create Payment drawer displays.

5. In the Create Payment drawer, click the three dots next to the Account field to view the list of saved searches.

   

6. If you enter some text into the field, the picker leverages Adaptive Search to return matched results. In the example below, we've entered pinnacle tech.

   

   In the picker, try searching on a city, for example, austin, so you can see how you can search on other record attributes.

   

   To understand how the search works, see Search Within Fields in the Search and Lists chapter in the Oracle Fusion Cloud Sales Automation Using Digital Sales (Redwood Sales) guide.

7. Once you're happy with how the picker looks, repeat these same steps for the edit layout.

   When configuring a second layout, you don't have to create a new field template and configure the picker fragment again; you can select the field template that you created in this procedure.

   You also don't need to configure the picker layout a second time.

8. Save your work by using the Push Git command.

   Navigate to the Git tab, review your changes, and do a Git push (which does both a commit and a push to the Git repository).