Skip to main content
Matrix42 Self-Service Help Center

Related Objects Picker Control


Related Object Picker Control allows selecting multiple Objects. The control specially designed for handling relations to multiple objects in Dialogs.

The behavior of the control is identical to Objects Picker control, which also able to select multiple objects, but these two controls have absolutely different Value model (how the selected objects are stored in Value property), what makes one of them best suitable for using in Wizards, whereas another (Related Object Picker) better fits for Dialogs.

How to Use Related Objects Picker in Run Time

Click the Related Objects Picker field in run time and start typing the name of the object you would like to add to the field or click the lookup icon for a complete list of options. 

Several objects added to the Related Objects Picker control in the run time are displayed as shown in the image below, for instance, the Action settings and the Applications where the Action can be used is assigned with the Related Objects Picker control:


How to Set up Related Objects Picker

Related Objects 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, which 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.


By default, the Related Objects Picker Control can be used only in the Dialog page layout.

Users with Administrator rights can change the default settings and add the control to other types of layouts via Supported Widget Types field in the Administration application → User Interface → Control Descriptors → Edit action → Advanced tab.

Layout Designer 

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

  • Locate an existing Related 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 Related Object Picker control data type (Object Reference). The controls added from the Data Model are suggested as follows:


  • Click the control on the canvas to open up its properties in the right-hand panel. Properties that the Related Object Picker has in Layout Designer are defined in the Related Object Picker Control Descriptor.

Minimal required property settings   

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

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

  • Value: the field that serves at the same time as a source of the suggested in the related object picker values and as the attribute of the Data Definition that stores the chosen from the picker values. Only Object Reference attributes can be used;
  • Label: the title of the displayed field.

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

Additionally, you may need to configure:

  • Display expression: if the reference to the Data Definition (see Value property) does not have the default Display Expression, specify an ASQL expression for correct displaying of the suggested object names in the related objects picker list.
  • Column definition: a set of columns that are displayed on the Select Object(s) page when the user clicks Show More link or the lookup icon.


Most of the properties and their configuration are the same as described in the Object Picker article. This section provides only the differences in the properties configuration.

Value (Model)

The main property of the Control keeps the data about selected objects. The data structure principle is fully identical to the structure of the Value of the Objects Relation Grid.  All the associated related objects are stored in the Database and directly retrieved by the control for display, and are not reflected in the Value data. Value data stores only the changes in relations, e.g. which Objects have been added or removed in comparison with the persisted state (related objects stored in the Database).  On submitting the Dialog with such control the affected changes (added or removed objects) are applied on the server.

The following example demonstrates the Value structure:

    AddedRelations:['{id1}', '{id2}'],
// where {id1}, {id2}, {id3} - unique objects identificators (guid)

The Value property includes both Entity Class and Relation Attribute Name. Both attributes specify the schema relation which is handled in the Control.

Entity Class is the name of the Data Definition which owns the relation, and the Relation Attribute Name is the name of the schema relation.
For example, for the relation which stores the members of the Role, the Entity Class = "SPSSecurityClassRole", the Relation Attribute Name = "Memebers"

Object Id (Model)

Sets the Id of the Object which owns the Relation. When control is used on Dialog, the setting of the Property is optional, as the ID is automatically detected from the Dialog context. 

In case when control is used for handling N:M relation in Multifragment Data Definition (multiple records in Object), the ID of the Fragment need to be assigned to the Object Id Property.

Selected Items (Model)

Specify the attribute of the data model that will store the following data from the items that have been selected in the application run time:

  • Id
  • ObjectId
  • EntityType
  • DisplayString


Selected IDs (Model)

Specify the attribute of the data model that will store the IDs of the fragments that have been selected in the application run time.

You can set up these returned values (Selected Items and Selected IDs) 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 for the Object Picker. Similarly, adjust the example for the Related Objects Picker using Selected Items or Selected IDs accordingly.

Other Properties

For the rest of the Properties see relating Object Picker control, which has quite the same properties and settings, with the only difference, it picks a single object only.

How To: Dynamically add related objects to Related Objects Picker

The adding objects to control dynamically (automatically, based on some events on the form) is completely identical to doing that in the Objects Related Grid. For more information see the Use Case: Dynamically add data to the object relation grid page.

  • Was this article helpful?