Skip to main content
Matrix42 Self-Service Help Center

Object Picker

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 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 up 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 the correct displaying of 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 steps, 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 check-box to allow users to reset the filtering conditions for the suggested in the 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
Column definition

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

column_definitipon_eg.png

  • ❌  not set: a default Data Query for the specified Data Definition is used;
  • set: add a technical name of the Data Query that should be used instead of the default one.
column_definition_LD.png
Display Expression

ASQL expression which determines the Display Name of the selected object, or names of the objects in the auto-complete dropdown list.

  • ❌  not set: if no Display Expression defined, the system uses standard Display Expression defined in the schema for the specified Data Definition.
  •  set: the ASQL expression is applied to the Schema class specified in the Data Definition property:
    display_expression_eg.png 
display_expression_LD.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

 

  • Was this article helpful?