UI Builder Essentials: Troubleshooting Guide

[MGOPW]

UI Builder Essentials Part 9

Table of Contents

• Equip yourself with the best tools
• Finding where an issue is occurring
• Fixing styling issues
• Fixing Cross-Component or Component to Data Resource interactions (Events)
• Use NED tools to observe what events are fired
• Check the event configuration in UI Builder
• Check the event mappings and configuration of data resources/controllers
• Check for event mappings that are invalid or missing
• Fixing a Component Not Interacting Within Itself Correctly
• Fixing a Data Resource or Controller not working
• Data resource preview only shows an error message
• Data resource preview shows an "unconfigured" message
• Data resource is not fetching expected values
• Data resource has no input properties or isn't creating/updating/deleting correctly

Article Directory

Part 1 - Six Fundamental Features You Need to Know Part 2 - Navigating UI Builder Part 3 - Dynamically bind List with Data Visualization Part 4 - Implementing Popovers Part 5 - Updating Component's Data with a Button Part 6 - Simple Counter Application Part 7 - Interactive List and Form Configuration Part 8 - Modals and Modeless Dialogs Part 9 - Troubleshooting

Overview

When working on experiences in the Next framework, it can be challenging to identify the root cause of an issue. The framework is extremely powerful, but with that power comes complexity and nuance when trying to troubleshoot issues. This article aims to provide the tips and tricks that will help you more quickly identify where the issues might be.

Family Release: Xanadu

UI Builder Release: 26.2.59

Roles Required: admin

Authored by: @John McCormick1 

📌

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.

Equip yourself with the best tools

Probably the best tool that you can put into your browser to help with troubleshooting in the Next Experience Framework is the Next Experience Developer (NED) tools Chrome Extension. These tools can help you investigate through your experience and pages and track performance, events, and more. The NED (Next Experience Developer) Tools team has a series of explanations of what the NED tools can do on the Developer site to work with their tools. We'd recommend starting with the Inspector Tab, then the Components Tab, the Events Tab, and then Deep Linking information.

If you already have it installed, make sure you have the latest version to take advantage of some of our tips below. As of writing, you'll need version 3.5 and above.

Finding where an issue is occurring

Let's say you're working on a page in your experience, and something is not working the way you wanted. But how on earth do you figure out what is wrong? Identifying where the issue is will help us narrow down what the problem might be and how we can fix it.

Let's start by asking a few questions:

1. Is the problem related to styling? In other words, is it a problem with width, background-color, padding, etc.?
2. Is the problem related to a component not interacting with another component or a data resource correctly?
3. Is the problem related to a component not interacting inside of itself correctly?
4. Is the problem within a data resource or a controller not working like you expect? Is it not fetching or not updating something?

Now that we know a general area where the issue could be, check one of the guides below to see how to potentially fix it.

Fixing styling issues

Styling issues can be confusing even outside of the Next Experience Framework! W e recommend taking the following steps to try and identify where the styling issue could be found:

1. Open your page as your end user would see it, impersonating the user should not be required but it might be a good thing to try. 
2. Inspect the part of the page that is not working as expected using your browser's developer tools. (Here is a small guide on using your browser tools found in our Knowledge 2024 Theming lab.)
3. Check the styles on the component in question and any Containers above it.
4. You can make changes to the styles directly through your developer tools to check and see what might be causing or might fix the problem.
   • Note: you cannot change styles on the DIV inside of the now-uxf-page-simple-container component due to a framework limitation.
5. Once you have found a potential culprit or place that additional styles are needed, now you can right click on the component and use the NED tools to open the page in UI Builder.
6. Next, locate the component or it's container in the left-side Content Tree panel and click on it.
7. Now, on the right side Component Configuration panel, select the Styles tab and change around the style that you think could be causing the issue.
   • Note: for containers, there are both Internal and External styles and the fix might be needed in one or both of those places. You can access these using the Edit CSS button at the bottom of the style panel.

As you make changes you should be able to see them reflected on the Stage in the middle of UI Builder or you can save and repeat steps 1-4 to see if it fixed the issue.

Fixing Cross-Component or Component to Data Resource interactions (Events)

We call these kinds of connections Events in the Next Experience Framework. This is the secret sauce that allows components to communicate with one another and for components to work with data resources. Events can be confusing at first, but the longer you work with them, the more familiar they will become! 

It's hard to give an ordered list of troubleshooting steps for events, so the things to try below are listed in no particular order. 

Use NED tools to observe what events are fired

1. While viewing your page as an end user would view it, open the NED Tools via your browser's developer tools and switch to the Events tab.
2. So you don't have to scroll through a bunch of events, clear out the console using the trash icon.
3. Perform the action that is not working as expected.
4. Check to see if the event fired and if it had the appropriate payload fields that you expected.

Check the event configuration in UI Builder

1. Go to the component that the user is acting on (e.g. button, form, etc.)
2. Inside of UI Builder, check the event mappings in the right side Component Configuration panel, within the Events tab, and open the one that coincides with the action the user would be taking.
3. Make sure that properties for that event are filled in as expected.
4. You can wrap the DEBUG formula around a data-bound output inside of Formula builder for the property OR you can switch to script mode and do a console.log() to log whatever you are receiving from the event and what you are putting into the payload. Either of these options will appear in the Console tab of your developer tools if you perform the action that triggers this event as an end user would.
   
   • 
5. Often the event.payload that you are expecting is incorrect or has different properties than what you are using, so be sure to check that!
6. Sometimes deleting the event mapping and re-adding it can fix issues that are harder to see by starting over.

Check the event mappings and configuration of data resources/controllers

1. Open the data resource that a component needs to interact with.
2. Make sure that its input values are setup correctly.
3. Check any event mappings that the data resource has and ensure that it is working as expected using the steps in the event configuration check above.
4. Most often, the outputs of the data resource aren't coming as expected or the result of an action (e.g. Update Record) returns properties that you might not expect.

Check for event mappings that are invalid or missing

If you check the component or data resource that you are investigating, you might see an error.  This could mean:

• The event is missing because a plugin is not installed (e.g. CSM/FSM Workspace has many additional plugins).
• The event is missing because a sys_ux_event record was not captured with changes made to the page and might be in a different instance and can be brought over.
• The event is misconfigured and broken and should be removed.

Typically, if you see this error on an event mapping that was provided OOB, it is likely a missing plugin and can be left alone.  If you see an error and this event mapping has been modified or is not OOB, check another environment to see if the event mapping looks correct there and port over the missing sys_ux_event.

If neither of the above apply, try removing this event and seeing if it fixes the issue you are experiencing, then re-add it and try again. When in doubt... Clear your cache! 

Fixing a Component Not Interacting Within Itself Correctly

Sometimes a component doesn't work or look the way that you expect it to. Because most components are provided by ServiceNow, you may or may not have the ability to fix issues with them. But the steps below will help you to diagnose issues with a component.

Keep in mind that based on how the Next Experience Framework is designed, components are built as web components. This means you are limited in how you can control them outside of the Properties that they expose for you to configure in UI Builder.

1. Open the page in UI Builder where the component is located.
2. Find the component in the left-side Content tree and click on it.
3. Note the ID of the element at the top of the right side Component Configuration panel.
4. Open the page as the end user would see it.
5. Open your browser developer tools and open the Next Experience Tools Inspector tab.
6. Switch to the Components tab inside of the NED tools and search for the element with the ID you noted.
7. Once you've selected that element on the left, you'll see it's properties and state on the right.
8. This information will tell you what your configurations in UI Builder are providing to that component as inputs and how that component is managing it's state internally.
9. If you are not seeing the Property value you expect from your configuration, then go to the component in UI Builder and try changing the value or binding you are passing into the property.
10. If you don't see a property that you can configure for what you are trying to do, then you can reach out through Support to see what options there might be for future enhancements.

Fixing a Data Resource or Controller not working

Data resources and controllers are the brains that interact with your ServiceNow instance to fetch, create, and change records in tables. Like components, data resources and controllers can have Input Properties which specify how the resource will behave. "Fetching" type resources that get data from a table or run a script depend on these Input Properties to determine how the resource will retrieve data or how the script will execute. For mutative resources that create, update, or remove data in tables, they often will not have Input Properties and are instead controlled exclusively through Event mappings.

Since there are a few different ways that data resources can have issues, we'll look at troubleshooting them separately below.

Data resource preview only shows an error message

1. Some data resource types (TRANSFORM and COMPOSITE) require an ACL to be created to allow them to be executed and that is why the error is showing.
2. To correct, open the data resource in the platform view (you can use "Open Record" from the context menu on the data resource in UI Builder) and grab the sys_id of the data resource record.
3. Go to the sys_security_acl table and create a new ACL.
4. Set the type to be data_broker and add a role or condition set of who should be allowed to execute the data resource.
5. Set the Name field to anything and save.
6. Open the list view of the sys_security_acl table,  double-click on the name of the ACL you just created, and paste in the sys_id of the data resource.
7. Return to UI builder, refresh the page, and the data resource should be available.

Data resource preview shows an "unconfigured" message

Some data resources require a minimum set of Input Properties to be populated before they will execute.  Fill in the Input Properties for the data resource and the preview will update when the required properties have been set.

In some older versions of UI Builder, the above problem can trigger this message as well, so try the steps above if setting Input Properties does not fix it.

Data resource is not fetching expected values

1. Check and make sure the input properties are set correctly.
2. If they are bindings, double check the previewed value in the Input Property field (the text that shows) to make sure the binding is bringing in the value you expect. You can also bind the value to a Heading component on the stage to see a bigger preview of the value. (Remember to remove any extra components you may have added to the page during troubleshooting before promoting your work to prod!)
3. If you own the data resource, use the Open Record in the context menu to check the resource on the platform and ensure that it is configured as you expect.

Data resource has no input properties or isn't creating/updating/deleting correctly

For Mutative data resources, there usually are not input properties, and instead the behavior of the resource is set through event mappings. 

1. Find the component or data resource that should call the mutative data resource and create an event mapping to the EXECUTE event of the mutative data resource.
2. In the Payload of the event, you provide a version of Input Properties for the data resource so it knows what to do (You might call that same resource differently from different components or resources!)
3. If that event mapping isn't working, make sure that the Payload fields are set correctly and are getting the values you expect.
4. You can use the DEBUG formula for a binding or the Script option to console.log() out what you are passing in to make sure that it is correct.
5. On the mutative data resource in your page, you can add an event mapping for "Operation Failed" to get more information about why the data resource could not execute successfully.

Conclusion

Congratulations! 🎉  In this article, we've explored essential tips and tricks for troubleshooting and optimizing your UI Builder projects within the Next Experience Framework. You'll learn how to leverage NED tools for performance tracking and understand event configurations to ensure seamless component interactions.

If you found this guide helpful, consider sharing it with peers or teams looking to elevate their UI Builder skills with dynamic pages. If you like this type of content, please mark the article "Helpful", and leave us your topic ideas in the comments.

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