- edited by
Maria Gabriela
What You Will Learn
By the end of this post, you will be able to:
-
Understand what the List Controller Transform Script is and why it was initially introduced
-
Configure the transform script through the Advanced section of the List Controller in UI Builder
-
Customize row, column, cell, and group context actions using the script's built-in API calls
-
Apply best practices to keep customizations clean, maintainable, and upgrade-safe
The Problem With One-Size-Fits-All Lists
If you have spent time building workspaces in UI Builder, your list looks great out of the box, but stakeholders want more. Perhaps the Caller field should display as plain text instead of a hyperlink. Maybe you need a dynamic icon column that reflects incident priority. Maybe your team uses groupings that do not map neatly to column values.
Before the Vancouver release, addressing these requests meant submitting an enhancement record, or modifying increasingly cumbersome API configurations. The existing Seismic list component simply did not offer an easy path to fine-grained control. The List Controller’s Transform Script changes that.
What is the Transform Script?
The transform script is a server-side script exposed through the List Controller in UI Builder. It executes after the platform fetches your GlideRecord data, giving you the ability to define your rows and columns exactly how you want them. Think of it as a transformation layer sitting between your raw data and your final rendered list to your users.
Since the script runs server-side after data fetch, you have authority on how the records display. You can evaluate field values, apply conditional logic, and reshape the how the list displays accordingly. The result is a list that looks and behaves exactly the way your organization needs, that simply requires a ServiceNow developer instead of a formal product release.
Things that can be Customized
The transform script exposes a set of API calls on the List Controller that correspond to the different levels of the list structure. Each call accepts an edit actions object where you define your customizations.
-
To customize row-level context actions, use
editRowActions(editActionsObj). This controls the actions that appear when a user interacts with a full row, such as right-clicking or using a row action menu. -
To customize column header actions, use
editColumnHeaderActions(editActionsObj). This is useful when you want to modify or extend what happens when a user interacts with a column header, such as the default grouping action. -
To customize cell-level actions for a specific column, use
editCellActionsForColumn(editActionsObj). This lets you tailor behavior at the individual cell level for targeted columns. -
To override cell actions entirely, use
editOverrideCellActions(editActionsObj). This is the right choice when you want to replace default cell behavior wholesale rather than extend it. -
To customize group-level actions (for grouped rows), use
editGroupActions(editActionsObj).
You can also control where row actions appear in the table. Setting the positioning property to 'start' places row actions on the leftmost side of the table, while 'end' positions them on the right.
Setup
Getting started with the transform script takes only a few steps inside UI Builder.
Best Practices
-
Start with the template. The auto-populated script template is your friend. It documents every available hook with commented examples. Read through it fully before writing your own logic to avoid reinventing what is already there.
-
Use Customization arguments for reusability. If you have logic that depends on variable inputs (such as a field name or a threshold value), pass those through the Customization arguments rather than hardcoding them in the script. This makes your scripts easier to reuse across different list instances.
-
Test in a sub-production instance first. Transform scripts execute server-side on every data fetch. A logic error or infinite loop can degrade list performance for all users on that page.
-
Lean on built-in properties before scripting. The List Controller has a growing set of configuration properties. Check those first. Script-based customizations are more powerful but also carry more maintenance responsibility.
