Related Lists in General
A related list is a display of records that have some association with the record you are viewing.
- A common type of related list shows records that are related to the form via a Reference field on the related records. This is often like a parent-child relationship.
- The many-to-many (m2m) relationship is another way to display associated records. In this case, multiple entries on one table can be linked to multiple entries on the other. For instance, a related m2m list might show multiple services you signed up for, but each service in turn can be tied to multiple other people.
A number of related list choices are available by default. For example, here is a screenshot of a custom form for “ABC Request” that has no related lists in this form view.
Let’s say that we want to add a couple of lists to it:
- one to show records from another table called ABC Item as child records
- one to show open catalog Requests put in by the person in the “Select user” field
Finding and selecting a related list
First, let’s see what lists are available already:
- Right-click in the form header and choose Configure > Related Lists.
This opens a related lists configuration screen that shows many lists that are available for that form for different uses.
For example, some lists can be related to the current record as children (they are displayed as entries ending in >Parent).
- The “ABC Item > Parent” list looks like what we want. Click it in the Available list, then click the right arrow to move it over to the Selected box.
- When it is moved over, click “Save”.
- Back on the ABC Request, refresh the page. A related list for ABC Items should appear.
But it may be that none of the available lists fits the need. For the next example, we don’t see an existing way to relate sc_request records to the ABC Request. That’s when creating a “defined” related list might provide what is needed.
Setting up a new Relationship (defined related list)
The Relationships form is used to define a search that you don’t have available through existing related lists. The documentation calls this list a “defined related list”.
Examples of relationships that are not available by default could be:
- A related list on Incident that has all open Catalog Requests for the Caller.
- A related list on Request that lists any open Problems against the Service on the request.
Back to the ABC Request: We want to list all open sc_requests for the user listed on the ABC Request.
- Go to System Definition > Relationships in the left-hand navigator.
- Click “New”.
The Relationship form opens.
- Fill in the fields:
- Enter a name that will be suitable for this relationship. For this example, we’re using the name “User Open Requests”. This is what will appear on the tab when this is added as a related list to a form in a tabbed view.
- “Applies to table” is the table on which you want to be able to add this as a related list.
- “Queries from table” is the table being reported on whose results will be listed.
- “Query with” is where the query code is placed.
Here is the code from this example:
current.addQuery(‘requested_for’, parent.u_user);
current.addQuery(‘state’, ‘<‘, 3);
- “current” refers to “Queries from “table”.
- “parent” refers to “Applies to table” (the one on which this related list will be displayed).
The first line is looking for Requests (sc_request) where requested_for matches the ABC Request “Select user” ( u_user) field whose record is being viewed. The second line limits the search to open sc_request records.
Note: There are two checkboxes not used in this example.
“Advanced” allows the table dropdown fields to be replaced with scripted location references.
“Simple reference” sets up a relationship based on a Reference field.
- Click “Submit”, or in the Context menu, “Save”.
Viewing the new defined related list
Let’s go back to the ABC Request form and add this new related list to its display.
- Right-click in the form header and select Configure > Related Lists.
- Find the name of the relationship in the Available list. Here we find “User Open Requests”, the name we gave this search earlier. Click it and click the right arrow to move it over to the Selected box.
- When it is moved over, click “Save”.
- Back on the ABC Request, refresh the page. The new list should display. If you use tabbed forms, you may need to select the new tab if another one is selected.
In this example, we see that the user listed on the ABC Request has two open Requests where they are listed as the “Requested for” person.
Conclusion
This article went over how to select existing related lists and how to create a defined relationship using a standard query. See the documentation for more information on any of these options. You might also look at some of the existing Relationships on your instance to get insight into how they are used.
