Skip to main content
Matrix42 Self-Service Help Center

Object Relations Grid


Object Relations Grid settings and grid properties configuration examples.


This how-to explains the basics of the Object Relations Grid settings and provides examples of the properties configuration.

Data type:  object reference.

The main purpose of the object relations grid type is to display data that is stored as a collection of relations of the main object of the edited layout and affiliated by specific criteria entries.   For instance,  Incident as the main object and a list of related Services that were affected by the current Incident.

For more information about Grid Control types and use cases see Grid Controls page.


Object relations grid is added and configured after the following steps:

  1. Administration application: open a Solution Builder;
  2. User Interface  Layouts: create new or edit existing layout;
  3. Data model: click "Customize" layout action and drag&drop an object reference data from the Data Model section on the layout designer canvas. 

Object relations grid is most often used in such layouts:

  • Dialog
  • Wizard
  • Preview
  • Landing page

Minimal required property settings

For proper grid displaying it is necessary to define the source of the related entries retrieval to the grid and columns to show. 

The following data model properties are minimum required for the grid displaying:

  • Relation: defines both the data source for the grid and columns to display.

The rest of the properties are assigned by default and can be optionally modified if necessary. Other properties refine the displayed records by specified criteria, define the add, edit, delete modes of the grid records and grid's look&feel.

Default object relations Grid characteristics

By default, each object relations grid with the configured minimum required properties results in the following page elements:

  • Heading row;
  • Column with a check-box for records multiple selection;
  • Columns  data sorting order (ascending/descending);
  • Add record from a list of existing items;
  • Delete selected relation(s) button;
  • Search field for displayed data filtering (global search and per each displayed field);
  • Pagination: all records are not shown on the same page but can be navigated through by selecting the next or previous page;
  • Refresh button for new records retrieval;
  • Export data (download .xlsx spreadsheet);
  • Column preview mode (show/hide specific columns).


Object relations Grid: preview example with default grid characteristics


Properties and settings

The table provides a detailed list of configurable object relations grid properties, their settings, and particularities overview.


Property group Property name Description Default Property setting example



Defines which data will be displayed in the grid. This field is required and should be selected manually:

  • ❌  not selected: by default the field is empty.  
  • set data from the Dada model: select necessary data of an object reference type  which serves as a source of the related entries that will be used in the grid:


Relation field suggests data from the model of an Object Reference type only. 

 Selected object reference is a relation attribute of a related to the main object Data Definition (see Administration → Schema → Data Definition → Relations tab) .

Stored in the system Data Definition is a database table with its own specific structure. This Data Definition can have a default Data query which defines a set of columns that can be displayed in the grid (applicable for cases when the Data query is based on a Data Definition). 

Set Column definition property in order to have necessary columns retrieved to the grid's header row. If the default Data query for the selected Relation does not exist, the system results in error only during the application's runtime. 

Selected value acts as a raw data source of a collection of relations that is filtered before displaying in the application's runtime according to additional criteria set in other properties of the Model section which are listed below.




Allowed types

  • ❌  not specified (default): data to show is retrieved based on the Relation field property;
  • 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 displayed in the grid data results.

For instance, selected Relation field value shows all available Services which are related to the Incident.  Specified Allowed Types narrow down the list of showed records by specifying the part of which Configuration Item the value of the Relation field must be.

Currently, Martix42 platform has 4 types of services: service, bundle, group, and set.

By specifying Service Bundle Configuration Item in the Static value bundle records only will be retrieved to the grid:




  • ❌  not specified (default):  extra data filtering is not applied;
  • specified: manually enter an ASQL expression to filter data retrieved to the object relations grid.

For instance, the following condition retrieves only records with a specific state:  object_relations_filter1.png

A combination of the specified in the Model property group fields are applied one after another and filter out the records to show:

  • Relation: retrieve related services;
  • Allowed Types: retrieved related services are bundles;
  • Filter: retrieved related bundles can be of a specific status only, for example only operational bundles can be shown. 

Browse where clause

  • ❌  not specified: extra data filtering is not applied;
  • specified: manually enter an ASQL expression containing filtering condition for the records that can be added as related items to the object relations grid. Condition from the Browse where clause field is applied to the list of records that can be added via Add existing item(s) button.  

For instance, object relations grid shows all Services that are related to the current Incident.  The services can have various statuses: operational, retired, approved, etc. Let's suppose that all the following services that can be added as related should be of an operational status only. Specify this condition in the Browse where clause  using an  appropriate ASQL expression:




Data Query

  • ❌  not specified
  • specified: enter existing Data query name (see Administration application → User Interface → Data Queries).  Specified Data query defines a set of columns to be displayed in the grid's heading row, their search mode, sorting, graphics, showing data of a specific range or filtering, and other settings defined in a particular Data query.
Screenshot 2023-06-20 at 17.59.36.png



help icon and tooltip for information displaying as:

  • ❌  not set: help icon is not displayed;
  • static value: manually entered text 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 profile settings;
  • model: displayed data is retrieved from a specified data model field.


Help icon with a tooltip displaying example



title of the grid. Can be set via one of the following options:

  • not selected:  grid title is empty and not displayed;
  • static value: manually entered title of the grid;
  • localizable:  grid title 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.


Localizable grid label example


Show label

Check-box options:

  • disabled: the title of the grid is not shown. 
  • selected:  grid's title display is enabled. The title is specified in the Label field.    
Disabled clipboard_e0da6a6ec8b063aa682bf127f8fc2b41f.png


  • Static value: check-box options
    • disabled (false): search field and all buttons displayed in grid's header row are available;
    • selected (true): header row is displayed but all options like add relation, search, pagination, etc. are disabled. Search is the only active field:
      Grid header row displaying example: disabled property is set to true.
  • Model: suggests boolean data options from the data model (true/false values)
False grid_disabled.png


  • Static value: check-box options
    • disabled (false): all options displayed in the grid's header row are available;
    • selected (true):  header row is displayed but all options except search field and export data button are disabled:
      Grid header row displaying example: read-only property is set to true.
  • Model: suggests boolean data options from the data model (true/false values)
False grid_read_only.png


  • Static value: check-box options
    • disabled (false): relations are optional;
    • selected (true): the relation is mandatory and the main object requires at least 1 added relation: 
      Required property is set to true: at least 1 relation is required to proceed
  • Model: suggests boolean data options from the data model (true/false values)
False grid_required.png

Enable filter of Configuration Item

Check-box options:

  • disabled (default): Add existing items(s) button suggests a list of all possible records that can be added as related to the main object. The list contains all available records from all possible Configuration Items the relation belongs to.
  • selected: enables additional data pre-filtering of the records that can be added as related by the Configuration Item name. Click  Add existing item(s) button to see Configuration Item filter. 
    For instance, an Incident with related Services is listed in an object relations grid. The system has 4 default service types and let's consider an example when there are too many records per each type of services. In order to improve the application's performance and simplify the search use pre-filtering by Configuration Item:
    1. Click Add existing item(s) button in the grid's heading row;
    2. Select Configuration Item filter from the list of auto-suggested options;
    3. Existing items of a specified Configuration Item  are listed in the grid and can be added as related objects: 


automatically generated name or identifier of the grid. 

The only required field for the grid saving, although without properly configured Relation property the entire grid is poorly displayed.

auto-generated object_relations_grid_name.png


Full Height

Check-box options:

  • disabled: the grid takes only a part of the page's working area and shows 10 first records. Use scrolling for other records preview
  • selected: the grid preview expands and covers the entire available space of the page's working area.
Disabled grid_full_height.png

Minimal Height, px

defines the fixed height of the grid displayed on the page. 

Set and measured in pixels, for instance: "100".

The specified height is spread upon the entire grid representation, including grid's header with default buttons area (export, columns preview), grid heading row and displayed records data.


Disable create

  • Static value: check-box options
    • disabled (false):  allows creating not only a relation but also a new related record item from the object relations grid:object_relations_disable_create_true.png
    • selected (true): create new related item button is not shown;
  • Model: suggests boolean data options from the data model (true/false values).  Create new item from the relation grid option displaying depends on the current value of a selected record.
True grid_disable_create.png

Disable add

  • Static value: check-box options
    • disabled (false):  new relations can be added from a list of existing items. Items which have already been added as related are not suggested in the list of items that can be added using Add existing item(s) button :
      Disable add property is set to false: add button is available.
    • selected (true):  new related records cannot be added; add button is no longer displayed in the grid's header row.
  • Model: suggests boolean data options from the data model (true/false values)ю
False grid_disable_add.png

Delete Actions

manually entered field value:

  • ❌  not specified (default): selected related object cannot be deleted from the system directly using object relations grid. Delete selected object(s) button is not shown in the grid's heading row;
  • specified:  choose from the list  of available in the system delete actions:grid_delete_actions.png

For Actions management see  Administration application  → User Interface  → Actions.

As a result, selected delete action allows deleting a relation and the entire related item record from the system via Delete selected object(s) button of the object relations grid: object_relations_delete_actions_grid.png

❌   delete_actions.png

Disable remove

  • Static value: check-box options
    • disabled (false): retrieved to the grid relations can be removed with a delete button:
    • selected (true):  displayed relations cannot be removed and the delete button is not shown in the grid's heading row.
  • Model: suggests boolean data options from the data model (true/false values).
False grid_disable_remove.png


Grid display on the page modes:

  1. Static value: check-box options
    • selected (True): grid displaying on the page layout template is enabled; 
    • disabled (False): the grid is not shown on the page layout template.
  2. model:
    • assigned model: select source of the data model;
True clipboard_ef748af5414dd44fb723697c41161887d.png

Hide Grid Header

Check-box options:

  • disabled: grid header is displayed on the page layout. The header includes:
    • the title of the grid ("Label");
    • standard buttons (export, columns displaying);
    • extra buttons (delete relation, add relation).
  • selected: header is not displayed,  only  grid  heading row with sortable columns titles and the available in the grid records are shown:
Disabled grid_hide_grid_header.png

Show "Selected items" panel

Check-box options:

  • Static value: check-box options
    • selected (True): "Selected items" panel is shown under the grid area of the layout;
    • disabled (False):  the "Selected items" panel is not used on the page; 
  • Model: suggests boolean data options from the data model (true/false values). 

Selected items panel provides an overview of multiple items selected on different pages of the grid:


The panel shows the Display Name of the selected items. The Display Name property value is retrieved from the Configuration Item of the selected object.

False selected_items_grid1.png

Enable row selection

  • Static value: check-box options
    • selected (true):  the first column of the grid is a column with check-boxes for grid records multiple selection and further processing:enable_row_selection1.png
      Enabled row selection displaying example: check-box option is selected.
    • disabled (false): the first column with check-boxes is not displayed in the grid.
  • Model: suggests boolean data options from the data model (true/false values).
True grid_enable_row_selection.png

Device visibility


This property allows improving user experience by managing device visibility options. For instance, the grid can be hidden from the preview when it is too large and contains a lot of columns that cannot fit the small screen of a mobile device.

The application checks the user device's screen resolution and shows or hides grid preview based on the selected check-box options settings:

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


Device visibility settings example: object relations grid is enabled for tablets only.

Enabled clipboard_eb901040d88572e905a56dde0cd58b948.png






Use Case: Dynamically add data to Object Relation Grid

Value of the Relations property

The data is loaded to the grid based on the Data Definition, specified in the Relation field, but the changes like adding or removing items are reflected in Value. On submitting the From with Relation Grid only appropriate actions are executed which also solves the problem of concurrent editing of relations.

Value is a complex object which reflects the changes of data relations. Due to the possibility to deal with a huge amount of the related objects, the Value does not keep the array of all related objects but only a list of data changes made during the current session. 

 In simplified form, the modified by the Value data relations may look as follows:

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

Pre-filling object relations grid dynamically 

The example below shows how to modify existing object reference specified in the Relations property of the object relations grid in order to add an extra condition of data processing before showing it in the grid.

The described case is only applicable to those object references that were added to the Relation field directly from the Data Model and modified accordingly.  That said, it is not necessary to create a new property in the Context of the Data Model, but it is required to edit the existing data property. 

Dynamic data pre-filling in the grid can be useful when the data modified in one area of the layout affects records retrieved to the other area of the layout, containing the object relations grid. For instance,  creating a Dialog for data editing: when the data entered in the edit dialog is saved and a new object is created, this object should be also immediately displayed in the Object Relations Grid of the same layout or of the other page layout due to some specific conditions or context, e.g. current user, some interactive input, etc.

The additional conditions that allow dynamical data pre-filling are specified in:

  • the existing object reference, set as Relation source;
  • defined via Edit property → Configure calculated property  →  Advanced Mode using JavaScript expression.  

The example below shows how to modify the Value of the existing object reference property  in order to retrieve all Incidents of the user defined as initiator and dynamically add these entries to the Related Incidents:

  1. Retrieving Incidents by Initiator:  create Data Source which obtains all the related incidents depending on a specified Initiator (for example,  InitiatorIncidents  property);
  2. Specifying conditions for dynamic data retrieval:  define special logic for the property which serves as a source of the data to show in the grid (Incident.ChildActivities) by  

a. setting related data model properties that should be taken into account in the condition and trigger displayed in the object relations grid data changes;

b.  specifying  JavaScript expression which is a condition that results in dynamic data pre-filling of the object relation grid:


Code to copy:

if (incidents.$value.length) {
  $value.AddedRelations = incidents.$ {
      return inc.ID;
  $value.RemovedRelations = [];
return $value;
  • Was this article helpful?