UI Builder Tips #1: The Tables Behind UI Builder

UI Builder Tips Series

Welcome to the UI Builder Tips series! I'll use this series to document what I've learned while working with ServiceNow's UI Builder. Since this is a learning process, these blog posts should be seen as a set of notes.

The content of these posts will likely change often to include new information as I continue to learn. Feel free to leave feedback or corrections in the comments, and I'll update the posts as needed. Let's learn together!

Exploring the Tables Behind UI Builder

ServiceNow's UI Builder is a powerful tool that lets users create customized workspace pages and experiences using a simple, low-code, drag-and-drop interface. This interface hides the complexity of modern web development but still offers a lot of control and customization.

Most of the time, you can use UI Builder without worrying about the tables working behind the scenes. However, there may be times when you need to dive into the backend to fix something. If you find yourself in such a situation, you might notice there's not much documentation to help you. Here is a list of the tables I have encountered, each with a short description of what the table does and a screenshot of the backend form.

UX Component Definition (sys_ux_lib_component)

This table contains definitions for all components that are available to be added to a UI Builder page, including custom components. It is referenced in a lot of other UX tables hence the many related lists.

UX Application (sys_ux_page_registry)

Each one of the records in this table represent a different experience/workspace in UI Builder.

UX App Configuration (sys_ux_app_config)

This table holds configurations for different workspaces/experiences. This record is used to:

• Specify a landing path for the workspace

• gather all of the routes inside of the workspace

• gather all of the screens in the workspace

UX App Route (sys_ux_app_route)

This record shows a route within a given workspace. It holds important information like the fields (required params) and the optional params that are available for the route.

UX Screen Collection (sys_ux_screen_type)

A screen collection record corresponds to a group of page variants in UI Builder. When you see multiple variants under the same parent, the screen collection record is that parent. It also ties a route to the list of variants.

UX Screen (sys_ux_screen)

UX Screens are the same thing as variants. A variant record ties together:

• The screen collection (which has the route)

• Conditions for when to display this variant

• The actual macroponent definition of the variant's contents

• And some other things

UX Macroponent Definition (sys_ux_macroponent)

The macroponent definition is probably the most important record in all of UI Builder. When you are editing a page in UI Builder, you are editing the macroponent record. Its a higher-order component (macroponent) that arranges a bunch of lower-order components (microponents). The macroponent record defines:

• The layout of your page

• The composition of your page

• The data your page pulls in

• Any custom events that your page handles internally

• The properties (aka URL params, both required and optional) that your page accepts

• The initial client state of your page

• And many other things

Many of the fields on the macroponent record contain JSON so be very careful when editing their contents.

If you are having problems with a page and you need to start investigating on the backend, always start here.

UX Page Properties (sys_ux_page_property)

UX Page Properties are like System Properties for individual workspaces/experiences in UI Builder. Here are some common ones that you will see on most experiences:

• chrome_main

• chrome_header

• chrome_footer

• chrome_toolbar

• chrome_tab

You can also add custom UX Page Properties to hold values for your workspace.

UX Event (sys_ux_event)

Any kind of event that you see in UI Builder lives in this table. When you want to fire off and handle a custom event, the first step is to create a record in this table.

UX Add-on Event Mapping (sys_ux_addon_event_mapping)

This table allows you to tie an event firing to a declarative action on a given macroponent.

UX Client Script (sys_ux_client_script)

UX Client Scripts are scripts that are reusable on a given page. When you add a new client script at the bottom left corner of UI Builder it creates one of these records. These scripts can reference client script includes when a client script include is added as a dependency.

The UX Client Scripts table also contains the scripts that are created when you data bind a script to a specific field on a UI Builder field.

Client Script Includes (sys_ux_client_script_include)

Client Script Includes can be referenced in Client Scripts in UI Builder. This should feel familiar to those who use Script Includes on the backend. These scripts can be reused across multiple pages.

Data Brokers (sys_ux_data_broker)

The Data Broker table is the parent table to all data brokers. Here are it's children:

When creating a custom data broker, you will choose from one of these types. Each type has unique configuration options and forms, but the main idea is the same: get data into UI Builder.

Other Tables

If the table you are looking for is not listed above, please post a comment on this blog post and check back later as this list will be continually updated. There are 117 tables related to UI Builder (as of Washington DC) so creating a comprehensive list will take a while. I will keep updating this list as I learn more about each table.

A Complete List of UI Builder Tables