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.

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.

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 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.

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.