With the ServiceNow Yokohama Release, the list controller comes with several exciting new features. In this article series, I’m sharing what I’ve learned while exploring these enhancements.
This second article focuses on context row actions, a powerful addition to the list view. If you’re curious about what’s now possible out of the box (OOTB), this is for you! And if you haven’t read the first article yet, be sure to check it out.
Exploring the Yokohama list controller – Part 1 – Adding SLA Timer
In this second article, we’ll dive into context row actions, a powerful addition to the list view. We’ll use this feature to provide an opportunity to highlight the short description of an incident record.
As in the first article, we’ll use the "Customizations to run on data fetch" option in the list controller. In UI Builder, you can find this option by opening the list controller, navigating to the Configure tab, and scrolling to the bottom.
In the first article, we already created a custom copy of the default script used in Service Operations Workspace. Now, we’ll extend this script further to implement the use case described earlier.
We’ll implement a context row action that allows us to highlight the short description of incidents. To store whether an incident should be highlighted, we need to create a new column for the incident table. We name it “Highlight” [u_highlight], the type is true/false.
First, we’ll focus on highlighting the short description when the Highlight (u_highlight) column is set to true. Once that is implemented, we’ll proceed with creating a context row action that allows users to toggle the highlight value directly from the list.
Within our Script Include, we can utilize the rowDefinitions object to customize the appearance of the list.
For our use case, we’ll iterate over the rows, and if the u_highlight column is set to true, we will update the highlightedValue property of the short_description cell to visually emphasize it.
listModel.rowDefinitions.rows.forEach(function (row) {
if (row.cells.hasOwnProperty("u_highlight") && row.cells.u_highlight.value == true) {
row.cells.short_description.highlightedValue = {
"color": "critical",
"variant": "tertiary",
"field": "short_description",
"value": row.cells.short_description.value,
"status": "critical",
"showIcon": true,
"iconName": "marker-fill"
}
}
});
That's all we need to highlight the short description when the u_highlight value is set to true.
Now, we’ll implement the row context action to allow users to toggle the highlight status directly from the list.
The out-of-the-box (OOTB) Service Operations Workspace (SOW) Script Include already contains actions like Copy URL and Copy sys_ID. Because of this, an object called rowActionsObj already exists. We will use this object and add our own row action to it. We do this inside the if-block for incident lists.
rowActionsObj['add'].push({
id: 'my_highlight',
icon: 'enterprise-asset-management-outline',
label: "Highlight",
action: 'LIST#MY_OWN',
index: actionIndex
});
actionIndex++;
This adds the row action to the context menu, but clicking it doesn’t trigger any functionality yet.
To set the highlight value when the row action is clicked, we need to configure two key components in UI Builder (UIB): a client script (sys_ux_client_script) and an Update Record Data Resource. The client script will be triggered by the "Context Action Clicked" event of the Presentational List component. Its role is to determine whether the correct row action was selected and if that’s the case updating the highlight value of the corresponding incident record. The event payload contains the actionItem that was clicked. We use the id property of the actionItem to check if the event was triggered by our row action. If that’s the case we use the Update Record data resource to modify the u_highlight field on the incident record.
/**
* @Param {params} params
* @Param {api} params.api
* @Param {any} params.event
* @Param {any} params.imports
* @Param {ApiHelpers} params.helpers
*/
function handler({api, event, helpers, imports}) {
const id = event.payload.actionItem.id;
if(id === "my_highlight"){
const sysId = event.payload.context.row.key;
const templateFields = "u_highlight=true";
api.data.update_record_1.execute({
table:"incident",
recordId: sysId,
templateFields
});
}
}
We can observe that this sets the value of u_highlight but the change is not directly visible in the workspace. To achieve this we create a event mapping for the “Operation Succeeded” Event of the Update Record data resource and trigger the “Data refresh requested” Event handler of the list controller.
Now that the context row action successfully highlights the short description, you can follow the same approach if you need to add a context row action to remove the highlighting or something else.
However, there is still one issue left. When opening the context menu on a row where the short description is already highlighted, we want to disable the Highlight action to prevent redundant toggling.
To achieve this, we use the toggleRowActionsEnablement function. We define an object that contains an array, which we populate with objects representing the rows where we want to disable the Highlight action.
var editActionsObj = {
disable: []
};
var actionIds = ["my_highlight"];
Inside the incident if-block, we utilize the rowDefinitions object to iterate through all rows. As we loop through each row, we check whether the u_highlight field is set to true. If it is, we add that row to the disable array, ensuring that the Highlight action is disabled for already highlighted incidents.
transformBuilder.rowDefinitions.rows.forEach(function (row) {
if (row.cells.hasOwnProperty("u_highlight") && row.cells.u_highlight.value == true) {
editActionsObj.disable.push({
rowKey: row.key,
actionIds: actionIds
});
}
});
Don’t forget to call the function toggleRowActionsEnablement
toggleRowActionsEnablement(editActionsObj)
Now, the Highlight action is automatically disabled when the short description is already highlighted.
Complete Code:
(function transform(transformBuilder, transformScriptArgs) {
try {
if (!transformBuilder) return;
// Build rowActions object that is passed down as param in editRowActions function
var rowActionsObj = {
add: []
};
var actionIndex = 1;
if (gs.hasRole("sn_sow.sow_list") || gs.hasRole("itil")) {
rowActionsObj['add'].push({
id: 'copy_url',
icon: 'square-share-outline',
label: gs.getMessage('Copy URL'),
action: 'LIST#COPY_URL',
index: actionIndex
});
actionIndex++;
}
if (gs.hasRole("admin")) {
rowActionsObj['add'].push({
id: 'copy_sysId',
icon: 'documents-outline',
label: gs.getMessage('Copy sys_id'),
action: 'LIST#COPY_SYSID',
index: actionIndex
});
actionIndex++;
}
var editActionsObj = {
disable: []
};
var actionIds = ["my_highlight"];
rowActionsObj['add'].push({
id: 'my_highlight',
icon: 'enterprise-asset-management-outline',
label: "Highlight",
action: 'LIST#MY_OWN',
index: actionIndex
});
actionIndex++;
var newCols = [];
if (transformBuilder.tableName == "incident") {
newCols.push({
index: 3,
column: {
key: "sla",
type: "custom",
label: "SLA",
componentTag: "now-sla-timer",
},
columnData: [],
});
transformBuilder.rowDefinitions.rows.forEach(function(row, index) {
newCols[0].columnData.push({
rowKey: row.key,
cellValue: {
componentProps: {
task: row.key,
showIcon: true
},
},
});
});
transformBuilder.rowDefinitions.rows.forEach(function(row) {
if (row.cells.hasOwnProperty("u_highlight") && row.cells.u_highlight.value == true) {
editActionsObj.disable.push({
rowKey: row.key,
actionIds: actionIds
});
}
});
}
var listModel = transformBuilder
/* INSTRUCTIONS */
// The below commented out calls are customizations that can be applied to the list.
// Uncomment any customizations that you would like to use, and provide your own arguments.
// We recommend that if possible, you maintain the order the functions are written in, and only use each function once. This prevents accidentally overwriting a customization.
// Please note note that any operations involving removal or disabling will be executed before operations involving addition or enabling.
// Keep in mind that any customizations are only for rendering and will not be persisted in any capacity.
// This script will run on every data fetch, including initial fetch, filtering, sorting, grouping, etc.
// This API is defined in sys_script_include_a816a0930535a510f8777eba8d465d65, see that file for source code and documentation.
/* DATA MUTATORS */
/**
* Adds new columns and their corresponding body data at a provided index.
*
* @Param {Object[]} newColumns Array representing all the columns to be added, index and their respective column data
* @Param {Object} newColumns[].column An object containing the definiton of a single column. Full column docs - <public url>/now-list/typeSchemas/columnDefinitions/columnsDocs.md
* @Param {number} newColumns[].index The 0-based index at which the column needs to be added. If empty or falsy, the columns is added at the end of the table.
* @Param {Object[]} newColumns[].columnData Array representing all of the columns' cell data to be added and their respective row keys
* @Param {string} newColumns[].columnData.rowKey The key of a row to update
* @Param {Object} newColumns[].columnData.cellValue An object containing the data for a single cell. Full cells docs - <public url>/now-list/typeSchemas/rowDefinitions/cellsDocs.md
* TODO: add public urls for docs for columnsDocs and cellDocs
*/
.addColumns(newCols)
/* COLUMN HEADER MUTATORS */
/**
* Changes the label (text) for one or many column header cells
*
* @Param {Object[]} newLabels Array representing all the columns to be edited and their respective new labels
* @Param {string} newLabels[].columnKey The key of a column to update
* @Param {string} newLabels[].newLabel The new label to display
*/
//.editColumnLabels(newLabels)
/**
* Toggles the enablement of the column header label click based on the provided edit type for one, many, or all columns.
* This function can be used to undo the default behavior of sorting a column on header text click.
* It can also be used to add clickability to a custom added column, for example for a custom sort.
*
* @Param {Object} editColumnsObj Object containing 'enable' and 'disable' properties.
* @Param {string[]} editColumnsObj.enable Array of column keys for which to enable column header click.
* @Param {string[]} editColumnsObj.disable Array of column keys for which to disable column header click.
*/
//.toggleColumnHeaderClickEnablement(editColumnsObj)
/**
* Sets the column header text click action text for one, many, or all columns.
*
* @Param {string} text The new text to display in a tooltip on every column that conveys what action clicking triggers. If empty or falsy, all columns will be disabled and will not have a tooltip.
*/
//.setColumnHeaderClickActionText(newText)
/**
* Updates the column header icons based on the provided edit type.
*
* Added icons are purely decorative and not clickable.
* @Param {Object} editIconsObj Object containing 'add' and 'remove' properties.
* @Param {Object[]} editIconsObj.add Array representing all the columns to be edited and their respective inputs for adding icons.
* - @Param {string} editIconsObj.add[].columnKey The key of a column where column header icons should be added.
* If null, icons will be added to every column.
* - @Param {'start'|'end'} editIconsObj.add[].position The position to add these icons, relative to the text label.
* Either 'start' or 'end'.
* - @Param {Object[]} editIconsObj.add[].iconArr Array of objects representing the icons to be added, from start to end.
* - @Param {string} editIconsObj.add[].iconArr[].value Name of the icon to render from the icon library.
* - @Param {string} editIconsObj.add[].iconArr[].color Color variant for the icon, e.g., 'warning' or 'moderate'.
* - @Param {string} editIconsObj.add[].iconArr[].label Aria-label to be used for accessibility.
* @Param {Object[]} editIconsObj.remove Array representing all the icons to be removed and from which columns.
* - @Param {string} editIconsObj.remove[].columnKey The key of a column where column header icons should be removed.
* If null, icons will be removed from the given position across the table. If position is also null, icons for both positions will be removed.
* - @Param {'start'|'end'} editIconsObj.remove[].position The existing position of the icon(s) to be removed, relative to the text label.
* Either 'start' or 'end'. If null, icons for the given column will be removed from both positions.
* - @Param {number[]} editIconsObj.remove[].iconIndexArr Array of 0-based indices of objects representing the icons to be removed.
* If null, all icons will be removed from the given position. If position is also null, all icons for both positions will be removed.
*/
//.editColumnHeaderIcons(editIconsObj)
/**
* Sets a column's aria-sort value. This does not actually sort the data, just provides context to screen reader users if the data has already been sorted.
*
* @Param {string} columnKey The key of the column that will receive a new sort value. If empty or falsy, all columns will be set to "none" regardless of the value of the direction parameter.
* @Param {'ascending' | 'descending' | 'none'} direction The direction of the sort.
*/
//.setColumnSortDirection(columnKey, direction) {
/**
* Toggles the ability to click on the text in a given column of type URL, link, or person.
* If you want to toggle this for all columns across the list, we recommend using the boolean property on the controller.
*
* @Param {Object} editColumnObj Object containing 'enable' and 'disable' properties.
* @Param {string[]} editColumnObj.enable An array of column keys where clickable text should be enabled.
* If empty or falsy, clickable text will be enabled in all columns.
* @Param {string[]} editColumnObj.disable An array of column keys where clickable text should be disabled.
* If empty or falsy, clickable text will be disabled in all columns.
*/
//.toggleColumnEnablement(editColumnObj)
/**
* Toggles the ability to click on the text in a given cell of type URL, link, or person.
* The value of disabled at the cell level overrides the value of disabled at the column level.
*
* @Param {Object} editCellsObj Object containing 'enable' and 'disable' properties.
* @Param {Object[]} editCellsObj.enable Array of objects representing cells where clickable text should be enabled.
* - @Param {string} editCellsObj.enable[].rowKey The key of the row containing the cell.
* - @Param {string} editCellsObj.enable[].cellKey The key of the cell.
* @Param {Object[]} editCellsObj.disable Array of objects representing cells where clickable text should be disabled.
* - @Param {string} editCellsObj.disable[].rowKey The key of the row containing the cell.
* - @Param {string} editCellsObj.disable[].cellKey The key of the cell.
*/
//.toggleCellsEnablement(editCellsObj)
/**
* Changes the column width for one or many columns
* This new width will remain in effect until the user manually resizes any column. If the user resizes a column, the manually adjusted width will take precedence.
* Users can be prevented from resizing a column by setting `columnResizingEnabled` to false. Full doc: <public url>/now-list#public-props
*
* @Param {Object[] | string} newWidths Either an array representing all the columns to be edited and their respective new widths, or a string representing the width in px to be set for every column, eg '40px'.
* @Param {string} newLabels[].columnKey The key of a column to update
* @Param {string} newLabels[].newWidth The new width in px
*/
//.setColumnWidths(newWidths)
/**
* Changes the maximum number of characters allowed to be displayed per cell before truncation for one or many columns
*
* @Param {Object[]} newMaxChars Either an array representing all the columns to be edited and their respective new maximum.
* @Param {string} newMaxChars[].columnKey The key of a column to update
* @Param {string} newMaxChars[].newMaxChars The new maximum characters in the column
*/
//.setColumnMaxCharacters(newMaxChars)
/**
* Sets highlighted values for cells
*
* @Param {Object[]} newHighlightedValues An array representing the highlighted values and the cell they should appear in.
* @Param {string} newHighlightedValues[].rowKey The key of a row containing the cell
* @Param {string} newHighlightedValues[].cellKey The key of a cell to set highlighted value
* @Param {Object} newHighlightedValues[].highlightedValueObj The object containing the highlighted value. Full highlighted value doc - <public url>/now-list/typeSchemas/rowDefinitions/cellsDocs.md#highlighted-value
* TODO: add public urls for docs for cellDocs
*/
//.setHighlightedValues(newHighlightedValues)
/**
* Sets the display type for a person column: either avatar, name, or both. This function is not applicable to columns that are not the person type.
*
* @Param {Object[]} newDisplays An array representing the columns to update and their new display setting.
* @Param {string} newDisplays[].columnKey The key of a column to update.
* @Param {'avatar'|'name'|'both'} newDisplays[].newDisplay Sets the appearance of body cells in this column. Can be 'avatar', 'name', or 'both'.
*/
//.changeDisplayForPersonColumn(newDisplays)
/**
* Sets the numActionIcons property to determine the number of actions to render as icons.
* The first n items in the actionItems array will be rendered as icon buttons, and the rest will be hidden under a dropdown.
*
* @Param {number} numActionIcons Number of actions to render as icons
*/
.setRowActionCountOverflow(1)
/**
* Updates the row actions for all rows based on the provided edit type.
*
* @Param {Object} editActionsObj Object containing 'add' and 'remove' properties.
* @Param {Object[]} editActionsObj.add Array of objects representing the row actions to be added.
* - @Param {string} editActionsObj.add[].id A unique string identifier for this action
* - @Param {string} editActionsObj.add[].icon A now-icon name to represent this action
* - @Param {string} editActionsObj.add[].label The label to be displayed in tooltips and dropdowns
* - @Param {string} editActionsObj.add[].action The name of a Seismic action to dispatch
* - @Param {number} editActionsObj.add[].index The index at which to insert the action. If null or falsy, the action will be added to the end of the array.
* @Param {string[]} editActionsObj.remove An array of ID strings representing all the row actions to be removed.
* If empty or falsy, all the row actions will be removed
*/
.editRowActions(rowActionsObj)
/**
* Toggles enablement/disablement one or many row actions on a row by row basis. Any disabled actions will be visible but not interactable.
*
* @Param {Object} editActionsObj An array of objects representing the row actions to be toggled.
* @Param {Object[]} editActionsObj[].disable An array of objects representing the row actions to be disabled. The specified action will be visible but not interactable.
* - @Param {string} editActionsObj[].disable.rowKey The key of the row to update
* - @Param {string[]} editActionsObj[].disable.actionIds An array of action keys that represent actions to disable.
*/
.toggleRowActionsEnablement(editActionsObj)
/**
* Updates the column header actions based on the provided edit type.
* If all actions are removed through this function, the default column filtering popover will display on the list.
*
* @Param {Object} editColumnActionsObj Object containing 'add' and 'remove' properties.
* @Param {Object[]} editColumnActionsObj.add Array of objects representing the column and its respective column header actions to be added.
* - @Param {string} editColumnActionsObj.add[].columnKey The key of the column to update
* - @Param {Object[]} editColumnActionsObj.add[].actionObjArr The action object to be added
* - @Param {string} editColumnActionsObj.add[].actionObjArr[].id The id of the action to be added
* - @Param {string} editColumnActionsObj.add[].actionObjArr[].label The label of the action to be added
* - @Param {string} editColumnActionsObj.add[].actionObjArr[].action The name of a Seismic action to dispatch on click
* - @Param {number} editColumnActionsObj.add[].actionObjArr[].index The index at which to insert the action. If null or falsy, the action will be added to the end of the array.
* @Param {Object[]} editColumnActionsObj.remove Array of objects representing the column and its respective column header actions to be removed.
* - @Param {string} editColumnActionsObj.remove[].columnKey The key of the column to update
* - @Param {string[]} editColumnActionsObj.remove[].actionIdArr The IDs of actions to be removed
*/
//.editColumnHeaderActions(editActionsObj)
/**
* Updates the cell actions across a whole column based on the provided edit type.
* This can be used to remove the default 'Show matching' and 'Filter out' actions, but we recommend using the controller prop if you want to remove both.
*
* @Param {Object} editActionsObj Object containing 'add' and 'remove' properties.
* @Param {Object[]} editActionsObj.add Array of objects representing the column and its respective cell actions to be added.
* - @Param {string} editActionsObj.add[].columnKey The key of the column to update
* - @Param {Object[]} editActionsObj.add[].actionObjArr The action object to be added
* - @Param {string} editActionsObj.add[].actionObjArr[].id The id of the action to be added
* - @Param {string} editActionsObj.add[].actionObjArr[].label The label of the action to be added
* - @Param {string} editActionsObj.add[].actionObjArr[].action The name of a Seismic action to dispatch on click
* - @Param {number} editActionsObj.add[].actionObjArr[].index The index at which to insert the action. If null or falsy, the action will be added to the end of the array.
* @Param {Object[]} editActionsObj.remove Array of objects representing the column and its respective cell actions to be removed.
* - @Param {string} editActionsObj.remove[].columnKey The key of the column to update. If empty or falsy, removes all cell actions across the list.
* - @Param {string[]} editActionsObj.remove[].actionIdArr The IDs of actions to be removed. If empty or falsy, removes all the cell actions on the column.
*/
//.editCellActionsForColumn(editActionsObj)
/**
* Updates the override cell actions based on the provided edit type.
* If there are no actions present in this override, the cell actions defined at the column level will be used instead.
*
* @Param {Object} editActionsObj Object containing 'add' and 'remove' properties.
* @Param {Object[]} editActionsObj.add Array of objects representing the cell and its respective cell actions to be added.
* - @Param {string} editActionsObj.add[].rowKey The key of the row to update
* - @Param {string} editActionsObj.add[].cellKey The key of the cell to update
* - @Param {Object[]} editActionsObj.add[].actionObjArr The action object to be added
* - @Param {string} editActionsObj.add[].actionObjArr[].id The id of the action to be added
* - @Param {string} editActionsObj.add[].actionObjArr[].label The label of the action to be added
* - @Param {string} editActionsObj.add[].actionObjArr[].action The seismic action to dispatch from the new action
* - @Param {number} editActionsObj.add[].actionObjArr[].index The index at which to insert the action. If null or falsy, the action will be added to the end of the array.
* @Param {Object[]} editActionsObj.remove Array of objects representing the cell and its respective cell actions to be removed.
* - @Param {string} editActionsObj.remove[].rowKey The key of the row to update
* - @Param {string} editActionsObj.remove[].cellKey The key of the cell to update
* - @Param {string[]} editActionsObj.remove[].actionIdArr The action ids to be removed
*/
//.editOverrideCellActions(editActionsObj)
/**
* Sets the expanded state of one or more groups
*
* @Param {Object[]} groupObjectArr An array of objects representing the group and its respective expanded state
* @Param {string} groupObjectArr[].groupKey The key of the group to update
* @Param {boolean} groupObjectArr[].isExpanded The expanded state of the group
*/
//.setGroupsExpandedState(groupObjectArr)
/**
* Updates the group actions based on the provided edit type.
*
* @Param {Object} editActionsObj Object containing 'add' and 'remove' properties.
* @Param {Object[]} editActionsObj.add Array of objects representing the group and its respective actions to be added.
* - @Param {string} editActionsObj.add[].groupKey The key of the group to update
* - @Param {Object[]} editActionsObj.add[].actionObjArr The action object to be added
* - @Param {string} editActionsObj.add[].actionObjArr[].id The id of the action to be added
* - @Param {string} editActionsObj.add[].actionObjArr[].label The label of the action to be added
* - @Param {string} editActionsObj.add[].actionObjArr[].action The name of a Seismic action to dispatch on click
* - @Param {number} editActionsObj.add[].actionObjArr[].index The index at which to insert the action. If null or falsy, the action will be added to the end of the array.
* @Param {Object[]} editActionsObj.remove Array of objects representing the group and its respective actions to be removed.
* - @Param {string} editActionsObj.remove[].groupKey The key of the group to update. If null or falsy, the actions will be removed from all groups.
* - @Param {string[]} editActionsObj.remove[].actionIdArr The IDs of actions to be removed. If null or falsy, all the actions will be removed from the given group.
*/
//.editGroupActions(editActionsObj)
/**
* Hides declarative actions that require record selection
*/
//.hideDAsRequiringSelection()
// do not remove
.transform();
// You can make further changes to columnDefinitions and rowDefinitions objects here
// to customize the experience of the list
// TODO: add public urls for docs for rowDefinitions and columnDefinitions
// Full rowDefinitions docs - <public url>/now-list/typeSchemas/rowDefinitions/rowDefinitionsDocs.md
// Full columnDefinitions docs - <public url>/now-list/typeSchemas/columnDefinitions/columnDefinitionsDocs.md
// eg. loop thru columns and set column properties
// listModel.columnDefinitions.columns.forEach(function(column) {
// // add end icon to short description column
// if(column.key === 'short_description') {
// column.icons = {
// endIcons: [{ value: 'camera-fill', color: 'positive', label: 'aria label' }]
// };
// }
// // and starting icon to state column
// if(column.key === 'state') {
// column.icons = {
// startIcons: [{ value: 'eye-outline', color: 'critical', label: 'aria label' }]
// };
// }
// // add custom cell action in priority column
// if(column.key === 'priority') {
// if(!column.cellActions) column.cellActions = [];
// column.cellActions.push({
// id: 'custom_action',
// label: 'Do Cell Action',
// action: 'CUSTOM_COMPONENT#CUSTOM_CELL_CLICK',
// });
// }
// });
// eg. loop thru rows and make changes to row based properties
// listModel.rowDefinitions.rows.forEach(function(row, index) {
// // disable row selection on every other row
// if(index % 2 === 0) {
// row.selectionDisabled = true;
// }
// });
listModel.rowDefinitions.rows.forEach(function(row) {
if (row.cells.hasOwnProperty("u_highlight") && row.cells.u_highlight.value == true) {
row.cells.short_description.highlightedValue = {
"color": "critical",
"variant": "tertiary",
"field": "short_description",
"value": row.cells.short_description.value,
"status": "critical",
"showIcon": true,
"iconName": "marker-fill"
}
}
});
return listModel;
}
// do not remove
catch (error) {
return {
failed: true,
error: error.message
};
}
})(transformBuilder, transformScriptArgs);
2 Comments
