The Portal data widget displays content such as cases, invoices, or data from any table in a list.
Below you can see Portal Data list widget. In this example, it's displayed on the Business Portal.
This widget is out of the box for the Business Portal and other CRM & Industry customer portals that leverage Configurable Portal Widgets.
When the business user or administrator does a "Control and Right-Click", the instance options display.
There are several widgets that leverage JSON (JavaScript Object Notation) to define the widget content and behavior.
The Portal Data List widget is one of the widgets that uses JSON formatting to display information. Typically it's the case or order table displayed, but it can be leveraged for any ServiceNow table.
Documentation Portal Data list Widget
Let’s review the format below for the parameter name and value:
“Parameter name”:”value”
|
JSON Parameter name |
Description |
|
categories |
Each category displays a set of records from the table that meets the filter criteria. For each category, you can choose from pre_defined_filters and run_time_filters predefined filter tabs, set the columns for the list view, and determine the fields to be shown in the card view. ServiceNow table in list and card format along with the capability to search and filter content. |
|
ID |
A unique identifier that enables the categories condition script to determine whether to show or hide categories on the widget |
|
category |
Name of the category that appears on the navigation pane. If a label isn’t entered, the category doesn't appear. |
|
table |
The table from which the records are shown on the widget when a category is selected. By default, this field is set to the Case [sn_customerservice_case] table. Any other table could be displayed. |
|
view |
The name of the view that defines the list of columns or fields to appear on the widget. If no value is provided, all columns are shown |
|
card_view_primary_column |
A field from the defined table to be displayed in the first column of a card. For example, you can show the case number in the first column. |
|
card_view_secondary_column |
A field from the defined table to be displayed in the second column of a card. For example, you can show short description of the case record. This parameter is optional. |
|
card_view_additional_columns”:”column1|column2| column3|column4” |
Field pairs from the defined table to be displayed as additional columns of a card. You can add a maximum of four additional columns. This parameter is optional. |
|
query":"active=true" |
Query to filter the records that display under the category. If no value is provided, all records are displayed |
|
glyph":"glyph_name" |
The glyph to appear on the left of the category label in the navigation pane. The glyph name provided should be from the font-awesome library, which can be accessed at the following URL: https://fontawesome.com/versions/icons The currently supported version of the font-awesome library is v4.7. If you use a glyph name from a different version, the image will not appear correctly. Note: If both a glyph and an image are defined, the image is displayed. This parameter is optional |
|
"image_name":"file_img" |
An image to appear on the left of the category. The image name should be selected from the Images [db_image] table. Note: If both a glyph and an image are defined, the image is displayed. This parameter is optional. |
|
target_page_id |
The portal page that displays the details of any record accessed in the widget. This parameter is optional. By default, this field is set to the Case (csm_ticket) page. |
|
sub_categories |
Display cases which are in New, Closed, Open, or Awaiting Info state in any selected category. These filters appear as tabs in the widget. Only Open and Closed case are included by default in the JSON code. You can change the names of these filters by changing the value of filter_name. This parameter is optional. |
|
run_time_filters |
Displays column and its fields from the defined table as runtime filters in a drop-down list. These runtime filters filter the case records displayed in the widget based on different fields from the defined table. For example, you can display Priority as a column and State, Contact, or Updated as fields. If the runtime filters values are not provided in the column and selection_type parameters, the filter icon will not appear for the category. This parameter is optional. column: |
|
column |
A field from the defined table to be displayed as a runtime filter in the widget. \For example, you can choose to display case records according to their Priority, such as Critical, High, Moderate, or Low. |
|
selection_type |
Display the type of selection. The available options are: Single select: Single selection for the filter column Multi select: Multiple selection values for the filter columns |
|
values |
Defines the values from the defined table for the column parameter. The available values are: Value: Integer value of a field Label: Name of a value |
|
ranges |
Used to filter the records from the table using a query defined in label and query parameters. For example, you can display case records that have been updated in the last month, last 3 months, or last 6 months. The range configuration is: Label: Name of the filter option Query: Query that defines a set of values grouped under a label This parameter is optional. |
|
filter |
Used to apply filter on the data list. Static: The value of the condition is provided in the query, for example, StateIN1. Dynamic: The value of the condition is taken from the portal page URL by providing the URL keyword in curly braces, for example, product={sys_id}. The sys_id is taken from the URL and the replaced into the query. Note: If no keyword is found in the URL, the query becomes product=null. |
The administrator or business analyst that will configure this portal data list widget must be familiar with the table and data elements that will be displayed in the widget (e.g. case, order, case tasks, invoice) in order to provide information for the JSON parameters.
As an example, one commonly used data element is the Case state to learn more see case state documentation.
To see the actual data values that could be configured for any table, you can look at the system choice list table for that data element to learn more see choice list documentation
Example 1: View Open Cases
This configuration displays all cases that are not in a closed or resolved state. It displays the case number, short description, priority"
Case Explanation:
- State NOT IN 3,4,7: Excludes Resolved (3), Closed (4), and Cancelled (7) states
-
State Values Reference:
- 1 = New
- 2 = In Progress
- 3 = Resolved
- 4 = Closed
- 6 = On Hold
- 7 = Cancelled
- 18 = Awaiting Info
-
- ORDERBYDESCopened_at: Sorts by most recently opened first
- Pre-defined filters allow users to further refine by specific open states
- target_page_id: "csm_ticket" navigates to the case form page when clicking a record
JSON -
[
{
"category": "Open Cases",
"table": "sn_customerservice_case",
"view": "csp",
"card_view_primary_column": "number",
"card_view_secondary_column": "short_description",
"card_view_additional_columns": "priority|state|opened_at|contact",
"glyph": "folder-open",
"target_page_id": "csm_ticket",
"pre_defined_filters": [
{
"filter_name": "All Open",
"filter_query": "stateNOT IN3,4,7^ORDERBYDESCopened_at"
},
{
"filter_name": "In Progress",
"filter_query": "state=2^ORDERBYDESCopened_at"
},
{
"filter_name": "On Hold",
"filter_query": "state=6^ORDERBYDESCopened_at"
}
]
}
]
-----------------------------------------
Example 2:
Show cases assigned to me, cases that need my action and overalll all my cases
Explanation:
assigned_toDYNAMIC90d1921e5f510100a9ad2572f2b477fe: Filters to logged-in user dynamically- DYNAMIC90d1921e5f510100a9ad2572f2b477fe is the dynamic filter for "Me" (currently logged-in user)
stateIN6,18: Shows cases On Hold (6) or Awaiting Info (18) for "Action Needed" filter- Allows users to see only cases they're responsible for
Note: For external portal users with the sn_customerservice.customer role, you may need to add a READ ACL on the assigned_to field to prevent console errors.
JSON -
[
{
"category": "Assigned to Me",
"table": "sn_customerservice_case",
"view": "csp",
"card_view_primary_column": "number",
"card_view_secondary_column": "short_description",
"card_view_additional_columns": "priority|state|opened_at|account",
"glyph": "user",
"target_page_id": "csm_ticket",
"pre_defined_filters": [
{
"filter_name": "My Open Cases",
"filter_query": "assigned_toDYNAMIC90d1921e5f510100a9ad2572f2b477fe^stateNOT IN3,4,7^ORDERBYDESCpriority"
},
{
"filter_name": "My Action Needed",
"filter_query": "assigned_toDYNAMIC90d1921e5f510100a9ad2572f2b477fe^stateIN6,18^ORDERBYDESCopened_at"
},
{
"filter_name": "All My Cases",
"filter_query": "assigned_toDYNAMIC90d1921e5f510100a9ad2572f2b477fe^ORDERBYDESCopened_at"
}
]
}
]
-----------------------------------------
Example 3 – Configure the Portal data list widget to show all cases, with data for case number, short description, product and contact for the Category “Actions Needed”
JSON:
[ { "category": "Actions Needed", "ID": "actions_needed", "table": "sn_customerservice_case", "view": "csp", "card_view_primary_column": "number", "card_view_secondary_column": "short_description", "card_view_additional_columns": "product|contact|account|priority", "filter": "state=18", "target_page_id": "standard_ticket", "run_time_filters": [ { "column": "product", "selection_type": "multi_select" }, { "column": "contact", "selection_type": "multi_select" }, { "column": "account", "selection_type": "multi_select" }, { "column": "priority", "selection_type": "multi_select" }, { "column": "state", "selection_type": "multi_select" } ] } ]
-----------------------------------------
Example 4:
Multiple Combination of cases using filters for all open cases, priority cases, assigned to me, recent cases
[
{
"category": "Open Cases",
"table": "sn_customerservice_case",
"view": "csp",
"card_view_primary_column": "number",
"card_view_secondary_column": "short_description",
"card_view_additional_columns": "priority|state|opened_at|contact",
"glyph": "folder-open",
"target_page_id": "csm_ticket",
"pre_defined_filters": [
{
"filter_name": "All Open",
"filter_query": "stateNOT IN3,4,7^ORDERBYDESCopened_at"
}
]
},
{
"category": "Priority Cases",
"table": "sn_customerservice_case",
"view": "csp",
"card_view_primary_column": "number",
"card_view_secondary_column": "short_description",
"card_view_additional_columns": "priority|state|opened_at|assigned_to",
"glyph": "exclamation-triangle",
"target_page_id": "csm_ticket",
"pre_defined_filters": [
{
"filter_name": "Critical & High",
"filter_query": "priorityIN1,2^stateNOT IN3,4,7^ORDERBYpriority"
}
]
},
{
"category": "Assigned to Me",
"table": "sn_customerservice_case",
"view": "csp",
"card_view_primary_column": "number",
"card_view_secondary_column": "short_description",
"card_view_additional_columns": "priority|state|opened_at|account",
"glyph": "user",
"target_page_id": "csm_ticket",
"pre_defined_filters": [
{
"filter_name": "My Open Cases",
"filter_query": "assigned_toDYNAMIC90d1921e5f510100a9ad2572f2b477fe^stateNOT IN3,4,7^ORDERBYDESCpriority"
}
]
},
{
"category": "Recent Cases",
"table": "sn_customerservice_case",
"view": "csp",
"card_view_primary_column": "number",
"card_view_secondary_column": "short_description",
"card_view_additional_columns": "priority|state|opened_at|contact",
"glyph": "clock-o",
"target_page_id": "csm_ticket",
"pre_defined_filters": [
{
"filter_name": "Last 24 Hours",
"filter_query": "opened_at>=javascript:gs.beginningOfLast24Hours()^ORDERBYDESCopened_at"
}
]
}
]
Related links:
Additional information in Documentation - Configure Widget Instance Options
Training:
Related links: