Overview
In this guide, we walk through the process of adding a custom icon to an existing record page sidebar in UI Builder. This icon, called Related Records, will display a filtered list of incidents associated with the caller of the current record.
What You’ll Learn:
• How to create a new page in UI Builder.
• How to modify an existing record page and add a new icon.
• How to configure a list component to show relevant records.
• How to apply dynamic filters using data binding.
• How to enable navigation to related records from the list.
📢
Prerequisites
Before starting this tutorial, ensure you've completed the necessary prerequisites to follow along smoothly. Here are some key articles you might need to reference:
- How to make a workspace from scratch: In this article, we created the Customer Support Workspace.
📌
Troubleshooting
If at any point something isn't working, try clearing the UI Builder cache.
Within your page variant editor in UI builder, click the hamburger menu icon at the top-left, go to Developer > Clear UI Builder Cache. You can also try clearing your local browser cache.
Step 1. Open UI Builder
1. In your ServiceNow instance, use the Unified Navigator to go to Now Experience Framework > UI Builder.
2. When UI Builder opens, you should see the UI Builder "Home” screen.
3. Select Experiences Tab at the top of the screen.
4. Open the Customer Support Workspace.
Step 2. Creating a Page
1. In the Experience Editor, find Pages and variants.
2. Click the + icon next to it.
3. Select Create a new page.
4. Choose Standard record page.
5. Enter the page name: “Icon Record” (URL path auto-populates). Click Continue.
6. Review the parameters and click Looks good.
7. Leave the variant name as “Default” and select Create.
8. In the Page Variant Editor, navigate to the cylinder icon (top-left corner) to edit page parameters:
• Change Table to
Incident. • Change sys_id to any incident record.
9. Select Apply.
Quick Tip
Remember to SAVE your record.
Step 3. Add a Custom Tab
1. Navigate to an existing page by clicking the dropdown menu next to the page variant name.
2. Click on Default variant under Record > Default.
3. In the Content Tree, navigate to Tab Sidebar, or click on the Contextual Sidebar in the Page Variant Stage Panel.
4. In the Component Configuration Panel, click + Add to add a new tab.
5. Select “Start from an empty container”, then click Next .
6. Under Tab Settings, configure the following:
• Tab Label: Related Records
• Tab ID: (Auto-populated)
• Icon: Accessibility Outline
7. Click Create.
8. The new tab appears under Tab Property alongside existing tabs. You can drag and drop to reorder.
9. In the Content Tree, go to Tab Sidebar > Related Records and click + Add Content.
10. Search for “List” and select List-Simple component.
11. In the Component Configuration Panel, update:
• Component Label: Related Records List
• Component ID: related_record_list
12. Click Apply .
Step 4. Configure the List Component
1. In the Component Configuration Panel, go to the Configure tab and change the Table Property to:
Incident . 
2. Click Edit Fixed Filter, then add:
(We will be using the caller and sysID fields to display related incidents reported by the same caller)
• Caller is (click Bind Data Icon) → Select under Data Type: Data Resource > Form Controller > forms > fields > caller_id > value
3. Click Apply.
4. Click AND to add another condition:
• Sys ID is (click Bind Data Icon) → Select under Data Type: Data Resource > Form Controller > sysId
5. Click Apply.
6. Verify your Edit Fixed Filter Conditions and click Apply.
5. In the Columns Property, click + Add, then add:
• Number
• Caller
• Short Description
• Category
6. Scroll to Title Property and update it to: “Incident Related Records for Caller”.
Step 5. Configure Navigation for Record Selection
1. In the Component Configuration Panel, go to the Events tab.
2. Locate the pre-configured event Reference Link Clicked, then click Add Handler.
3. In the modal, select Link to Destination Event Handler.
4. Click Continue.
5. Under Select Destination, choose Pages in Current Experience.
6. In the modal, select “Icon Record” Page.
7. Under Table Property, click the Bind Data Icon, then select under Data Type:
• Event Payload > Table
8. Click Apply.
9. Repeat for sysId property:
• Event Payload > sys_id
10. Click Apply.
11. Verify properties and click Select.
12. Check “Open in New Tab” checkbox, then click Add.
Step 6. Testing & Previewing
1. In the Dropdown Menu, select Preview and click on Open URL Path.
2. Navigate to the Contextual Sidebar on the Record Page and click on the newly created icon.
3. The sidebar should now display Incident-Related Records for the Caller.
📌
Troubleshooting
If at any point something isn't working, try clearing the UI Builder cache.
Within your page variant editor in UI builder, click the hamburger menu icon at the top-left, go to Developer > Clear UI Builder Cache. You can also try clearing your local browser cache.
Conclusion
Congratulations! 🎉 You've successfully added a custom icon to your record page! Now, you can easily view and navigate to related incident records, enhancing workflow efficiency
If you found this guide helpful, consider sharing it with your peers or teams looking to refine their UI Builder skills and enhance record page customization.
Keep an eye out for future tutorials where we'll explore even more advanced UI configurations and dynamic filtering techniques. Until then-happy building, stay innovative!
Check out the Next Experience Center of Excellence for more resources
2 Comments
