Configuring Lists in Configurable Workspace

[Ashley Snyder]

• COE
• Workspace Resource Hub
• Configuring Lists in Configurable Workspace

FYI: This article has not been updated or reviewed since the Tokyo release. Use at your discretion, but be advised that these methods may or may not work on later releases.

Table of Contents

Lists Configuration Applicability M2M Applicability Declarative Actions Highlighted Values Related Lists Data Visualization Drilldown

This article is written for users who are configuring product-line workspaces, workspaces created from App Engine Studio, or using the out-of-the-box page templates as these templates are pre-configured with multiple components and bindings. It is not written for Agent Workspace configuration, though some of the information may still apply. Some of the information can apply to users who are creating pages with individual components but is not a definitive resource for that use case. For more technical information on components see the Component Library on the Developer site. 

Lists

You can configure lists either when you create a workspace experience via App Engine Studio. If you're working with a pre-existing workspace or product workspace you can configure workspace lists in UI Builder. When working in UI Builder, navigate to the List page for the workspace you're working with. If you're working with out-of-the-box or read-only page templates, you may see there's a Read-only protection banner on the page. This is okay because we're not modifying the page itself, only the data that is being sent to the list component. If you click on the List nav component (actual name List menu) in the content tree, you'll see the Config panel for the component.

At the bottom of the Config panel for the list component there are three links to configure the workspace list. Note: This isn't just specific to Workspace, this is just the context of this article. You can add the List Menu component to an experience page and you'll see these same configuration options.

Configuration

This link jumps to the UX List Menu Configuration (sys_ux_list_menu_config) table, which shows the configurations for each Workspace/Experience. Clicking into the experience you're configuring will show a the record with the related lists:

UX List Categories (sys_ux_list_category): The categories that show on your list menu, i.e. Incidents, Problems, Cases, etc. and links to the Configuration property for the list menu component.

UX Lists (sys_ux_list): Lists defined for each category. A list must have a category and you can configure the conditions for the list data, columns, grouping, and other parameters you can set. You'll notice that you cannot configure the component properties for a List component when the page is read only, but many of those properties are exposed in the UX List record for configuration, so you do not need to duplicate the page to set List properties.

 

Applicability

Now that our categories and lists have been configured, we will want to control who can see them. The applicability tab brings us to the first step in doing this where we create an Audience (sys_ux_applicability_list). An Audience is a set of role based criteria for records such as lists, or variants to evaluate against for viewing permission. Audiences can be expanded with the UX Framework User Criteria plugin which is available to request from the Support site to target groups, users, companies, etc. You may already have an out-of-the-box audience you want to use, or can create one here.

M2M Applicability

The last step to is tie our list configuration and audiences together to determine which audience(s) can view a list. This is done with the M2M Applicability link, which jumps to the List Applicabilities (sys_ux_applicability_m2m_list) table. In this table you'll see out-of-the-box records created when installing a product workspace, or via creating an experience via App Engine Studio, and can create a new record if needed via entering the List and Applicability. This will determine which audience can see the list, and you can create multiple records to bind multiple audiences to a list.

Declarative Actions/List Buttons

If you wish to add declarative actions to your list, you can do it from the List component in UI Builder found under the Config panel. Clicking the Actions Config link will jump to the UX Actions Configurations (sys_ux_action_config) table. This table contains which Declarative Actions/UI Actions display for an experience. If you do not see one for your experience, you will need to create one. Check out this COE article for more information on creating Declarative Actions.

You can tie existing Declarative Actions to your experience here, keep in mind each related list corresponds to an Action Model type, meaning you cannot use a Form Action as a List Action.

In this example the GlideList API was used to create a declarative action that will only show Active records in the list when the user clicks it and linked to the workspace experience. For more information on the GlideList API see the product documentation.

Highlighted Values

This link jumps to the UX Highlighted Value Configurations table. Highlighted fields in list appear colored and optionally have a leading bullet. You use Highlighted value configurations to determine the highlighting for lists per experience. You may see out-of-the-box configuration records for your experience or may need to create a new configuration record. Under the configuration record you add Highlighted Values records. You can create new highlighted values or use existing ones. In this example the the Incident Management Priority Highlighted Value for Incident has been re-used and associated to a custom workspace. One thing to mention is that you'll want to double check the UX Lists record to verify Hide Highlighted Values is unchecked. If you have two or more UX Highlighted Configurations for a Highlighted Value, you may need to set the ordering on them to not be the same for the highlights to show.

 

 

Related Lists

Related lists are shown on the Record page, related lists are set up for the table itself and not via UI Builder. The component Record Page Tabs imports the related lists from the view on the record, this view may be the Workspace view, or you can set your own Workspace view rules. The Details tab shows the view of the record, and form sections can be jumped to via clicking the three vertical dots next to the record title. Adding buttons or actions on Related Lists can be done via Declarative Actions. 

You can change the ordering of the tabs and which tab defaults via Workspace view rules by navigating to Workspace Experience > Forms > Workspace View Rules, this is an example of Agent Workspace and Configurable Workspaces sharing the same functionality and modules for configuration. You can create a view rule for your view based upon conditions or not and within the Form Tabs section use the Default Tab Order, or create your own. The Set up Related Items in Workspace product documentation walks through some of this, while it is meant for Agent Workspace the view rule configuration does apply to Configurable Workspaces.

Data Visualization Drilldown

You may want to open a list or simple list from a data visualization component with a specific list view. The list will open in the Default view unless the component is passed a different value for the listView parameter. If you inspect the Config panel of a list component you'll see a View parameter, and it's expecting @context.props.listView passed to it. This is helpful to know, because this means we can pass the view that we want to use via the URL in an event when clicking a data visualization. In this example we'll reuse the Simple List page that is packaged with most product-line workspaces and the App Engine Workspace to show a list when clicking a data visualization. For clarity, the Simple List page uses a list component, and not the simple list component.

1. In this example we'll re-use the default Home page that is shipped with an App Engine Studio workspace. 

2. Before we configure a data visualization on the Home page, we need to add an optional parameter to the Simple List page so that it accepts the listView parameter we want to pass. Note: You can add required and optional parameters to a read-only page template without accepting ownership of these pages will retain updates via upgrades.

3. Next, we'll place a data visualization component (or re-use one) on the Home page, and configure a Link to destination event. For this example, I'm going to reuse a view that was installed with the Service Operations Workspace, but you can use views you've created for your lists. In this example I placed a new data visualization on the page and am configuring an event.

In the Link to destination event, you can click the Select destination button, and will see the panel to choose an app route. The app routes are the pages we have available to the workspace, so if you create a page you'll see it here. Since we're reusing the out-of-the-box Simple List page, we will select it and configure as follows, to note, @payload is coming from the event that is triggered 

table: @payload.params.table (The table you're passing from the data visualization)

listTitle: @payload.title (This is optional, but this sets the tab title from Loading... to a value)

query: @payload.params.query (The conditions you set on your data visualization)

listView: Your view, make sure this is the name of the view and not the title. I hardcoded this in, but it can be bound dynamically as well.

4. After saving off the event and page, open the page and click the data visualization you created and configured the event to. You'll notice in the URL that the list-view parameter is being passed, and your list is using the view you specified instead of the default view. If you used the listTitle parameter, you'll notice the tab for the list has the value you passed instead of the default 'Loading...' text.

[Mike Naputano]

@Ashley Snyder - Is there a way that you can group categories together? For example, we have a customer that would like to break list views down by regions for work order tasks. So we were interested in a structure like this:
Work Order Tasks (category)
North East Region (subcategory)
Assigned Tasks (list)

Pending Dispatch (list)

Completed Tasks (list)

South East Region (subcategory)

Assigned Tasks (list)

Pending Dispatch (list)

Completed Tasks (list)

Each of the lists above would have a specific filter based on the assignment groups so they only display the proper tasks for those regions.

Thanks!

Mike

[Uma2]

Hi @Ashley Snyder Thank for the Informative post.

I have one issue related to Related list layout configuration.

I want to replicate the same Related List layout same as native UI, Could you help me how we can do those changes.

[Luis Severo]

Is there a way to call a Script Include in a sys_ux_list?

[Rose L]

Hi @Ashley Snyder,

My customer would like to use the CSM configurable workspace. However, since their major case view has certain fields that should be hidden from the usual case view, may I know if there is anyway that we can set a different default opening view for the major cases?

Right now, in the platform UI, agents can open the case form in the case view, while open the major case records in the major case view. However, when it comes to the workspace, seems both the normal case and the major case are both opening in the workspace view so we can't hide the fields in the workspace for major case. 

Would be good to know a way to show a different view in the workspace for the same table if possible. 

Thanks,

Rose

[Shannon Burns]

@Ashley Snyder If I want to make it so that the agents cannot create a list from their own source, how do I do that?

Thanks,

Shannon

[Ashu_8871]

What if we need to apply list applicability directly to UX list Categories and not UX lists.
Like we Assign role directly to the Application and not Module level in native UI?

[Magda Abu Aitah]

Hi @Ashley Snyder 

Regarding the "Data Visualization Drilldown", is it possible to do the same for a component inside a Workspace Dashboard? Specifically when you click on "View All" of the report that leads to the Simple List page.

[Tushar]

Hi @Ashu_8871  you can use below script to apply list applicability directly to UX List categories -

// Category sys_ids
var categorySysIds = [
    'sysid1', // enter your category sys ids 1
    'sysid2', // enter your category sys ids 2
 
];

// Loop through each category
for (var i = 0; i < categorySysIds.length; i++) {
    var categoryId = categorySysIds[i];

    // Getting all lists with the current category
    var grList = new GlideRecord('sys_ux_list');
    grList.addQuery('category', categoryId);
    grList.query();

    // Loop through each list record
    while (grList.next()) {
        // Creating a new record in sys_ux_applicability_m2m_list
        var newItem = new GlideRecord('sys_ux_applicability_m2m_list');
        newItem.initialize();

        // Set the applicability and sys_scope fields
        newItem.applicability = 'your_sys_id';
        newItem.sys_scope = 'your_sys_id';

        // Reference the list instead of setting sys_id directly
        newItem.list = grList.sys_id;

        // Insert the new record
        if (!newItem.insert()) {
            gs.error('Failed to insert record for list: ' + grList.sys_id + '. Error: ' + newItem.getMessage());
        } else {
            gs.info('Record inserted successfully for list: ' + grList.sys_id);
        }
    }
}

// Succes message
gs.info('Created records in sys_ux_applicability_m2m_list');

[PallavS]

Super helpful and well detailed doc. Helped me knock down a defect. Thanks @Ashley Snyder 🙌

[Community Alums]

Hi @Ashley Snyder , is there any way I can hide a column on the workspace and make it not visible and selectable from list filter? Thanks

[jose rosales]

@Community Alums I ended going the ACL route for my client.  Article  https://www.servicenow.com/community/itsm-forum/hide-column-from-list-view/m-p/737895  

[MichaelZischeck]

great... many thanks... I did some Declarative actions already. Your approach is way simpler...

If I want to add declarative actions to the "record" page, where do I have to look for the action configuration link in UI Builder?

I follow your other article https://www.servicenow.com/community/next-experience-articles/introduction-to-declarative-actions/ta... and I stumbled (more than once...) on the "different models for declarative actions"..

is there no easier way than you describe in the other article?

I find it massively confusing. Action Payload definition is literally nowhere explained

Also Action Assignment and M2m Action Assign Ux Action Config, depending on where you click in the list.

what I would like is: kind of a map which components come together where and what do they influence...

I took me days to figure out a way to expose an "Export" button in related lists on a record...

[Jeff Wentworth]

This is a great community discussion. Thanks Ashley!

Any plans to update this article for Xanadu forward?