If you manage ServiceNow workspaces, you have probably noticed that at times, new UI Builder features roll out faster than the product-focused Workspaces adopt them (ex. CSM Configurable Workspace or HR Service Delivery Agent Workspace). The platform releases quarterly updates with enhanced UI Builder components like the new list template with gallery view, but individual Workspaces can take a release or two to incorporate these enhancements. That leaves Workspace admins in a position where features exist but may not be actively leveraged yet.
This guide shows you how to manually migrate to the new list templates in UI Builder so you can access the latest features immediately, whether you need to adopt new capabilities in custom workspaces or prefer not to wait for out-of-box workspace plugin updates.
What You Will Learn
By the end of this post, you will be able to:
-
Understand when and why to create list page variants in UI Builder
-
Successfully migrate from legacy list components to new list templates with gallery view (note: similar process can be used for adding the standalone list bundle onto any existing page)
Prerequisites
Before you begin, verify the following:
-
Your UI Builder plugin is updated to the latest version available for your release (at the time of writing Zurich release and UIB version 28.2.73)
-
Your Workspace store app (for ex. CSM Configurable Workspace) is updated to the latest version
-
You have the necessary roles to edit UI Builder pages (typically admin or ui_builder_admin)
-
Review the current List component settings to see whether it has been updated by checking whether the layout options has an option for a gallery view
To check store app versions, navigate to Application Manager and search for "UI Builder" as well as your workspace name. Note: you may need to click “Sync Now” in the Application Manager, even if it says it recently synced.
Step-by-Step Migration Process
Step 1: Access UI Builder and Open Your Workspace
In the filter navigator on your ServiceNow home page, navigate to All > UI Builder and open the workspace you want to modify. For this example, we will use the CSM/FSM Configurable Workspace.
Once inside the CSM/FSM Configuration, locate and select the List > View Settings from the pages list. Note: you may select the blue “List” button to the right of the search
Step 2: Create a Variant Using the List Page Template
At the settings page, click on the Create variant plus icon located at the top gray bar. Then select Add variant to open the variant creation dialog. This allows one list page to have multiple versions, so different users and groups can see their own personalized version of the list page (ex. Case managers able to see a list of cases with additional columns that other agents do not get to see).
Instead of choosing "Create from scratch," look for List page template, and select Use template. This template includes all the necessary configurations for the enhanced list component, including gallery view support.
Step 3: Configure Variant Properties
In the variant configuration screen, provide a descriptive name for your variant (ex. "List Academy"). This name is for internal administrative reference and will not be visible to end users.
Next, configure your audience settings. Audiences determine which users will see this variant. If you want all users to access the new list template immediately, you can leave the audience set to "All" or create specific audience rules based on roles, groups, or other criteria. Audience targeting is particularly useful if you want to pilot the new list view with a subset of users before rolling it out organization-wide.
Set the order value to control variant precedence. Lower order numbers take priority. If you want your new variant to display by default, set it to the lowest number in the order (note: negative numbers are included as well).
Click save. Once the variant is created, you will see it appear at the top of your variant list. The variant is now active, but you need to configure which layout options users will see.
Step 4: Configure List Layout View
Click into the Editor view of the newly created list page located at the top. Select the Presentational List in the left content tree. In the component configuration panel on the right, locate the Layouts property. You will now see three choices:
-
List only: Users see only the traditional list view
-
Gallery only: Users see only the gallery card view
-
Both list and gallery: Users can toggle between list and gallery views using a view switcher
Select Both list and gallery to give users maximum flexibility. You can also configure which view displays by default when the page loads (list or gallery).
Click Save to apply your changes.
Step 5: Preview and Test
After saving your changes, use the Preview button in UI Builder to test the new list page. Alternatively, you can open the list view in your CSM workspace. You should now see a layout switcher that allows you to toggle between list and gallery layouts.
Test the following:
-
Toggle between list and gallery views to confirm the view switcher works
-
Click on a record to verify the form modal opens correctly from the gallery view
-
Verify that all list actions (filters, search, bulk actions) function as expected
Step 6: Verify Variant Conditions and Promote
Return to the variant settings and confirm your audience and conditions are set correctly. Remember that variants are evaluated in order, and the first matching variant will display. If you have multiple variants for the same page, ensure your new list template variant has the correct order value to take precedence.
Once you have verified everything works as expected, promote your changes using an update set. The new list template with gallery view is now live for your configured audience.
Pro Tips for Success
-
Test in Sub-Production First: Always create and test variants in a development or test instance before deploying to production. This allows you to refine audience targeting and verify compatibility with any custom configurations.
-
Document Your Customizations: Maintain a record of which workspaces have custom list page variants and why. This documentation helps future administrators understand what has been customized and prevents confusion during upgrades.
-
Use Audience Targeting Strategically: Do not feel obligated to roll out new features to all users immediately. Consider piloting the gallery view with a specific department or user group to gather feedback before expanding access.
-
Keep Variant Orders Organized: As you create more variants over time, periodically review your variant order values to ensure the correct variant displays for each audience. A misconfigured order value can cause unexpected behavior.
-
Apply the Same Pattern to Other Components: The process described here for list components applies to other UI Builder components as well. If you see a new feature available in component properties that is not yet adopted by your workspace, you can use the same variant creation approach to access it.
