Related Lists

Related lists appear at the bottom of forms and contain records from the tables related to the current record. For example, an Employee (employee) record contains the User Role related list. It displays records from the User Roles (sys_user_has_role) table related to the current record.

There are two types of related lists:

• Referenced related lists have a direct reference to another table through the ID of the current record. For example, a record in the Table A contains the ID of the record from the Table B, then the referenced record in the Table B will have a related list with the record from the Table A in it. This connection is provided by the Reference, List, and Document ID column types.
• Scripted related lists do not have direct references to each other. See the Scripted Related Lists section of this article.

In related lists, users can view and edit information like in any other list, and administrators can configure their appearance on forms by configuring the form layout.

To narrow the list of records in a related list, use the condition builder. Note that the set filters will not be saved as default. To apply a complex filter to a related list, use a scripted related list.

Add a related list element

To add a related list to a form, complete the steps below:

1. Open the form to which you need to add a related list.
2. In the burger menu , select Configure → Related Lists → Layout.

3. Configure sets of related lists by moving the elements in the heapselect: 

   

   
   

   The Available box contains a list of related tables you can add to the form.

   The Selected box contains a list of related tables displayed on the form.

   Edit the related lists area with the following actions:

   • Move elements by dragging them or using the  and  buttons.
   • To remove or add all the fields, click the  or  button.
   • To change the order of the elements, drag them or use the and buttons.
   • To move several scattered elements at once, select them with the Ctrl key pressed and drag them from one box to the other.
   • To move many elements in a row, click the first and last elements with the Shift key pressed, and drag them from one box to another.
4. Click Save to apply the changes.

The title before the arrow (→) stands for the table storing related records. The title after the arrow (→) stands for the field, referring to the current record. That is, Incident Task→Parent will display records from the Incident Task table that have the current record ID in the Parent field.

There may be more than one field in one table: the Change Request (itsm_change_request) table may contain references to the current record in the Caused by incidents, Parent, Related incidents, and Resolved incidents columns.

Create a record in a related list

You can create records related to the current one through related lists. For example, you can create a change task for a change request record.

To create a record in a related list, complete the steps below:

1. Open the record to which you want to add a related record.
2. In the Related Lists area, select the tab you need.
3. Click New, fill in the fields.
4. Click Save or Save and exit.

Edit records in a related list

You can add existing records to the related list of a current record. For example, you can add a user to existing groups:

To edit records in a related list, complete the steps below:

1. Open the record to which you want to add a related record.
2. In the Related Lists area, select the tab you need.
3. Click Edit.
4. Using a heapselect form, select the records to bind with the current record.
5. Click Save.

Scripted related lists 

Scripted related lists are different from referenced related lists – their connection is synthetic and provided by the script. That is, you can add relations between tables which do not reference one another in the Reference, List or Document ID column types. These lists can be configured via the Scripted Related Lists (sys_related_list_script) table.

To set up a scripted related list, complete the steps below:

1. Navigate to System Settings → Scripted Related Lists.
2. Click New and fill in the form.
3. Click Save or Save and exit to apply the changes.

Scripted Related List form fields

In your scripts, you are free to use the current and parent objects. The main purpose of this script is to generate a query that will be applied to the table specified in the Query from field.