Overview
In this tutorial, you will create a Field Action Decorator in UI Builder, you will add an interactive icon next to the Caller field within the Customer Service Workspace. When clicked, this icon will open a modal displaying the caller's related records, enhancing agents' ability to access relevant information more quickly.
We will cover:
- Configuring an existing page
- Creating a custom modal
- Setting up a page handled event
- Creating a declarative action
- Adding a UX Add-On Event Mapping
Family Release: Yokohama
UI Builder Release: 27.1.x
Roles Required: admin
Authored by: @sophiasemga
Thinking Beyond Modals
Configurable Workspaces offer many different opportunities to transform your fulfiller's experiences, so instead of adopting a "Lift and Shift" mentality when migrating to workspaces, I invite you to take a moment to pause. Consider if that requirement you're trying to fulfill with a modal would be better suited to a different location in the workspace, like the sidebar or a page collection. Modals currently see widespread use to address many use cases and requirements for Core UI form views. While looking in to what Modals and Modeless dialogs can do for you in Workspaces, keep in mind that they were likely a popular tool in the past because of how limiting the configuration of Core UI forms was.
What are Declarative Actions?
Declarative Actions are like UI Actions but built specifically for Next Experience-based UIs (Workspaces and Experiences).
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 Experiences.
For example, if you add a "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 Declarative Actions
- 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. Configuring an existing Page
1. In the Experience Editor, find Pages and Variants.
2. Locate the record page in the list of pages.
3. Under the existing default page variant, click the three dots (⋮) on the right.
4. Select Duplicate Variant.
5. Rename the new variant to Field Action Decorator and click Create.
Step 3. Creating a Custom Modal
1. In the Content Tree of the new page variant editor, go to Overlays > Modals and click + to add a new modal.
2. Select Custom to create a new modal.
3. A modal dialog will appear, graying out the rest of the screen.
4. In the Component Configuration Panel, click the component name above the preset and edit it.
- Component Label: User Related Record
- Component ID:
user_related_record
5. Click Apply.
6. Navigate back to the Content Tree and select + Add Content under User Related Record > Header 1.
7. In the modal that appears, search for Stylized Text Component and select it.
8. In the Component Configuration Panel, click the component name above the preset and edit it.
- Component Label: Related Record Header
- Component ID:
related_record_header
13. Click Apply.
14. In the Preset Menu, select the preconfigured preset Record Subheading.
15. Click Remove Current Preset in the modal that appears.
16. Under the Configure tab, update Text Property to “User’s Related Record”.
17. Click Save on the top-right corner.
Adding a List Component
1. In the Content Tree, click + Add Content under User Related Record > Body 1.
2. In the modal that appears, search for List Component and select List Simple.
3. In the Component Configuration Panel, click the component name above the preset and edit it.
Component Label: Related Record List
Component ID:
related_record_list
6. Under the Configure tab, navigate to Data > Table and click the Edit Fixed Filter butto n.
7. In the first condition, search for
'Incident'and dot walk to Incident → Caller. 
8. On the third box click on the Bind Data icon, In the modal that pops up, under Data resource> Data types, click on Form controller > Form > Fields > caller_id > value. It should look like this on the display:
@data.record.form.fields.caller_id.value 
9. Click the 'OR' button to add another condition.
10. In the second condition search for
Requested Item and dot walk to Requested Item → Requested For. 11. On the third box click on the Bind Data icon, In the modal that pops up, under Data resource> Data types, click on Form controller > Form > Fields > caller_id > value. It should look like this on the display:
@data.record.form.fields.caller_id.value 
20. Click Apply.
Adding a Button Component
1. In the Content Tree, click + Add Content under User Related Record > Footer.
2. Search for Button Component and select it.
3. In the Component Configuration Panel, click the component name above the preset and edit it.
- Component Label: Related Button
- Component ID: `related_button`
6. Click Apply.
7. Under the Configure tab, set Variant Property to Primary.
8. Navigate to the Events tab and add a handler for Button Clicked event.
9. Search for Open or Close Modal Dialog and select it.
10. In the Modal Dropdown, select User Related Record.
11. Uncheck the Open Modal Dialog checkbox.
12. Click Add.
Step 4. Creating a Handled Event in Body Container
1. In the Content Tree, select the Body Container.
2. Navigate to the Component Configuration Panel and select the Events tab.
3. Click + Add icon below Handled Event.
4. Set Event Label to: User Related Record Event
5. Event Name auto-populates.
6. Click Add.
7. On the Event tab, click the Add Event Mapping Under Page Event Mappings.
8. Select the newly created event, User Related Record Event and click Continue.
9. Search for Open or Close Modal Dialog, select it, and click Continue.
10. In the Modal Dropdown, select User Related Record.
11. Leave Open Modal Dialog checked.
12. Click Add.
13. Save your changes.
Step 5. Creating a Declarative Action
1. In Platform View, search for Field Decorators under Declarative Actions>Field Decorators in the All Navigator.
2. Click the New button to create a new Field Decorator.
3. Set Action Label to: User Related Records.
4. Action Name auto-populates.
5. On Implemented As dropdown field, select: UXF Client Action.
6. Click the Magnifying Glass on Specify Client Action field and select New to create a new payload definition which creates the UI action.
7. In the new record, update Key field: Field Decorator.
8. Update Label field: Open User Related Records.
9. Applicable To field: UXF, Field.
10. Payload field:
{
"referenceField": "{{fieldName}}",
"referenceKey": "{{referenceKey}}",
"referenceTable": "{{referenceTable}}",
"fieldLabel": "{{label}}",
"parentTable": "{{tableName}}",
"parentSysId": "{{recordSysId}}",
"encodedRecord": "{{encodedRecord}}",
"serializedChanges": "{{serializedChanges}}",
"fieldType": "{{fieldType}}",
"value": "{{value}}",
"displayValue": "{{displayValue}}",
"dependentField" : "{{dependentField}}",
"dependentValue": "{{dependentValue}}"
}
11. Click Submit.
12. You should be redirected back to the Action Assignment record and Specify Client Action field should now be populated.
13. Navigate to Table dropdown field, select
Incident.
14. On Decorator Applies To dropdown field, select Specific Field as we want this action to be on a specific field. A field can have a max of 3 field decorators.
15. On the Field name field, it will pop up all the fields on the incident table. scroll down and select 'Caller'.
16 On the Icon field, search for and select chat-triangle-exclamation-fill.
17. Click Save.
18. Click Advanced View related link and navigate to the Conditions tab.
19. Set Record Conditions to 'Caller is not empty'.
20. Click Save.
Step 6. Adding a UX Add-On Event Mapping
1. Under Related Lists, click on the UX Add-On Event Mappings tab and click the New button. This is what maps the action to the actual handled event you created in UI Builder.
2. Set Event Mapping Name to: Related User Records.
3. On the Parent Macroponent field, search for and select: Field Action Decorator.
4. On the Target Event field, select: User Related Record Event.
5. On the Source Element ID field, which is the element ID of the component that will be emitting the actual event, enter: form.
6. On the Target Payload Mapping field add this payload mapping:
{
"container": {
"fields": {
"container": {
"encodedRecord": {
"binding": {
"address": [
"encodedRecord"
]
},
"type": "EVENT_PAYLOAD_BINDING"
},
"label": {
"binding": {
"address": [
"fieldLabel"
]
},
"type": "EVENT_PAYLOAD_BINDING"
},
"referenceField": {
"binding": {
"address": [
"referenceField"
]
},
"type": "EVENT_PAYLOAD_BINDING"
},
"referenceKey": {
"binding": {
"address": [
"referenceKey"
]
},
"type": "EVENT_PAYLOAD_BINDING"
},
"serializedChanges": {
"binding": {
"address": [
"serializedChanges"
]
},
"type": "EVENT_PAYLOAD_BINDING"
},
"size": {
"type": "JSON_LITERAL",
"value": "md"
},
"sysId": {
"binding": {
"address": [
"parentSysId"
]
},
"type": "EVENT_PAYLOAD_BINDING"
},
"table": {
"binding": {
"address": [
"parentTable"
]
},
"type": "EVENT_PAYLOAD_BINDING"
}
},
"type": "MAP_CONTAINER"
},
"params": {
"type": "JSON_LITERAL",
"value": {}
},
"route": {
"type": "JSON_LITERAL",
"value": "modal_ref_lookup"
},
"size": {
"type": "JSON_LITERAL",
"value": "lg"
}
},
"type": "MAP_CONTAINER"
}
7. Click Submit.
Step 7. Testing and Previewing
1. Open UI Builder by searching for it in the ALL navigator
2. In UI Builder, select Customer Support Workspace and scroll down to locate your page variant, Field Action Decorator.
3. In the page variant editor, open the Preview dropdown menu and select Open URL Path.
4. Locate the Caller field and click on the newly added icon next to it.
Expected Behavior:
• Clicking the icon should open the custom modal, displaying the caller's related records
• Clicking the button inside the modal should close it.
📌
Troubleshooting
• Check the Event Label - Ensure your page level event does not include any commas, or apostrophes in the Event Label.
• Validate JSON Formatting - Verify that the Action Payload Definition JSON is correctly formatted. You can use online tools to format and check for errors.
• Confirm Target Payload Mapping - Ensure that your Target Payload Mapping is correctly structured and does not contain any syntax errors.
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 have successfully created a Field Action Decorator in UI Builder! Big shout out to @dylan_lindgren 's awesome Declarative Actions article. You should check it out if you're looking for a super deep dive in to how Declarative Actions work.
If you found this guide helpful, consider sharing it with peers or teams looking to elevate their UI Builder skills with dynamic actions.
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
2 Comments
