Related Lists

Related lists appear at the bottom of forms and display records in tables related to the current record. For example, a Table (sys_db_table) record contains the Column related list. It displays records from the Column (sys_db_column) table related to the current record.

There are two types of related lists: referenced and synthetic.

• Referenced related lists are lists which have direct reference to another table through the sys_id of the current record. For example, a record in the Table A contains 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.
• Synthetic related lists are lists that 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 Form Layout.

To narrow the list of records in a related list, use the Condition Builder. Please note, that the set filters will not be saved as default. To apply a complex filter to a related list, use the scripted related list.

Adding a related list

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

1. Open the form to which you want to add a related list.
2. In the hamburger 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 drag-and-dropping or using the  and buttons.
   • To remove or add all the fields, click the  or  buttons.
   • To change the order of the elements, drag-and-drop them to use the and buttons.
   • To move several scattered elements at once, select them with the Ctrl key pressed and drag-and-drop them from one box to the other.
   • To move several elements in a row, click on the first and last elements with the Shift key pressed, and drag-and-drop them from one box to another.
4. Click Save to apply 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 which have the current record ID in the Parent field.

As in the example, 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.

Creating a new record in related lists

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

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

1. Open the record to which you want to add a related list.
2. Navigate to the Related Lists area and open the tab you need.
3. Click New, fill in the fields, and click Save or Save and Exit.

Editing records in related lists

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

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

1. Open the record to which you want to add a related list.
2. Navigate to the Related Lists area and open the tab you need.
3. Click the Edit button.
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, please 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 changes.

Scripted Related List form fields

In your scripts, you are free to use 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.

.