Exercise 3: Field Decorator Declarative Action

Declarative actions add custom functionality to your Workspace forms, fields, lists, and related lists without writing custom scripts or learning APIs.

Goal

In this exercise, you'll add a field decorator declarative action. In the HR Agent Workspace, you have a requirement to add a field decorator (icon button) to the HR Service field that will pop open a modal showing the most recent 10 cases opened in that category.

There are a few ways you could solve this problem of getting more context around what people are asking related to a specific service, and this exercise will teach you how to solve it with a declarative action.

Add Demo Data

You'll need to create a quick case for demo data.

In the platform view, go to Workspaces > HR Agent Workspace.
Click on the plus sign and create a new HR Case.
Choose Skip verification and fill out the form:
- COE: HR Case
- HR Service: General Inquiry
Click Create Case.
Create a second case.

Build the modal and event in UIB

Create a new record page variant

Open UI Builder (UIB) by going to All > UI Builder or click the icon at the top left of the UIB window to get to the UIB homepage.
Open the HR Agent Workspace experience.
Switch your scope to the Agent Workspace for HR Case Management.

When duplicating a variant you want to do it in the same scope as the original variant.
Scroll down to the Record page and, mouse over Case SRP, click the three vertical dots icon to the far right, and choose Duplicate Variant.
Name the variant Case SRP Acme copy and click Create.

Since you're duplicating the page and owning the new variant it's probably helpful to come up with some sort of naming convention to easily tell your variants apart from the ServiceNow shipped pages.
Click the Settings pill at the top of the page, change the order to 0, and click the Save button.
Switch back to the editor view and give the page some test values by clicking the table pill just under the experience name at the top of your window.
Set the table required parameter to sn_hr_core_case, let the sysId auto-fill, and choose Apply.

You'll now see some of the components appear in the middle of the page since they've got data.
Save the UI Builder page.

Now you'll add a new modal to the page that will show a list of related records.

In the content tree, mouse over modals toward the top under Overlays, choose the plus sign to the right, and choose Custom.
Rename the modal by clicking the (i) icon next to Custom 1 in the right-hand panel to the following:
- Component label: Related cases modal
- Component ID: related_cases_modal
Click Apply.
Collapse all the modals in the content tree on the left except for your new modal, and click +Add component under the Heading 1 section of your modal.
Add a Stylized text component.
Remove the preset using the preset dropdown on the config panel and clicking Remove in the popup.
Change the Text property to data binding.
Choose the Formulas tab and the CONCAT formula.
Double-click into value1 and type "Related records for " (with the quotes)
Now click into the second value, click into the Data types tab, and choose Data resource > record > form > fields > hr_service > displayValue, and choose Apply.
In the Body 2 section in the content tree, choose + Add component and add a List - Simple.
Choose None for the preset to configure it manually.
Configure the component's properties in the Configure panel as follows:
- Table: HR Case
- Edit fixed filter: <data binding> HR service | is | Data resource > record > form > fields > hr_service > value
- Columns: <add one at a time>
  - Number
  - Subject person
  - Description
- Maximum rows: 10
Now add a Button component to the modal's footer.
Remove the preset.
Change the button's label to Close.
Click into the Styles tab and give the button a margin of L.
Click into the Events tab and choose Add Event Handler.
Choose Open or close modal dialog.
Choose the Related cases modal for the Modal and click Add.
Save the UI Builder page.

Add a handled event to the page

In this section, you'll create a handled page event. This will alow the declarative action to tie into it and take some action based on what the event does. Handled events can be used for any number of things including if you need to call the same series of event handlers more than once, you could do that from the handled event and define it once.

Click on Body in the content tree.
Click into the Events tab on the right.
Scroll all the way down to the Handled events section at the very bottom of the Events tab and choose +Add.
Set the Event label to HR Service Related Records and click Add.
Scroll back up in the Events tab and choose the + Add event mapping button.
Choose the HR Service Related Records event you just created.
Choose the Open or close modal dialog event, set the following, and click Add.
- Open modal dialog: true
- Modal: Related cases modal
Save the page.

Create the declarative action

Now you'll use the declarative actions framework to create an action that will show up on the HR Service field as an icon button that will trigger the event you just created.

In your Classic environment browser tab, go to All > Now Experience Framework > Declarative Actions > Create New Action.
Choose Field decorator on the page that comes up and fill out the form as follows:
- Action label: HR Service Related Records
- Action name: hr_service_related_records
- Implemented as: UXF Client Action
- Table: HR Case [sn_hr_core_case]

Specify client action: <click the magnifying glass and choose **New** to create a new client action>

Key: HR_SERVICE_ACTION
Label: HR Service Related Records
Applicable to: UXF, Field

Payload:

{
  "referenceField": "{{fieldName}}",
  "referenceKey": "{{referenceKey}}",
  "referenceTable": "{{referenceTable}}",
  "fieldLabel": "{{label}}",
  "parentTable": "{{tableName}}",
  "parentSysId": "{{recordSysId}}",
  "encodedRecord": "{{encodedRecord}}",
  "serializedChanges": "{{serializedChanges}}",
  "fieldType": "{{fieldType}}",
  "value": "{{value}}",
  "displayValue": "{{displayValue}}",
  "dependentField" : "{{dependentField}}",
  "dependentValue": "{{dependentValue}}"
}

Click Submit.
Set the following fields:
- Decorator applies to: Specific field
- Field name: HR service
- Icon: related-list-fill
- Tooltip: Other cases for this HR Service
- Description: Shows the other cases for this HR Service
Right-click on the header and choose Save.
Choose Advanced view under Related Links below the form fields.
When the form reloads click on the Conditions tab.
Set the Record Conditions to: HR Service | is not empty
Right-click on the header and Save the form.
Scroll down to and click on the UX Add-on Event Mappings related list.

Choose New and fill out the form as follows:

Event mapping name: HR Service Related Records
Source element ID: form
Parent Macroponent: Case SRP Acme copy
Target Event: HR Service Related Records

Target Payload Mapping:

{
    "container": {
        "fields": {
            "container": {
                "encodedRecord": {
                    "binding": {
                        "address": [
                            "encodedRecord"
                        ]
                    },
                    "type": "EVENT_PAYLOAD_BINDING"
                },
                "label": {
                    "binding": {
                        "address": [
                            "fieldLabel"
                        ]
                    },
                    "type": "EVENT_PAYLOAD_BINDING"
                },
                "referenceField": {
                    "binding": {
                        "address": [
                            "referenceField"
                        ]
                    },
                    "type": "EVENT_PAYLOAD_BINDING"
                },
                "referenceKey": {
                    "binding": {
                        "address": [
                            "referenceKey"
                        ]
                    },
                    "type": "EVENT_PAYLOAD_BINDING"
                },
                "serializedChanges": {
                    "binding": {
                        "address": [
                            "serializedChanges"
                        ]
                    },
                    "type": "EVENT_PAYLOAD_BINDING"
                },
                "size": {
                    "type": "JSON_LITERAL",
                    "value": "md"
                },
                "sysId": {
                    "binding": {
                        "address": [
                            "parentSysId"
                        ]
                    },
                    "type": "EVENT_PAYLOAD_BINDING"
                },
                "table": {
                    "binding": {
                        "address": [
                            "parentTable"
                        ]
                    },
                    "type": "EVENT_PAYLOAD_BINDING"
                }
            },
            "type": "MAP_CONTAINER"
        },
        "params": {
            "type": "JSON_LITERAL",
            "value": {}
        },
        "route": {
            "type": "JSON_LITERAL",
            "value": "modal_ref_lookup"
        },
        "size": {
            "type": "JSON_LITERAL",
            "value": "lg"
        }
    },
    "type": "MAP_CONTAINER"
}

Choose Submit.
Now to test this open a case in the HR Agent Workspace and notice the new icon in the HR service field next to the preview icon. When you click it the modal should appear, but sometimes declarative actions have caching issues. You may need to clear the instance cache by appending cache.do to the url after .service-now.com/, clearing browser cache, and closing and reopening windows.

Exercise 3: Field Decorator Declarative Action

Goal​

Add Demo Data​

Build the modal and event in UIB

Create a new record page variant​

Add a modal​

Add a handled event to the page​

Create the declarative action​

Goal

Add Demo Data

Create a new record page variant

Add a modal

Add a handled event to the page

Create the declarative action