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 |
|
Overview |
Overview |
The Declarative Action framework is used to integrate Core UI behaviors such as client actions or server scripts into Workspace forms, fields, lists, and related lists without the need to edit code. Declarative actions enable users to associate defined actions to their workspace and can be associated to the following action models:
- Field (Decorators)
- Form (Action Bar)
- List (Header)
- Related List
Declarative actions are similar to platform UI Actions to add buttons on a form, etc. UI Actions are only exposed in the Action Bar component in Workspace, etc. experiences so the use cases are limited. Declarative Actions can be used in the Action Bar component on a record, related lists, lists, etc. without having to modify the page in UI Builder itself.
By using Declarative Actions and not adding buttons to a page in UI Builder, you are making your upgrade experience better as Declarative Actions do not customize an OOTB UI Builder page. Instead, by creating Declarative Actions you are creating the necessary records needed in your own app scope.
This article is written from the context of using Configurable Workspace and not Agent Workspace, but some information may apply to Agent Workspace. This article walk through a simple use case of adding an Edit action to a Related List, and will serve as a resource document for various attributes related to Declarative Actions.
Action Models |
As mentioned in the overview there are different models for declarative actions. Some of the action models are used for both Agent Workspace and Configurable Workspace.
Form (Action Bar)
Module: Now Experience Framework > Actions and Events > Action Bar Declarative Actions
These are declarative actions specific to an Action Bar component. When creating a declarative action via this module, it will automatically be given the Action Model of Form, and inherit the Form Action Model fields. The Action Bar component is in the Record page template, so if you're wanting to add Declarative actions to the record and have them appear on the form, this is the module you would use.
As mentioned in the overview, you can utilize UI Actions on the form when using an Action Bar component as well. Since the Action Bar component is in the Record page template, you can add UI Actions to that form view by configuring the Workspace options in the UI Action form.
When adding Form declarative actions you will need to create a UX Form Action (sys_ux_form_action) record. When using UI Actions in Workspaces, you can do this automatically by setting Format for Configurable Workspace to true or manually by creating the UX Form Action record.
Note: The previous methods of adding Contextual Sidebar Components or Related Items in Agent Workspace do not apply to Configurable Workspaces since they utilize the UI Component Action Type.
Field (Decorators)
Module: Workspace Experience > Actions & Components > Field Decorators
Used in conjunction with Reference fields on forms to take an action. The Rome documentation applies both to Agent Workspace and Configurable Workspaces. Will populate the Action Model as Field and records inherit the Field Action model fields.
List (Header)
Module:Workspace Experience > Actions & Components > List Actions
Used to configure Declarative Actions for a list. Will populate the Action Model as List, and records inherit the List Action Model fields.
Related List
Module:Workspace Experience > Actions & Components > Related List Actions
Used to configure Declarative Actions for a related list. The declarative action must be added to the table it is to be shown on and not the parent table, i.e. ci_task for Affected CIs versus Incident. Records inherit the Related List Action Model fields.
Tables and Action Types |
Tables
Action Types
- UXF Client Action (UIB Workspace) - Triggers events within pages created with UI Builder. Allows action buttons to hook into elements on the page such as:
-
- Data resource operations such as update a record, refresh a list, etc.
- App shell capabilities such as navigating to another page, popping up a modal, etc.
- Any event handlers built for the page.
- Server Script (UIB and Agent Workspace) - Execute a server-side script such as creating/deleting a record, re-assigning a record, adding a record, etc.
Action Assignment Fields |
The advanced view of the Action Assignment record will contain more fields depending on what the declarative action is implemented as. This section will provide an overview of the fields and which implementation they apply to.
Server Script
- Server Script - Server script to execute when the action is triggered. Same environment and variables as a UI Action's server script. The current object is exposed representing the current record.
UXF Client Action
- Payload Map - Payload to dispatch to the internal event when the action is triggered (interpolation supported).
Both
- Conditions
- Script Condition - Server condition that must be met before the action is displayed.
- Client Conditions - Model field values that must be met before the action is displayed.
- Record Conditions - Record condition that must be met before the action is displayed.
- Required Roles - Specifies the roles the user must have to view the action.
- Requires create access - Specifies the user must have create access to view the action.
- Requires read access - Specifies the user must have read access to view the action.
- Requires write access - Specifies the user must have write access to view the action.
- Requires delete access - Specifies the user must have delete access to view the action.
- Confirmation Settings
- Confirmation Required
- Confirmation Message (if Confirmation Required is true)
Create a Declarative Action |
Server Script
In the first example we'll start with a simple server script that is going to allow a user to re-open an incident from the record page. The requirements are that users can re-open incidents in the CSM Configurable Workspace, only if the incident is in a resolved state, and the user who is clicking the button has write access to the incident record. We will associate the declarative action to the Action Bar component so it shows in line with other out-of-the-box declarative actions, UI actions, etc. To create the declarative action navigate to Now Experience Framework > Actions and Events > Action Bar Declarative Actions. This module will automatically create a record with a form position of Action Bar so it is available within that component on the record page.
| The Workspace field should be left blank when creating declarative actions for Configurable Workspace, this field is only applicable to Agent/legacy workspace. |
Most of the fields discussed in the section above are going to be in the Advanced View of the form. The following will be configured:
Record Conditions: State is Resolved
Requires write access is true
Server script:
current.state = 1; //New
current.update();
action.setRedirectURL(current);
gs.addInfoMessage('Incident number ' + current.number + ' has been reopened.');
Declarative actions can be made global or specific to a workspace. For example the CSM Configurable Workspace uses the CSM/FSM Configurable Workspace Config in the UX Actions Configuration (sys_ux_action_config). In this example we'll apply the button to just the incident table within this workspace. The first step is to associate the declarative actions to the UX Actions Configuration, this can be done via the Action Configuration related list on the Action Assignment record, or on the UX Actions Configuration table.
Next, we need to add the declarative action to a layout. Since this workspace doesn't have a UX Form Action Layout (sys_ux_form_action) for incident, we'll create one and link it. Now we can create a UX Form Action Layout Item (sys_ux_form_action_layout) for the declarative action. We also need to create a UX Form Action record so we can select our declarative action in the Action field.
Navigate to the workspace and select an incident record that is in the Resolved state.
This video covers Server side List actions and how to create a List action that will display if 1 or more records are selected in a list, and runs a server script to change the contact type. The video uses Agent Workspace but the action set up and usage works for both Agent Workspace and Configurable Workspace.
UXF Client Action
UXF Client Actions allow users to trigger a page-level event in UI Builder pages. UXF Client Allows action buttons to hook into elements on the page such as:
- Data resource operations such as update a record, refresh a list, etc.
- App shell capabilities such as navigating to another page, popping up a modal, etc.
- Any event handlers built for the page.
UXF Client Actions allow for users to create re-usable buttons to trigger events rather than adding adding buttons directly on UI Builder pages for areas such as Records or Lists.
Event Handlers
Event Handlers are used but not limited to UXF Client Actions. In UI Builder, Event Handlers are the equivalent of event listeners in JavaScript. They are what happens when a corresponding event has been triggered. Event handlers can be added to a page, data resource, or declarative action within UI Builder so that actions can be triggered. See the Configure an event handler product documentation for more information on event handlers and their usage.
We will create a Declarative Action that shows in the Record Page Tabs (Related List) to open a modal window. It is important to note that the Record page template includes the RECORD#OPEN_MODAL Handled Event out of the box. When creating your own handled events, you will have to add them to the page itself, which may be creating a variant of an out-of-the-box page. Check out the existing Event Handlers on the page to see if they meet your needs before copying a page.
Example
In this example we're going to add an Add button to the Affected CIs related list on the Incident table in a custom workspace created from App Engine Studio. The Service Operations Workspace has this action added out-of-the-box and is a great resource to use if you're planning on using this workspace in your customer instances or if you want to install it in your PDI.
1. The first step is to navigate to Workspace Experience > Actions & Components > Related List Actions. As mentioned in other articles in our Center of Excellence, Agent Workspace and Configurable Workspaces do share some of the same modules for capabilities. We're going to create an Action Assignment from here that will automatically populate the Action Model as Related List by clicking New.
2. Fill out the values on the Action Assignment record, and implement it as a UXF Client Action, and since this is on a related list choose the related list table, in this case CIs Affected (task_ci) also from here we will create a new client action.
3. In order to save our Action Assignment we need to create a new Action Payload Definition (sys_declarative_action_payload_definition) for the Specify client action field. It's very important to make the Key field unique here from other records, as we'll be using this key later on in our mapping.
In the payload field add the following:
{
"label": "Add",
"userGivenTable": "cmdb_ci",
"table": "{{table}}",
"parentRecordSysId": "{{parentRecordSysId}}",
"parentFieldName": "task",
"referencedFieldName": "ci_item",
"extensionPoint": "DEFAULT",
"view": "Default",
"columns": "",
"type": "m2m",
"hideSelectAll": false,
"relatedListName": "{{relatedListName}}"
}
For clarity, this payload is what the Multi-Record Associator component uses. If you've been through setting this up in Agent Workspace then you're familiar with selecting that component when using UI Component, and it is still available for use in Configurable Workspaces, we just configure it differently now. I'll show where as we get to that step. Ensure your new Action Payload Definition is now in the Specify client action field, and save your Action Assignment record.
4. Before moving onto configuring our payload mapping, we'll want to make sure the button shows on our workspace. Since this is a related list action and not a form action, we don't need to create a UX Form Action record, or add it to UX Action Form Layouts, etc. but if you were creating an action to show on the form you would need to do those additional steps.
5. At this point the Declarative Action shows but clicking it produces no results. We have to link our Declarative Action to an event on the page via a UX Add-on Event Mapping (sys_ux_addon_event_mapping) record. This record is basically what maps the Action Payload Definition of the Declarative Action to a Handled Event on the page, and defines how the payload is mapped. The fields we need to fill out are as follows:
Event Mapping Name: Give this an easily identifiable name.
Source element ID: The component on the record page we're linking this to, since we're using a Related List action we're going to use the record_page_tabs_1 component. You can find this in UI Builder if you're not sure.
Source Declarative Action: The action we just created in Step 1.
Parent Macroponent: This is the record page of your workspace. You'll need to search for this by sys_id. You can find that by going into UI Builder, navigating to the Record Page, clicking Menu > Open Page Definition (sys_ux_macroponent) and copying the sys_id from there. Then use the filter in the reference pop-up to filter by sys_id.
Target Event: For this we're going to re-use the OOTB RECORD#OPEN_MODAL event handler since it's available to use. If we were mapping this to a custom or new event handler, we would need to create a copy of the Record page (owning customizations, skipping updates) to do this.
Target Payload Mapping: This is where we map the payload from the Action Payload Definition, and we're defining that we want to use the Multi Record Associator component in the modal, as defined by "mra", and mapping our payload fields to the component. Enter this JSON in the field:
{
"type": "MAP_CONTAINER",
"container": {
"route": {
"type": "JSON_LITERAL",
"value": "mra"
},
"size": {
"type": "JSON_LITERAL",
"value": "lg"
},
"fields": {
"type": "MAP_CONTAINER",
"container": {
"label": {
"type": "EVENT_PAYLOAD_BINDING",
"binding": {
"address": ["label"]
}
},
"userGivenTable": {
"type": "EVENT_PAYLOAD_BINDING",
"binding": {
"address": ["userGivenTable"]
}
},
"table": {
"type": "EVENT_PAYLOAD_BINDING",
"binding": {
"address": ["table"]
}
},
"parentRecordSysId": {
"type": "EVENT_PAYLOAD_BINDING",
"binding": {
"address": ["parentRecordSysId"]
}
},
"parentFieldName": {
"type": "EVENT_PAYLOAD_BINDING",
"binding": {
"address": ["parentFieldName"]
}
},
"referencedFieldName": {
"type": "EVENT_PAYLOAD_BINDING",
"binding": {
"address": ["referencedFieldName"]
}
},
"extensionPoint": {
"type": "EVENT_PAYLOAD_BINDING",
"binding": {
"address": ["extensionPoint"]
}
},
"view": {
"type": "EVENT_PAYLOAD_BINDING",
"binding": {
"address": ["view"]
}
},
"columns": {
"type": "EVENT_PAYLOAD_BINDING",
"binding": {
"address": ["columns"]
}
},
"type": {
"type": "EVENT_PAYLOAD_BINDING",
"binding": {
"address": ["type"]
}
},
"hideSelectAll": {
"type": "EVENT_PAYLOAD_BINDING",
"binding": {
"address": ["hideSelectAll"]
}
},
"relatedListName": {
"type": "EVENT_PAYLOAD_BINDING",
"binding": {
"address": ["relatedListName"]
}
}
}
},
"params": {
"type": "JSON_LITERAL",
"value": {}
}
}
}
6. Save the record and head over to your Workspace. Under the Affected CI tab for Incident or however you're using this related list, you'll see your Add button. Upon clicking the button, what you're doing is triggering the handled event RECORD#OPEN_MODAL which calls a Client Script on the Record page to open a viewport modal window. Within the viewport modal window, we're showing the Multi-Record Associator component and passing the payload values to show the records we want for selection. This all works auto-magically because we're re-using some OOTb elements in our Record page such as the handled event, client script, and pre-configured modals on the page.
To round this out we can add a Remove declarative action that uses a Server Script and allows for selecting multiple items.
1. Navigate to Workspace Experience > Actions & Components > Related List Actions and create a new record. Instead of choosing UXF Client Action we'll use Server Script in the Implemented As field.
2. There are a couple of things to note with setting this Action Assignment up, first we'll want to use ({{count}}) after our label in the Action label to show how many records we are selecting, for example: Remove ({{count}}). Also we need to ensure that Record Selection Required is true, and the table is CIs Affected (task_ci). Since Record selection Required is true, the button will not be active until a user selects a record.
Using the Advanced View we can set the server script as follows:
current.deleteRecord();
GlideList API |
The GlideList API is a new feature for Workspace experience lists as of the San Diego release. A custom button can be added to the List page on a Workspace experience that returns the list information in the current view. The Use the client GlideList API in the Workspace Experience UI product documentation walks through the steps in Agent Workspace, but the steps are applicable to Configurable Workspaces as well. In the example in the product documentation, there is a filter of 'active=true' applied to the declarative action. Once the button is clicked, the filter is applied and the list is refreshed. The API documentation has other methods that can be called as well.
I have tried to create action assignment for related list in CSM Workspace:
when i click on it I am getting the below error:
Hello @Ashley Snyder ,
I have a requirement of popup window in workspace to come up when a caller is selected on the incident form the CI's related to the caller is to be visible in the popup.
This same functionality is working in normal view with help of client script but not in workspace.
Below is the client script working in normal view -
Client script -
@simoneserra9483 Just play around with the conditions tab and it will be displayed when the condtions are met.
I discovered this article from the following YouTube video:
Sign in Creating a UXF Client Declarative Action in ServiceNow Service Operations Workspace (Add but...
Like many others, I struggled with getting the modal to appear after clicking the button. However, I was able to get the modal to appear after adopting a slightly different configuration as seen here:
Add Related list button on Workspace
In summary, when creating the "UX Add-on Event Mapping" record, set the following fields instead:
- Source Component = List - Related
- Controller = UI Controller Record Page
