Related List

What It Is

Related lists are dynamic collections of records from other tables that share a relationship with the current record, displayed as embedded list views at the bottom of forms. They solve the fundamental problem of navigating connected data without requiring users to perform separate searches or remember complex relationships between records. When viewing an incident, related lists automatically show connected change requests, configuration items, tasks, and approval records — essentially creating a 360-degree view of all related information in a single interface.

Architecturally, related lists live within the form rendering engine in the base ServiceNow platform, controlled by the sys_ui_related_list table and associated with specific form views through the sys_ui_view table. They operate at the presentation layer but depend entirely on the underlying data model — specifically reference fields, extended tables, and many-to-many relationships defined in the database schema. Unlike list views or reports, related lists are contextual and dynamic, automatically filtering their queries based on the current record's field values and relationship definitions.

The data model relationship determines how related lists populate their records through three primary mechanisms: reference field relationships (where the related table has a field pointing back to the current record), reverse reference relationships (where the current table points to the related table), and many-to-many relationships through intermediate tables. Related lists automatically construct their queries using these relationships, applying security rules, domain separation, and access controls to ensure users only see records they're authorized to view. This automatic query generation includes complex joins and filtering that would otherwise require manual GlideRecord scripting or custom list configurations.

You cannot function without related lists in any enterprise ServiceNow implementation where users need to understand record relationships, track work progression, or access connected data efficiently. Incident management becomes impossible without related lists showing tasks, child incidents, change requests, and configuration items — forcing users into constant navigation between forms and manual searches. Change management workflows break down when users can't see affected CIs, approval records, implementation tasks, and related incidents from a single change record. Request fulfillment requires related lists to display catalog tasks, approvals, requested items, and fulfillment activities — without them, agents spend most of their time hunting for connected records across multiple modules.

System administrators manage related list configuration, including which lists appear on which forms, their display properties, and access controls — typically during initial implementation and ongoing customization. Application developers handle advanced related list behavior through custom relationship definitions, scripted queries, and dynamic filtering logic that goes beyond standard reference field relationships. Platform owners control the underlying table relationships and field definitions that make related lists possible, but they rarely interact with individual related list configurations unless major data model changes are required.

Recent ServiceNow releases have improved related list performance through better query optimization and lazy loading, reducing initial form load times when records have many relationships. Vancouver introduced enhanced related list personalization, allowing users to customize column displays and save personal views within related lists. Xanadu expanded related list scripting capabilities with additional client-side APIs for dynamic show/hide behavior and improved integration with Workspace and Agent Workspace interfaces, though classic UI form behavior remains unchanged.

Where to Find and Configure It

Primary configuration lives at System UI > Related Lists where you create, modify, and delete related list definitions, set their display properties, configure access controls, and define custom queries. Individual related list records can be accessed directly through sys_ui_related_list.list or by right-clicking any related list on a form and selecting Configure > Related Lists for immediate access to that specific configuration.

Form view association happens through System UI > Views where you add related lists to specific form views by editing the view record and selecting which related lists appear for that particular table/view combination. Studio provides related list management through the Forms section under each application, allowing scoped application developers to configure related lists within their application scope. App Engine Studio includes related list configuration in the Experience > Forms section with a more guided interface for citizen developers.

Related lists in action appear on any form where they're configured — most commonly visible on incident, change, request, user, and configuration item records in their default form views. Scoped applications can only configure related lists for tables within their scope or extend global related lists through application-specific customizations, while global scope allows configuration of related lists for any table in the system. The relationship definition that drives each related list lives in the data dictionary at System Definition > Dictionary where reference field configurations determine available relationship options.

How It Works Step by Step

Related lists operate through a sophisticated query generation and rendering process that combines form configuration, data model relationships, and security enforcement in real-time. When a form loads, the system reads the form view definition to identify which related lists should appear, then examines each related list configuration to understand the relationship type, target table, and any custom filtering. The platform constructs dynamic queries based on these relationships, automatically building WHERE clauses that link related records to the current record through reference fields, parent-child relationships, or many-to-many associations.

Security and access control processing happens at query execution time, applying user roles, domain restrictions, and field-level security to ensure each related list only shows authorized records with visible field data. The system applies any additional filtering from related list configurations, including custom where clauses, reference qualifiers, and conditional display rules based on the current record's state or field values. Each related list query executes independently with its own performance characteristics, caching behavior, and result limits, which explains why some related lists load faster than others on the same form.

The Execution Order

1. Form view resolution identifies which related lists are configured for the current table and view combination through the sys_ui_view and sys_ui_related_list table relationships
2. Relationship analysis examines each related list configuration to determine the connection type (reference field, reverse reference, many-to-many) and target table
3. Query construction builds the SQL WHERE clause using the current record's sys_id and the relationship field definitions, including any custom filtering conditions
4. Security processing applies ACLs, domain separation, field-level security, and user role restrictions to the query before execution
5. Query execution retrieves the related records with configured limits, sorting, and field selection for display
6. Rendering and display formats the results as a list view embedded in the form, applying column configurations, row limits, and user personalization settings

// Common server-side pattern for custom related list filtering
var relatedGR = new GlideRecord('task');
relatedGR.addQuery('parent', current.sys_id);
relatedGR.addQuery('state', '!=', '7'); // Exclude closed tasks
relatedGR.addQuery('assigned_to', '!=', '');
relatedGR.orderBy('priority');
relatedGR.orderBy('due_date');
relatedGR.query();

// This query pattern underlies most related list behavior
// The 'parent' field creates the relationship to current record
// Additional filters can be applied through related list config
// Security and domain restrictions are automatically applied
// Results populate the related list display with proper formatting

// Related lists execute similar queries automatically
// But you can override with custom relationship definitions
// Or add conditional filtering based on current record state

Real-World Scenarios

Creating Filtered Change Tasks by Implementation Phase

Change managers need to see implementation tasks grouped by phase rather than showing all tasks in one long list, because changes often have dozens of tasks that span planning, implementation, and validation phases. This requires creating separate related lists that filter tasks by custom phase field values to provide better visibility into change progression.

Navigate to System UI > Related Lists and create three new related list records: set Name to Planning Tasks, Table to change_task, and Related list to REL:change_request=change_request^u_phase=planning. Repeat for implementation and validation phases, changing the phase filter accordingly. Add all three related lists to the change request form view through System UI > Views.

Watch for performance issues if change records have hundreds of tasks — consider adding row limits through the Maximum entries field on each related list record. The phase field must exist and be populated on change tasks for the filtering to work properly. Users with restricted access to change tasks will see empty related lists even if tasks exist, so verify ACL configurations align with your intended visibility.

Showing Only Active Assignment Group Members on User Forms

HR teams reviewing user records need to see current group memberships without being confused by historical assignments or inactive group relationships. The default group member related list shows all assignments regardless of status, making it difficult to understand current access and responsibilities.

Create a new related list record with Name set to Active Group Memberships, Table to sys_user_grmember, and Related list to REL:user=sys_id^group.active=true. Replace the default Group Members related list in the user form view with this new filtered version by editing the view and substituting the related list reference.

The filter joins to the group table to check the active status, which can impact performance for users with many group memberships — monitor form load times after implementation. Users without read access to the sys_user_grmember table will see an empty related list regardless of their actual memberships. Consider adding a custom column showing the group's type or category to provide more context about each membership relationship.

Dynamic Related List Visibility Based on Record State

Service desk agents need to see approval-related lists only when incidents are in pending approval states, because showing empty approval sections on every incident creates visual clutter and confusion. Different incident workflows require different related lists to be visible at appropriate times throughout the resolution process.

// UI Script for conditional related list display
function showApprovalRelatedLists() {
    var state = g_form.getValue('state');
    var approvalStates = ['4', '5']; // Pending Customer, Pending Vendor
    
    if (approvalStates.indexOf(state) !== -1) {
        // Show approval-related sections
        gel('related_lists_approval').style.display = 'block';
        gel('related_lists_approvers').style.display = 'block';
    } else {
        // Hide approval-related sections
        gel('related_lists_approval').style.display = 'none';
        gel('related_lists_approvers').style.display = 'none';
    }
}

// Call on form load and state changes
addEventListener('state.change', showApprovalRelatedLists);
showApprovalRelatedLists(); // Initial load

This requires custom client scripting because related list conditional display isn't available through standard configuration — the script must be added to the form's onLoad and onChange events through UI Policies or Client Scripts. The DOM element IDs for related lists follow predictable patterns but can break with platform updates or customizations. Test thoroughly in your target UI framework (Classic, UI16, Workspace) since related list rendering differs between interfaces and the script may need adjustment.

The Classic Mistake

Admins frequently create related lists by navigating to Form Design > Related Lists, clicking New, and selecting a table without ensuring the reference field exists. They set the Table field to incident and the Name to "Related Incidents" without configuring the Reference qualifier or verifying the reference field exists on the incident table. The Parent table shows as the current form's table, but there's no actual relationship defined. When they save and view the form, the related list appears but shows either no records or, worse, all incidents in the system depending on ACL configuration.

This fails because ServiceNow queries the target table using the current record's sys_id to find matching reference field values, but if no reference field exists, the query returns empty or defaults to showing all records the user can see. Users see either a blank related list or thousands of unrelated records, making the form unusable. The relationship appears to work in Form Designer because ServiceNow doesn't validate the reference field existence during configuration. This is non-obvious because the related list UI appears correctly configured, and many admins assume the platform automatically handles the relationship logic.

// First: Create the reference field on incident table
// Field name: parent_change
// Type: Reference
// Reference: Change Request [change_request]
// Reference qualifier: active=true

// Then: Configure the related list
// Table: incident
// Name: Related Incidents  
// Reference qualifier: parent_change=${sys_id}
// Or use the relationship field directly
// Parent table: change_request
// Relationship field: parent_change

// Alternative: Use dot-walking for existing relationships
// Reference qualifier: caller_id.manager=${sys_id}
// This finds incidents where caller's manager is current record

When to Use This vs Alternatives

Related lists are the right choice when you need users to see, create, and manage child records directly from the parent record's form, and when a clear foreign key relationship exists. They excel when users need immediate context about connected records without navigating away from their current work, such as viewing incidents related to a change request or seeing all requests submitted by a user.

Choose Related Lists When

Use related lists when users need inline editing capabilities and the relationship is one-to-many with a direct reference field. They're superior to embedded lists because they provide full list functionality including filtering, sorting, and bulk operations. Reference field lookups and dot-walking queries fall short here because users can't see the full dataset or perform mass updates on child records from a single location.

Use Embedded Lists Instead

Choose embedded lists when the relationship data is simple, read-only, or when you need custom formatting that related lists can't provide. Embedded lists excel for displaying calculated summaries, metrics, or when the related data comes from complex GlideRecord queries that don't map to standard reference relationships. They also work better when you need the list to update dynamically based on form field changes without page refreshes.

Use Both Together

Combine related lists with UI policies or client scripts when you need the list contents to drive form behavior, such as making fields mandatory when related records exist. Use related lists alongside embedded lists when you need both detailed record management and summary information—the embedded list shows totals or key metrics while the related list handles the detailed record interactions. This pattern works well for expense reports with line items or change requests with implementation tasks.

Platform Interactions & Side Effects

• ACLs on the target table control visibility and editability of related list records, with *.list operations determining what users see and *.write controlling inline editing capabilities
• Business Rules on the target table fire normally for inline edits, but current.operation() returns update instead of insert for new records created through the related list
• Form sections and related lists are stored in sys_ui_related_list table with view and sys_domain fields determining scope and inheritance across domain separations
• Update Sets capture related list configurations but miss custom views and list layouts, requiring manual migration of sys_ui_list and sys_ui_view records
• Client Scripts and UI Policies targeting related list fields use g_list object instead of g_form, and changes don't trigger form modification indicators
• Reference qualifiers execute server-side for each related list load, creating glide.invalid_query.fields warnings in System Log when field references are invalid
• Performance degrades significantly when related lists lack proper indexing on reference fields, causing full table scans visible in stats.do slow query logs
• Audit records in sys_audit show the parent record's sys_id in the reason field when child records are created through related lists
• Domain separation applies independently to parent and child records, potentially hiding related list data when domains don't align with glide.sys.domain.delegated_administration property settings
• Mobile and Service Portal interfaces ignore related list configurations entirely, requiring separate sp_widget or mobile form customizations to display related data

Debugging and Troubleshooting

The most common failure symptoms include related lists appearing empty when records should exist, showing too many unrelated records, or displaying "Loading..." indefinitely. Users report seeing related lists that worked previously but suddenly show no data after system updates or configuration changes. Admins notice that new related lists appear in Form Designer but don't show on actual forms, or existing lists lose their custom formatting and revert to default layouts. Performance issues manifest as forms taking 10-30 seconds to load when multiple related lists are present, with users experiencing timeouts on record saves.

Start debugging by checking System Log > All for SQL errors and invalid field references, which appear as "Invalid table.field reference" or "ORA-00904: invalid identifier" messages. Use System Diagnostics > Stats to identify slow queries related to your target table. Navigate to System Definition > Tables & Columns and search for your reference field to verify it exists and points to the correct table. Check System UI > Related Lists to examine the exact configuration, paying attention to the Reference qualifier field for syntax errors.

Common error messages include "GlideRecord query invalid" in application logs when reference qualifiers contain typos, "Access denied" messages indicating ACL issues on the target table, and "List not found" errors when custom list layouts are missing from the target environment. Browser console shows JavaScript errors like "g_list is undefined" when client scripts attempt to manipulate related list data incorrectly. Database connection errors appear as "Connection pool exhausted" during high-volume related list loading, while session timeout errors manifest as "User session invalid" when complex queries take too long to execute.

Diagnostic Checklist:

• Verify the reference field exists on target table and has correct reference specification
• Test reference qualifier syntax by running it directly in a background script with current record values
• Check ACLs on target table for list, read, and write operations for the current user's roles
• Validate that custom list layouts and views exist in the target environment
• Confirm domain separation settings align between parent and child record domains
• Review business rules on target table for conditions that might prevent record display
• Check system property settings for list limits and performance constraints affecting related list display

Quick Reference

• Related lists display maximum 1000 records by default, controlled by glide.ui.per_page system property
• Reference qualifiers using ${sys_id} don't work on new records until after first save because no sys_id exists yet
• Inherited tables show related lists from parent table configurations unless explicitly overridden at child table level
• Form views with suffix _mobile require separate related list configuration, they don't inherit from default view
• Dot-walking in reference qualifiers supports maximum 3 levels deep: caller_id.manager.department works, but fourth level fails
• Related lists on extended tables automatically include records from parent table unless sys_class_name=${sys_class_name} is added to reference qualifier
• Custom list controls like slushbuckets and tree pickers don't work in related lists, only standard list view controls are supported
• Related list order is determined by order field in sys_ui_related_list table, with 100-unit increments recommended for easy reordering
• Dictionary overrides on reference fields affect related list behavior globally, not just for specific forms or views
• Related lists bypass workflow and approval engines completely—state changes made through inline editing don't trigger approval processes