Overview
In this tutorial, you will create a custom Declarative Action in UI Builder that adds a 'Check SLA' button to the Customer Support incident list page within the Customer Support Workspace. When clicked, this action will open a new tab displaying the associated Task SLA records of the selected Incident.
We will cover:
- Renaming the UI Builder page variant and component
- Creating a UX Action Configuration and Page Property
- Assigning the action to the Incident list
- Mapping the action to an event using UX Add-On Event Mapping
- Channeling the Event using a client script to open a record in a specific related tab
Authored by: @sophiasemga
📢
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.
What are Declarative Actions?
Declarative Actions (DAs) are like UI Actions but built specifically for Next Experience-based UIs (Workspaces and UI Builder).
UI Actions work in both the traditional Core UI (the standard ServiceNow interface) and Next Experience UIs. However, Declarative Actions do not work in the Core UI—they are designed to be more flexible and customizable for modern interfaces like Workspaces and UI Builder.
For example, if you add an "Assign to Me" button using a Declarative Action, it will only show up in Workspaces and UI Builder—not in the traditional ServiceNow interface.
|
Features
|
UI Action
|
Declarative Action
|
|
Where They Work
|
Core UI + Workspaces
|
Only in Workspaces & UI Builder
|
|
Supported Areas
|
Lists, Forms
|
Lists, Forms, Playbooks, Catalog Wizards, Kanban Boards, etc.
|
|
Implementation Options
|
Client Script, Server Script
|
Client Script, Server Script, UXF Client Action
|
Implementation Methods for DAs
- Client Script – Runs code on the user's browser (e.g., opening multiple records in new tabs).
- Server Script – Runs code on the server (e.g., approving a record by updating a related approval table).
- UXF Client Action – Triggers actions within UI Builder, handled by event handlers (e.g., opening a record in a sub-tab or modal).
Step 1. Open UI Builder
1. In your ServiceNow instance, use the Application 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. Open UI Builder and get the Parent Macroponent
We’re customizing the page variant and giving components meaningful names and IDs. This makes it easier to reference them in mappings later and helps differentiate the variant and components from out-of-box defaults.
1. In the Experience Editor, find Pages and Variants.
2. Locate the Customer Support List page in the list of pages.
3. Under the existing Default page variant, click the Settings link on the right.
4. Click on the Open records drop-down menu and select Page Definition.
5. Change the Name field from Default to: Custom List.
6. Right-click and save, then copy the name (Custom List) to a notepad for later use. (This name will be used as the Parent Macroponent in a later step).
7. Navigate back to the UI Builder page variant editor for Customer Support List.
8. In the content tree, click on Record List Header.
9. In the Component Configuration Panel, update the following:
- Component Label: Custom List Header
- Component ID: custom_list_header
10. Copy the Component ID (custom_list_header) for use in a later step.
11. Click Apply and then Save at the top.
Step 3. Create a UX Action Configuration
An Action Config is a stored definition of an action. It’s how you tell ServiceNow what the action is, what it should be called, and where it should be used.
1. In the All Navigator, type Action Configs, Click it under Declarative Actions > Action Configs.
2. Click the New button.
3. On the new record, set the following:
- Name: Custom List Action
4. Right-click and save.
5. Copy the sys_id of the newly created record and save it in your notepad — (this will be passed to the page as a property).
Step 4. Create a Page Property under Customer Workspace Support UX Application
Page properties allow data like the action config sys_id to be passed into the page and accessed dynamically in UI Builder.
1. On the All Navigator, type Experience and select it under Now Experience Framework > Experiences.
2. In the title bar, search for Customer Support Workspace and select it.
3. In the Related Lists, click New under UX Page Properties.
Creating the UX Page Property
1. On the new UX Page Property record, set:
- Name - actionConfigId
- Suffix - actionConfigId
- Type - String
- Value - fd30dc2b81a650e82bf6046e91bfe2 (paste the sysId of the Custom List Action)
2. Right-click and save or Submit.
Step 5. Creating an Action Assignment
This step connects the UX Action to a specific list/table/component in UI Builder. Without this, the action won’t show up or behave as expected.
1. Search for List Actions in the All Navigator, Select it under Declarative Actions > List Actions.
2. Click the New button to create a new list action assignment (this becomes the button).
3. Set the following fields:
- Action Label - Check SLA
- Action Name - (Auto-populates)
- Implemented As - UXF Client Action
Create a new Client Action
1. Click the magnifying glass on Specify Client Action field, then click New button.
2. On the new record, set the following fields:
- Key - check_sla_payload
- Label - Check SLA Payload
- Applicable To - List
- Payload:
{
"recordSysId": "{{sysIds}}"
}
recordSysId is the key name that will be referenced in event mappings.
{{sysIds}} is a variable automatically filled with the selected record(s) in the list view
3. Click Submit.
4. You’ll be redirected back to the Action Assignment record with the Specify Client Action field populated.
5. Set remaining fields:
- Table: Incident
- Icon: accessibility-fill
- Record Selection Required: True
- Order: 100
6. Right-click and save.
Setting the Action Configuration
1. Scroll to the Action Configuration related list.
2. Click the Edit button.
3. Search for and select Custom List Action.
4. Click Save.
Step 6. Add a UX Add-On Event Mapping
This is what connects the action to an event in UI Builder.
1. In the Related Lists, go to UX Add-On Event Mappings and click the New button.
2. Set the following fields:
- Event Mapping Name - Check SLAs
- Source Element ID - custom_list_header
- Parent Macroponent - Custom List
- Source Declarative Action - auto-populated
Create Target Event
1. Click the magnifying glass next to Target Event field, then click New button.
2. Set the following fields:
- Label - Customer Workspace - Open record in tabs
- Event Name - custom_wrks_open_record_tabs
- Properties -
[
{
"fieldType": "string",
"label": "Record Sys Id",
"name": "recordSysId"
}
]
3. Click submit which should revert you back to the UX Add-On Event Mapping record with the Target Event field populated.
4. On the Target Payload Mapping field, add the following JSON:
{
"container": {
"recordSysId": {
"binding": {
"address": ["recordSysId"]
},
"type": "EVENT_PAYLOAD_BINDING"
}
},
"type": "MAP_CONTAINER"
}
This mapping binds the recordSysId that comes from the list action’s payload and makes it available to the event handler.
5. Click save.
Step 7. Create Event and Configure Event Handler in UI Builder
Event handlers listen for and respond to the event (RECORD_OPEN_TAB). Without this, the button does nothing.
1. Go to UI Builder > Customer Support Workspace.
2. Navigate to the Customer Support List Page, then click the Default page variant.
3. In the content tree, click on BODY.
4. Navigate the Component Configuration Panel, go to the Events tab.
5. Click + Add under Handled Events.
6. In the modal that pops up, set the following fields:
- Event Label: Record Open Tab
- Event Name: (Auto-populated)
7. Add two payload fields:
- Name - record_id
- Label - Record ID
- Name - tab_id
- Label - Tab
8. Click Apply.
Step 8. Creating a Client Script
The client script takes the recordSysId from the list button and tells the UI Builder page to open the Task SLA tab.
1. In the bottom-left corner of the variant editor, click the + next to Client Scripts.
2. Set the script name: Open SLA in new tab
3. Paste the script:
let sys_id = event.payload.recordSysId;
let payload = {};
payload.record_id = sys_id;
payload.tab_id = "id=relatedLists^index=0";
api.emit("RECORD_OPEN_TAB", payload);
Gets the selected Incident sys_id and Opens the record with the Task SLA tab (first related tab)
4. Click Apply.
Add Event Mapping (Client Script)
1. Click Add Event Mapping button.
2. Select: Customer Workspace - Open record in tabs.
3. Click Continue.
4. Scroll down and select the script: Open SLA in new tab
5. Click Continue, then Add.
Add Event Mapping (Record Open Tab)
1. Click the Add Event Mapping button.
2. Select: Record Open tab
3. Click continue.
4. Select: Link to destination event handler
5. Under Select Destination, select Pages in Current Experience.
6. Click on the Record Page.
7. On the right, hover over the table property and type: incident
8. Hover over the sys_id property and click on bind data icon, under Data types select Event Payload > record_id.
9. Hover over the selectedTab property and click on bind data icon, under Data types select Event Payload > tab_id
10. Check Open in new tab and Click Add.
Don’t forget to click Save in the top right!
Step 9. Testing and Previewing
1. Click the Preview drop-down and select Open URL Path,
- Or go to ServiceNow homepage, Workspace Navigator > Customer Workspace
2. Click on the List outline.
3. Select any Incident record.
4. The Check SLA button should appear.
Click it — it should open a new tab 'Task SLA Related List' with a tab that contains task SLAs relating to the selected incident record.
📌
Troubleshooting
In case Customer Workspace - Open record in tabs event doesn’t show up in UI Builder:
- Click on settings in the middle of the page variant editor.
- Click on the Open Records dropdown menu and select Page Definition.
- Scroll down to the Handled Events field and click the lock key icon.
- Search for: Customer Workspace - Open record in tabs, select it, then click the lock key.
- Click the Update button or Right Click and Save.
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, then go to Developer > Clear UI Builder Cache. You can also try clearing your browser cache.
Conclusion
🎉 Congratulations! You have successfully created a reusable and dynamic UX Action that lets users quickly access related Task SLAs directly from the Incident List!
If you found this guide helpful, consider sharing it with peers or teams looking to elevate their UI Builder skills. If you like this type of content, please mark the article "Helpful" leave us your topic ideas in the comments, and fill in the survey at the top!
Keep an eye out for future tutorials where we’ll dive deeper into crafting immersive, data-driven experiences. Until then—happy designing, and stay curious!
Check out the Next Experience Center of Excellence for more resources.
