Workspace Essentials: Create a Custom Configurable Workspace from Scratch

MGOPW · ‎01-28-2025

Workspace Essentials Part 1

Article Directory

Overview

In this article, we will walk through the process of creating a workspace from scratch in UI Builder. By the end of this tutorial, you will have a fully functional Customer Support Workspace that includes a landing page, side navigation and tabs to display and manage data.

Family Release: Xanadu

UI Builder Release: 26.2.74

Roles Required: Admin

Authored by: @sophiasemga

📌

Quick Tip

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.

Step 1: Creating a Scoped Application

As of Xanadu, the way to create a scoped application in ServiceNow is through ServiceNow Studio. This new product provides a more structured development environment and a streamlined way to build applications. We will first go over how to install and use ServiceNow Studio, but if you are on a version prior to Xanadu we are also including instructions for how to create a scoped application using Legacy Studio.

Using ServiceNow Studio

Installing the ServiceNow Studio plugin:

1. Navigate to the All Menu and search for "Plugins"

System Definition > Plugins

2. In the search bar, type ServiceNow Studio and install it if it is not already available. You may have to sync to the store to grab updates.

Note: You only have to install from the store if you are on Xanadu. The ServiceNow Studio plugin will be automatically installed with the Yokohama release.

Creating a Scoped App Using ServiceNow Studio:

1. Open ServiceNow Studio by searching for "ServiceNow Studio" in the All Menu:

App Engine > ServiceNow Studio

2. On the top-right corner, click on the Create dropdown menu and select App.

3. On the new page:

• App Name: Customer Support

• Scope: Leave as default

Click Continue.

4. In the Add Roles step, leave the default fields as they are and click Continue (since we are not adding or modifying roles at this stage).

5. Wait a few seconds, and your new app will be created!

6. Click Go to App Dashboard to explore the following application settings:

• Application Files: Default files created for the app.

• Roles & Dependencies: Default roles and system dependencies.

• Cross-Scoped Privileges & Design Access: Security settings for integrations.

• Restricted Caller Access Privileges: Controls for external API access.

7. To verify that your app has been successfully created:

• Refresh the Filter List on the top-right corner to see your app populate.

• Navigate back to your ServiceNow home page and check the Application Picker—it should now show Customer Support as the application scope.

• A default update set is automatically created for your new scoped app.

Using Legacy Studio

1. Log into your ServiceNow instance.

2. In the All Menu, search for "Studio" and select it.

3. In the dialog, click Create Application and select Let’s Get Started.

4. Fill in the following details:

• Name: Customer Support.

• Advanced Settings: Leave as default (Scoped)

• Scope: Automatically populated; leave as is.

5. Click Create.

6. Configure application settings.

• Skip creating new roles or adding existing roles; click Continue.

• Select Mobile and Classic formats; click Continue.

• For tables, click Done with Tables (no new or existing tables needed).

• Exit the dialog by clicking the X.

7. Go back to the ServiceNow home page and ensure the Application Scope (1) is set to Customer Support, and that you are in the"Default" Update set.

Step 2: Building a Workspace in UI Builder

1. Navigate to Now Experience Framework > UI Builder in the filter navigator to open the UI Builder interface.

2. In the top right corner of UI Builder, click Create > Experience.

3. In the "Create an experience" modal, fill in the details:

• Name: Customer Support Workspace

• App Shell: Workspace App Shell

• Landing Path: Leave as default (home).

4. Leave the default role and click Create and then Open Experience.

You are now in the experience editor, let's create a new page!

Step 3: Create Pages for the Workspace

Since this is a completely blank experience, take a moment to review the menu under your Experience heading. Here we can see the URL path, Application Scope (Customer Support), App Shell, and assigned Roles.

To begin setting up your workspace, you will create three pages: a Record page, a List page, and a Landing Page.

Create a Record Page

1. In the Experience Editor, click Create New Page or the + icon next to Pages and Variants.

2. Select the Standard Record Template and click Use Template.

3. Provide the page details:

• Name: Record.

• URL Path: Automatically populated.

4. Click Continue and review the parameters:

• Required Parameters: table, sysId.

• Optional Parameters: query, extraParams, views, selectedTab.

5. Click Looks Good and define the page variant:

• Leave the name as Default.

• Skip Audience and Conditions.

6. Click Create.

You are now in the Page Variant Editor.

7. Familiarize yourself with the Page Variant Editor, which includes:

• Content Tree (left), Configuration Tabs (right), Stage (center) and Data and Script Section (bottom - left).

📌

Quick Tip

Save your work frequently using the Save button in the top right corner.

Create a List Page

1. In the Page Variant Editor, click the page drop-down menu on the top left and select the experience link to return to the Experience Editor.

2. Click the + icon next to Pages and Variants and select Create a new page.

3. Scroll down and select the List Page Template, then click Use Template.

4. Provide the page details:

• Name: Customer Support List

• URL Path: (Automatically populated)

5. Click Continue and review the optional listId parameter.

6. Click Looks Good and define the Page Variant:

• Leave the name as Default.

• Skip Audience and Conditions.

7. Click Create.

You are now in the Page Variant Editor.

Create the Landing Page

1. In the Page Variant Editor, click the page drop-down menu on the top left and select the experience link to return to the Experience Editor.

2. Click the + icon next to Pages and Variants, select Create a New Page and choose Create from Scratch Instead.

3. Enter the page details. We are calling this page 'Home' because workspaces will default to a page named 'Home' when opened.

• Name: Home

• URL Path: (Automatically populated)

4. Click Continue and then Looks Good to skip adding parameters.

5. Define the page variant, leave the name as Default.

6. Skip Audience and Conditions.

7. Ensure Build responsive is selected, then click Create.

Configure the Landing Page

1. In the Content Tree, select Add Content under Body > Add Content.

2. Select the Single Column Layout.

3. Select Column 1 in the Content Tree. Using the Component Configuration panel on the right side of the Page Variant Editor, set the alignment as follows:

• For Align Items, select the Center Icon.

• For Justify Content, select the Center Icon.

4. Click Add Content below Column 1 in the Content Tree. Alternatively, you can use the Stage by clicking on the + icon in the middle of the page preview.

5. Search for Stylized Text component and click to add it.

5. When the modal dialog pops up to select a preset, click Cancel.

6. On the right side, within the Component Configuration panel, select the Configure Tab. Set the Text property to 'Landing Page'.

7. Preview the Workspace by clicking on the Preview Dropdown in the top-right corner of the page variant editor.

8. Select Open URL Path. Once it opens, you should see your edited stylized text component!

📌

Quick Tip

When configuring components, make sure to change the Name and ID of the component in the top left of the Component Configuration panel so future collaborators on your app can know what things are at a glance.

Now that we have added pages, it's time for us to start configuring the rest of our workspace's features. Let’s start by adding a side navigation menu.

1. Go back to the Experience Editor view of the workspace and click on View Experience Settings.

2. Scroll down in the Experience Settings until you see the Side Navigation section and select + Add.

3. Configure the first side navigation entry:

Under URL Path, select the ‘Home’ page from the dropdown menu.
Click the dropdown under Icon, search for ‘home outline’, and select it.
In the Label box, type ‘Home’.
The Group drop down will determine whether the icon is aligned to the top or the bottom of the menu. Leave the Group dropdown menu as its default value.

4. Configure the second side navigation entry:

Click the + Add button to add another side navigation item.
Under URL Path, select the ‘Customer Support List’ page from the dropdown menu.
Next to URL Path, click the dropdown under Icon, search for ‘List outline’, and select it.
In the Label box, type ‘List’.
Leave the Group dropdown menu as its default value.

Once finished, click Save at the bottom-left corner of the Experience Settings.

5. Still in the Experience Settings, click the Experience Dropdown Menu in the top-left corner. Select the Default variant under the Home page, this will take you to the Variant Editor Settings.

6. We are going to navigate to the variant in UI Builder and preview our changes. Click the Editor Tab (next to Settings) to open the Page Variant Editor view.

7. In the Editor view, go to the top-right corner, click the Preview Dropdown Menu, and select Open URL Path.

You should now see a side navigation menu (often times referred to as the "L1 Menu") on the left, with two icons: The landing page and the list page we just added. We haven’t defined any lists for the experience yet, we will go through that process later in the tutorial.

Step 5. Configuring the Workspace Experience record

We are still missing tabs and a plus menu on our workspace, so let's add them to finish the basic workspace functionality. First we will navigate to the workspace's experience record, which holds all the configuration information for the workspace. A workspace is considered a type of Experience, and you use UI Builder to configure experiences, but there are still some configurations that have to be made outside of UI builder as you will shortly see.

1. Go back to the ServiceNow home page, where you can see the All menu in the Unified Navigator on the top left.

2. In the All Menu search bar, type ‘experiences’ and select Experiences under Now Experience Framework > Experiences.

3. Click on the search icon next to the column titles. In the search bar under the Title column, type the name of your workspace: ‘Customer Support Workspace’, hit enter, and click on it's record once it's displayed.

4. You are now in the Customer Support Workspace's Experience record. Here's a quick description of the related lists:

• UX Page Properties: these properties are used to configure how experiences are rendered by ServiceNow.

• UX Application Category M2Ms: these ensure your current experience appears in the Workspaces menu in the Unified Navigator.

1. Select the UX Application Category M2Ms related list, click the New button on the top right corner.

2. Fill in the fields in the new record:

• Experience Category: Workspace

• Order: 100

3. Click Submit.

4. Any time you make changes to what displays in a Unified Navigator menu, you need to refresh your browser tab to see the changes. Refresh the tab, then select the Workspaces menu, and confirm that your workspace appears in the list.

1. Back on the Experience record for our workspace, this time select the ‘UX Page Properties’ related list. Click the New button to create a new record.

2. We will now create the chrome_tab UX page property. Fill in the record as follows:

Name: chrome_tab
Type: JSON
Suffix: chrome_tab
Description: Tab Configuration
Value:

        {
        "contextual": [
            "record"
        ],
        "newTabMenu": [
            {
                "label": {
                    "translatable": true,
                    "message": "New Incident"
                },
                "routeInfo":{
                    "route": "record",
                    "fields": {
                    "table": "incident",
                    "sysId": "-1"
                    },
                    "multiInstField": "sysId"
                }
            }
        ],
        "maxMainTabLimit": 10,
        "maxTotalSubTabLimit": 30
    }

📌

Quick Tip

Here are the descriptions of some of the JSON properties used above:

message: This is the text shown to the end user in the option when you click the plus menu.
routeInfo: This is what tells the button what to do.
- route is the page ID.
- fields contain the URL parameters to be fed to the page when it's opened.

3. Click Submit.

4. Let's confirm our changes. Go to the Workspaces menu in the Unified Navigator, and select the menu item for this workspace.

5. You should now see the tabs section in your workspace! Click on the + (plus) menu icon next to the Home tab. A pop over should appear, showing the "New Incident" action we just added. Clicking on it should open the record page, displaying a new Incident record.

1. Navigate back on the Experience record for our workspace.

2. Select the UX Page Properties related list and click the New button.

3. Fill in the fields for the new record:

• Name: chrome_main

• Type: String

• Suffix: chrome_main

• Value:

        {
         "maxCachedPageCount": 5,
        "maxActivePageCount": 3,
        "timeLeftWarning": 15
        }

4. Click Submit.

With these steps, you’ve successfully added the tabs menu, added an option to the plus menu and created additional page properties to further configure your workspace!

Step 6. Configuring Lists for Workspace

Now, let’s configure our list page, this will allow us to display lists of records, such as incidents, directly in our workspace.

1. In the All menu's search bar, type sys_ux_list_menu_config_list.do and hit enter.

(Fun fact you can impress all your friends with: If you know the name of the table you are looking to access, you can type tablename.list in the All Menu search to open the list view directly! If you want to open just the list view in a different tab, you can change that to .LIST (all caps) and boom!)

2. You are now on the UX List Menu Configuration Table, which provides list menu configurations for each workspace. Click the New button to create a new record.

3. Fill in the record as follows:

• Name: Customer Support Workspace Config

4. Right click the gray header and select Save to save the record.

After saving the record, you will see two related lists:

• UX List Categories: Used to build out the categories for the workspace's lists page.

• UX Lists: Used to configure each individual list for the workspace.

5. Under the UX List Categories related list, click the New button.

6. Fill in the fields for the new record:

• Title: Incident

• Order: 100

📌

Quick Tip

The Order field helps you set the order that your lists and categories render on the list page, lower numbers will be at the top, with larger numbers being listed below them. It's always a good idea when first building out lists or menus using the Order field with large increments between them, to allow yourself room for growth in the future without having to re-number the entire list each time.

7. Click Submit.

8. Now let's add a List to the Category we just created. Back on the main UX List Menu Configuration record, go to the UX Lists related list and click the New button.

9. Fill in the fields for the new record:

• Title: All

• Table: Incident

• Configuration: Customer Support Workspace Config

• View: Default View

• Order: 1000

10. Click Submit.

11. When the UX List Menu Configuration record loads, right-click the header and select Copy sys_id.

We will now create a UX Page Property to tell our workspace about our new UX List Configuration record. Let's navigate back to our workspace's Experience configuration record.

1. Open the All menu in the Unified Navigator, and navigate to Now Experience Framework > Experiences.

2. Search for Customer Support Workspace under the Title column and click on it.

3. Under the UX Page Properties related list, click the New button.

4. Fill in the fields for the new record:

Name: listConfigId
Type: String
Value: Paste the sys_id of the list configuration record we just grabbed on step 11 of the previous section.

5. Click Submit.

Verifying List Configuration

Now that we’ve configured the list functionality, let’s navigate back to our workspace to see the results!

1. Select the workspace directly from the Workspaces menu in the Unified Navigator.

2. On the landing page, navigate to the L1 Menu (the left side navigation we configured earlier in the article) and click on the icon we selected for the List page.

3. Click on the All menu item under the Incident category, and you will see a list of all Incident records displayed.

4. Click on any record in the list, and the selected record will open in a new tab within the workspace, displaying the Record page we created earlier in this article.

Conclusion

Congratulations! 🎉 You’ve successfully created a workspace from scratch, configured it to display the side navigation menu (L1 menu), configured the Plus menu and the Tabs at the top, and finally configured the List page to display a list of Incidents. Don't forget to share this article with your colleagues and friends who might benefit from mastering UI Builder.

Stay tuned for more tutorials and tips to help you create dynamic and engaging user interfaces!

Check out the Next Experience Center of Excellence for more resources

Workspace Essentials: Create a Custom Configurable Workspace from Scratch

Workspace Essentials Part 1

Table of Contents

Article Directory

Overview

Quick Tip

Step 1: Creating a Scoped Application

Using ServiceNow Studio

Using Legacy Studio

Step 2: Building a Workspace in UI Builder

Step 3: Create Pages for the Workspace

Create a Record Page

Quick Tip

Create a List Page

Create the Landing Page

Configure the Landing Page

Quick Tip

Step 4: Adding Side Navigation (L1 Menu)

Step 5. Configuring the Workspace Experience record

Add the Workspace to the Workspaces menu

Configuring the Plus menu

Quick Tip

Adding final page property

Step 6. Configuring Lists for Workspace

Quick Tip

Verifying List Configuration

Conclusion

How to pass variable values into the Catalog Item component

UI Builder Essentials: Client Scripts in UI Builder