Workspace API - ServiceNow Fluent

The Workspace API defines configurable workspace experiences for organizing and sharing data visually.

Note:

For the latest ServiceNow Fluent API documentation and examples, see the ServiceNow Fluent API reference and ServiceNow SDK examples repository on GitHub.

The Workspace API creates application metadata in the following tables depending on the workspace definition: UX Application [sys_ux_page_registry], UX App Configuration [sys_ux_app_config], UX Application Category M2M [sys_ux_registry_m2m_category], UX Page Property [sys_ux_page_property], UX Screen Collection [sys_ux_screen_type], UX App Route [sys_ux_app_route], UX Screen [sys_ux_screen], and UX Macroponent Definition [sys_ux_macroponent].

Dashboards can be used as the home page of a workspace by referring to one or more workspaces from the visibilities array of the Dashboard object. To create a dashboard, see Dashboard API - ServiceNow Fluent.

For general information about workspaces, see Configurable Workspace UI.

Related concepts

• ServiceNow Fluent

Workspace object

Create a workspace for managing business entities in a single focused working area that enables users to complete an entire job.

Table 1. Properties

Name	Type	Description
$id	String or Number	Required. A unique ID for the metadata object. When you build the application, this ID is hashed into a unique sys_id. For more information, see ServiceNow Fluent language constructs. Format: Now.ID['String' or Number]
title	String	Required. A name for the workspace that appears in navigation and headers.
path	String	Required. The URL path segment of the workspace. Workspace URLs follow the pattern /now/<path>/<landingPath> and use kebab case. Workspaces require access control lists (ACLs) to secure the workspace routes. The field property of an Acl object must match the value of this property with a wildcard pattern: {workspace.path}.*.
tables	Array	Required. A list of table names to manage in the workspace.
listConfig	Reference	Required. The variable identifier of a UxListMenuConfig object that defines the navigation structure of the workspace. For more information, see UxListMenuConfig object.
landingPath	String	The URL path segment of the landing page. Workspace URLs follow the pattern /now/<path>/<landingPath> and use kebab case. Default: home
active	Boolean	Flag that indicates whether the workspace is accessible to users. Default: true

import { Workspace } from '@servicenow/sdk/core';

const itsmWorkspace = Workspace({
    $id: Now.ID['itsm_workspace'],
    title: 'IT Service Management',
    path: 'itsm',
    tables: ['incident', 'problem', 'change_request', 'user', 'sys_user_group'],
    listConfig: incidentListConfig
})

The UX List Menu Configuration referenced is defined using the UxListMenuConfig object.

UxListMenuConfig object

Define a UX list menu configuration [sys_ux_list_menu_config] for the navigation structure and list views of a workspace.

A UX list menu configuration organizes data into categories and lists, enabling users to access different views of business data with filtering, column selection, and role-based visibility. This structure appears in the workspace's navigation panel, providing organized access to different data views.

Table 2. Properties

Name	Type	Description
$id	String or Number	Required. A unique ID for the metadata object. When you build the application, this ID is hashed into a unique sys_id. For more information, see ServiceNow Fluent language constructs. Format: Now.ID['String' or Number]
name	String	Required. A name for the list configuration.
description	String	A description of the list configuration.
active	Boolean	Flag that indicates whether the list configuration is active. Default: true
categories	Array	A list of top-level groupings in the list configuration. For more information, see categories array.

import { UxListMenuConfig } from '@servicenow/sdk/core';

const incidentListConfig = UxListMenuConfig({
    $id: Now.ID['incident_list_config'],
    name: 'Incident List Configuration',
    description: 'Navigation for Incident Workspace',
    categories: [
        {
            $id: Now.ID['incidents_category'],
            title: 'Incidents',
            order: 10,
            lists: [
                {
                    $id: Now.ID['incidents_open'],
                    title: 'Open',
                    order: 10,
                    condition: 'active=true^EQ',
                    table: 'incident',
                    columns: 'number,short_description,priority,state',
                    applicabilities: [
                        {
                            $id: Now.ID['incidents_open_applicability'],
                            applicability: applicability
                        }
                    ]
                }
            ]
        }
    ]
})

categories array

Define categories of related lists [sys_ux_list_category] for a UX list menu configuration.

Table 3. Properties

Name	Type	Description
$id	String or Number	Required. A unique ID for the metadata object. When you build the application, this ID is hashed into a unique sys_id. For more information, see ServiceNow Fluent language constructs. Format: Now.ID['String' or Number]
title	String	Required. A title for the category to display in the navigation menu.
lists	Array	Required. A list of list views in the category. For more information, see lists array.
order	Number	A number indicating the position of the category in the navigation menu. Categories with lower numbers appear first.
active	Boolean	Flag that indicates whether the category is visible in the navigation menu. Default: true
description	String	A description of the category.

categories: [
    {
      $id: Now.ID["incidents_category"],
      title: "Incidents",
      order: 10,
      lists: [
        {
          $id: Now.ID["incidents_open"],
          title: "Open",
          order: 10,
          condition: "active=true^EQ",
          table: "incident",
          columns: "number,short_description,priority,state",
          applicabilities: [
            {
              $id: Now.ID["incidents_open_applicability"],
              applicability: applicability
            }
          ]
        },
        {
          $id: Now.ID["incidents_all"],
          title: "All",
          order: 20,
          condition: "",
          table: "incident",
          columns: "number,short_description,priority,state",
          applicabilities: [
            {
              $id: Now.ID["incidents_all_applicability"],
              applicability: applicability
            }
          ]
        }
]

lists array

Define list views of table data [sys_ux_list] with filtering and column configurations for a UX list menu configuration.

Table 4. Properties

Name	Type	Description
$id	String or Number	Required. A unique ID for the metadata object. When you build the application, this ID is hashed into a unique sys_id. For more information, see ServiceNow Fluent language constructs. Format: Now.ID['String' or Number]
title	String	Required. A title for the list to display in the navigation menu.
table	String	Required. The name of a table to use for the list.
columns	String	A comma-separated list of column names to display in the list.
condition	String	An encoded query string to filter the records displayed in the list.
order	Number	A number indicating the position of the list within its category. Lists with lower numbers appear first.
active	Boolean	Flag that indicates whether the list is visible to users. Default: true
applicabilities	Array	A list of variable identifiers of Applicability objects that control which roles can view the list. For more information, see Applicability object.

lists: [
        {
          $id: Now.ID["assets_active"],
          title: "Active",
          order: 10,
          condition: "install_status=1",
          table: "alm_asset",
          columns: "asset_tag,display_name,model_category,assigned_to",
          applicabilities: [
            {
              $id: Now.ID["assets_active_applicability"],
              applicability: assetApplicability
            }
          ]
        },
        {
          $id: Now.ID["assets_all"],
          title: "All",
          order: 20,
          condition: "",
          table: "alm_asset",
          columns: "asset_tag,display_name,model_category,assigned_to",
          applicabilities: [
            {
              $id: Now.ID["assets_all_applicability"],
              applicability: assetApplicability
            }
          ]
  }
]

Applicability object

Define the audience [sys_ux_applicability] that can view a list in the UX list menu configuration.

Table 5. Properties

Name	Type	Description
$id	String or Number	Required. A unique ID for the metadata object. When you build the application, this ID is hashed into a unique sys_id. For more information, see ServiceNow Fluent language constructs. Format: Now.ID['String' or Number]
name	String	Required. A name for the applicability rule.
description	String	A description of the audience.
active	Boolean	Flag that indicates whether the applicability rule is applied. Default: true
roles	Array	A list of variable identifiers of Role objects or sys_ids of roles that a user must have to view the list. For more information, see Role API - ServiceNow Fluent.
roleNames	String	A comma-separated list of role names that a user must have to view the list. This property is an alternative to the roles property.

import { Applicability } from '@servicenow/sdk/core';

const managerApplicability = Applicability({
    $id: Now.ID['manager_applicability'],
    name: 'Managers Only',
    roles: [managerRole]
})

The role referenced is defined using the Role object:

import { Role } from '@servicenow/sdk/core';

const managerRole = Role({
    $id: Now.ID['manager_user_role'],
    name: 'x_snc_manager.user',
    containsRoles: ['canvas_user']
})