Skip to main content
Matrix42 Self-Service Help Center

Object Picker

  1. Last updated
  2. Save as PDF

Overview

An Object Picker is a control that looks like an ordinary field in run time and allows you to locate and select a single object.

There are several types of controls that allow you to locate and select object(s) in Solution Builder, for example:

All of the above controls inherit the Object Picker, among others, and, therefore, have much in common.

How to Use Object Picker in Run Time

  • Click an Object Picker field in run time and start typing the name of the object you would like to add to the field. The control will suggest up to 5 options to select from as you type:
    object_picker.png
    If the option you need is not on the suggested list, click the Show More link or click the magnifying glass inside the field to open the Select Object(s) page.
     
  • Use the Search Text field at the top of the page to locate the object you need; then click the object to add it to the object picker field and close the Select Object(s) page. Alternatively, use the advanced search clipboard_e695b186ee1c84f415fcca4a589136850.png  icon to locate the object:
    object_picker_grid.png
  • You can sort the grid by any of the grid columns (A-Z or Z-A). You can also scroll down the page and use the paging controls at the bottom to locate the object you need. You can add a new object to the grid from the Select Object(s) page by clicking the Add new + button (if available) in the top right-hand corner of the page and filling out the New Object dialog that appears.
  • Click the CANCEL button in the bottom right-hand corner of the Select Object(s) page to close the page without selecting an object.
  • Click the remove X icon in the object picker field to clear the field.

How to Set up Object Picker Control

An Object Picker control, just like any other control in Solution Builder, has its own Control Descriptor (located under Administration application → User Interface → Control Descriptors), which defines how the control is set up, what fields the control has, and how it behaves. Users with Admin rights can modify the Control Descriptor, if needed, to suit their specific business needs.

Layouts

By default, the Object Picker Control is available for the following types of Layouts:

  • Dialog
  • Wizard

To enable the Object Picker control usage in other types of Layouts see Administration application → User Interface → Control Descriptors → Object Picker settings.

Layout Designer

Your next step is to set up the Object Picker control in Layout Designer:

  • Locate an existing Object Picker on the canvas in Layout Designer, add a new one from the Toolbox, or drag&drop the necessary Data Model attribute that has suitable for the Object Picker control data type (Object Reference or Guid). The controls are suggested as follows:
    object_picker_layout_designer.png
  • Click the control on the canvas to open its properties in the right-hand panel. Properties that the Object Picker has in Layout Designer are defined in the Object Picker Control Descriptor.

Minimal required property settings 

The following data model properties are minimum required for the object picker display in the runtime:

  • Value: the attribute of the Data Definition that stores the chosen from the object picker value;
  • Data Definition: entity class that serves as a source of suggested in the object picker values;
  • Label: the title of the displayed field.

Use drag&drop to automatically pre-fill Value, Data Definition, and Label properties. Drag&drop the attribute of Object Reference or Guid type from the Data Model on the canvas and choose Object Picker control from the suggested options. 

These properties are enough for correctly displaying the object picker field in the application. Other properties can be adjusted as described below.

Object Picker Specific Properties

Property group Property name Description Default Property setting example

Model
Value

Enter the attribute of the Data Definition that stores the chosen from the object picker value.

 ❌ value_LD.png
Data Definition

Source of suggested in the object picker values. Select an entity class for the Object Picker.

In the runtime, the suggested for the object picker list shows the options filtered according to the Allowed Types, Filter Expression, and the option titles are based on the Display Expression property.

 ❌ data_definition_LD.png
Allowed Types

Optional filtering criteria for the data retrieved from the specified Data Definition. 

  • ❌  not specified (default): options for the object picker are retrieved based on the Data Definition field property (if no other filters were configured);
  • Static value: set 1 or more filtering criteria for the retrieved data. The field auto-suggests all available in the system Configuration Items. Selected values refine available for the object picker options.
 ❌ allowed_types_LD.png
Filter Expression

Additional filtering criteria for the options retrieved to the object picker. Optional field. The filter is applied to the specified Data Definition.

Specify a default ASQL filter expression for the search results displayed in the suggested options list and Select Object(s) page in run time, if needed:

filter_expression.png

The example above filters and suggests in the object picker options that:

a. are from the Allowed Types (if configured) and;

b. the value of the specified Data Definition attribute "Hidden" is set to false (0).

For this data filtering step, the Allow Reset Filter is set to Disabled (default).

You can set a static value or bind the control with a data model property (from the Model tab).

 ❌ filter_expression_LD.png
Allow Reset Filter

Select the checkbox to allow users to reset the filtering conditions for the suggested object picker options in the run time:

  1. Click the Search without default filter link in the object picker field if the search result is not found:
    allow_reset_filter_1_1.png
  2. Select the Reset filter check-box on the Selected Object(s) page to see all available results:
    allow_reset_filter_2_1.png

The enabled check-box resets the Filter Expression condition and applies the Reset Filter Expression, if it is specified. 

Thus, the enabled check-box allows displaying all search results without the default filter applied.

The applied default filter depends on the properties and combinations of the following fields of the object picker configuration:

  1. Allowed Types
  2. Filter Expression
  3. Allow Reset Filter
  4. Reset Filter Expression

The configuration of these fields is optional and should be configured to achieve the necessary data filtering results.

Example 1

  1. Allowed Types: set.
  2. Filter Expression: set.
  3. Allow Reset Filter: Disabled (default).
  4. Reset Filter Expression: not set (default).
  • Default filter in this configuration applies conditions from Allowed Types and Filter Expression properties.
  • Reset default filter: not available.

 

Example 2

  1. Allowed Types: set.
  2. Filter Expression: set.
  3. Allow Reset Filter: Enabled.
  4. Reset Filter Expression: not set (default).
  • Default filter: Allowed Types and Filter Expression;
  • Reset default filter:  Allowed Types.

 

Example 3

  1. Allowed Types: set.
  2. Filter Expression: set.
  3. Allow Reset Filter: Enabled.
  4. Reset Filter Expression: set.
  • Default filter: Allowed Types and Filter Expression;
  • Reset default filter: Allowed Types and Reset Filter Expression.
 Disabled allow_reset_filter_LD.png
Reset Filter Expression

Specify an additional ASQL filter expression, if needed, to allow users to filter the search results by the additional criteria.

If the user selects the Reset Filter checkbox in run time, the Reset Filter Expression specified here will apply to the search results, while the Default Filter Expression specified in the Filter Expression field will not apply.

Additionally requires Allow Reset Filter property set to Enabled.

 ❌ reset_filter_expression_LD.png
Use Object ID

Check-box options:

  • Disabled (default): picked by the user object is stored in the Value field as a fragment ID (the ID from the specified Data Definition);
  • Enabled: instead of the fragment ID from the Data Definition returns the Expression-ObjectID that has a reference to the Configuration Item where the fragment is used.
 Disabled use_object_id.png
Data Query

Former Column Definition field that was renamed in DWP v.12.0.1.

Defines a set of columns that are displayed on the Select Object(s) page when the user clicks Show More link or the lookup.pnglookup icon:

column_definitipon_eg.png

 ❌ Screenshot 2023-06-13 at 16.54.38.png
Data Query Column To Display

Former Display Expression property that was substituted with Data Query Column to Display starting from DWP v.12.0.1.

To show the Display Expression edit the Data Query column Expression and specify the name of the Data Query Column in this property.

A Data Query column is used to display a value in the autocomplete dropdown list instead of a default display expression of the Data Definition.

  • ❌  not set: the system uses standard Display Expression defined in the schema for the specified in the Model property group Data Definition.
    For instance, the Display Expression for the SPSUserClassBase is LastName + ISNULL(', ' + FirstName,'') and will be displayed as follows:
    Screenshot 2023-06-13 at 17.25.16.png
  • set: the name of the Data Query Column
    For instance, the FirstName Data Query Column name is displayed in the object picker as follows:
    Screenshot 2023-06-13 at 17.29.20.png
    If the Data Query is set, the specified column from the Data Query is used. If the Data Query is not set, the system checks all available Data Queries based on the selected in the control Data Definition, checks the Data Queries by priorities, and uses the column from the Data Query with the highest priority.
 ❌ Screenshot 2023-06-13 at 17.12.22.png

Output

   Use the Output section to save the current state of the control:    
Object Id

Select where to store the Id of the object selected by a user in the Object Picker field in the run time. 

You can set up these returned values (Object Id and Display Name) to trigger something else in the application or perform a certain operation, for example, see the Custom Validation configuration using the Object Id property value.

 ❌ object_id_LD.png
Display Name 

select where to store the Display Name of the object selected by a user in the Object Picker field in run time.

You can set up these returned values (Object Id and Display Name) to trigger something else in the application or perform a certain operation, etc.

 ❌  

Common
Help 

help icon and tooltip for information displaying as:

  • ❌  not set: help icon is not displayed;
  • static value: manually entered text is displayed in a pop-up window. The text of the prompted message is edited in a standard text editor and can include plain text, headings, links, and lists;
  • localizable:  plain text specified per each available in the system locale. Shows appropriate localized help message according to the currently selected by the user language from the profile settings;
  • model: displayed data is retrieved from a specified data model field.

help1.png

 ❌ help_LD.png
Label

The title of the object picker field:

label1.png

Can be set via one of the following options:

  • ❌ not selected:  the title is empty and not displayed;
  • static value: manually entered title of the grid;
  • localizable:  the title is specified per each available in the system locale. Shows appropriate localized  title according to the currently selected by the user language profile settings;
  • model: displayed data is retrieved from a specified data model field.
 ❌ label_LD.png
Disabled
  • Static value: check-box options
      • disabled (false): the object picker field value can be modified;
      • selected (true): the field is available in the read-only mode and the value of the object picker control can not be changed manually.
    • Model: suggests boolean data type options from the data model (true/false values).
 False disabled_ld.png
Hint

Hint text or an example of the information required for the field. 

  • ❌  not set: hint is not displayed;
  • static value: manually entered text is displayed under the object picker field;
  • localizable:  plain text specified per each available in the system locale. Shows appropriate localized help message according to the currently selected by the user language from the profile settings;
  • model: displayed data is retrieved from a specified data model field.

hint1.png

Hint example displaying

 ❌ hint_LD.png
Required

Defines whether the data for the object picker is required for the layout.

  • Static value: check-box options
    • disabled (false): the layout can be saved without selecting an object;
    • selected (true): the value for the object picker control is mandatory.
  • Model: suggests boolean data type options from the data model (true/false values).
 False required_LD.png
Read-only
  • Static value: check-box options
      • disabled (false): the object picker field value can be modified;
      • selected (true): the field is available in the read-only mode and the value of the object picker control can not be changed manually.
    • Model: suggests boolean data type options from the data model (true/false values).
 False read_only_LD.png
Name
 Mandatory field with auto-generated name or identifier of the edited object picker control. auto-generated name_LD.png

Validation
Custom Validation

Additional validation of the selected in the object picker value. Configure this property in case the standard filtering conditions of the Allowed Types, Filter Expression and Reset Filter Expression fields configuration are not enough. 

The Custom Validation is handy in cases when the selected value should be additionally validated by another service, for instance:

  1. Choose the user in the object picker;
  2. Configured service retrieves user data;
  3. Configured Custom Validation runs and depending on the result may show a validation error:

custom_validation2.png

The selected user has 'Global' location. Based on the Custom Validation settings this location returns an error and the dialog can not be saved.

The Custom Validation configuration for this example may include the following steps:

  1. Using the Object Id field, configure a service that returns user details information, including the assigned Location:
  • In the Data Model of the Layout Designer, click +Add Source to add a new source with the following configuration:
    userDetails_service.png
  • In the Output → Object Id field of the object picker set a property from the configured source:
    object_id_LD.png

2. Configure Custom Validation: 

  • In the Data Model → Context → click Add Property.
  • Configure calculated property of an Object Type.

​​The Custom Validation property allows setting up selected value validation in the format:
{ IsValid: true, ErrorMessage: '' }

test_validation_settings.png

  • In the Validation section → Custom Validation field of the object picker set configured property:
    custom_validation_LD.png

The configuration will validate the user data in the run time as shown in the example above. 

 ❌ custom_validation_LD.png

Appearance
Visibility

Grid display on the page modes:

  1. Static value: check-box options
    • selected (True): object picker control displaying on the page layout template is enabled; 
    • disabled (False): the object picker control is not shown on the page layout.
  2. Model:  select data model source out of suggested data with boolean type. The object picker displaying depends on the current value of a specified property.
 True visibility.png
Margin

set property creates additional blank space outside of the borders of the element containing the object picker control.

Set control's margin in CSS format measured in px or rem:

  • '10px', '1rem'  (top, right, bottom, left);
  • '1rem 2rem' (top-bottom, right-left); 
  • '1px 2px 3px 4px' (top, right, bottom, left).
 ❌ margin_LD.png
Padding

the property is used to generate additional blank space around the object picker, inside of the borders of the element containing the object picker control. 

Set control's padding in CSS format  measured in px or rem:

  • '10px', '1rem'  (top, right, bottom, left);
  • '1rem 2rem' (top-bottom, right-left); 
  • '1px 2px 3px 4px' (top, right, bottom, left).
 ❌ padding_LD.png
Flex Option

intended to automatically adjust the width of the displayed in the run time field. Possible options:

  • fixed: field width is static;
  • flex: the container width is responsive and adjusts automatically according to the screen resolution of the user's device.
 Fixed flex_option_LD.png

Device Visibility
Desktop

The application checks the user device's screen resolution and shows or hides the object picker element based on the selected check-box options:

  • disabled: the object picker is not displayed;
  • selected (default): the object picker is shown on the page.

device_visibility.png

Device visibility settings example: object picker control is displayed for all types of devices

 Enabled  
Tablet 
 Enabled
Mobile
 Enabled

 

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Reference
    Checked
    Checked
    Stage
    Final
  2. Tags
    1. object picker
    2. target-groupb:customer