PROBLEM TO SOLVE
The use case was a task-based record to track the life cycle of a letter file to be sent out to some external recipient. The letter record would ultimately have a single PDF attachment dynamically generated from a template. The client didn’t like that attachment “buried” on the ‘Attachments’ side panel tab of the workspace record page. The request was to add a button in the action bar to provide easy access to preview the file. The desired user experience when clicking the button was the same as what ServiceNow does when the user accesses the file from either the ‘Attachments’ tab or the activity stream: a “Preview” window.
We couldn’t think of any way to do that using a classic UI Action. Going that route would likely mean a solution that would immediately prompt the user to download the file. They wanted the ability to preview the file in a viewer that allowed zooming, searching, rotating, and downloading. So we went looking for a solution.
SOLUTION
Declarative Action and ‘Document display’ component
As we investigated how ServiceNow was presenting the attachment to the user, we “discovered” the Document display component (wasn’t aware of it until we went looking). It was quickly obvious that ServiceNow was leveraging that component for previewing files, so if we could design the proper use of it, we’d have our solution. We went through some trial and error trying to determine the best approach, mostly centered around where to put the component on the page. It was to display only when the user clicked the action button, it would be refreshed and displayed each time the button was clicked, and it should overlay the entire record page. We ran into trouble when the user used the ‘X’ in the component’s UI to close the preview, then trying to click the action button to reopen. We eventually fell to a “fullscreen” modal with the Document display component on it where the visible ‘X’ button to close was the modal’s close, not the component’s. This worked great! Here’s a breakdown of that solution:
Create the ‘Preview Letter’ Action Button…
UX Event (sys_ux_event)
The event to be fired by the declarative action.
UIB Record Page: Handled Event
Tie the event to the record page as a ‘Handled Event’.
Action Assignment (sys_declarative_action_assignment)
With the event created, now jump to the steps to get a new button in the action bar of the record page: a Declarative Action.
Go to Now Experience Framework > Declarative Actions > Create New Action, select “Form”.
Selecting “UXF Client Action” indicates how the button will work (e.g. fire UX Event).
The Specify client action is a new Action Payload Definition (described below).
Action Payload Definition (sys_declarative_action_payload_definition)
For the Action Assignment created above, this defines the action as applicable to “Form” with a specified payload. NOTE: I didn’t have a payload for my action.
UX Add-on Event Mapping (sys_ux_addon_event_mapping)
Ties the declarative action button with the page it should display on and the event it should fire.
Parent Macroponent: The UIB page the action button will appear on.
Target Event: The UX Event to fire when the action button is clicked. The event had to be tied to the macroponent as a ‘Handled event’ to be available for selection here.
Source element ID: The ID of the Action bar element that will contain the action button.
Source Declarative Action: The Action Assignment; the action’s relationship to the UX Add-On Event Mapping record is shown on a related list on the Action Assignment form, shown below.
UX Form Action (sys_ux_form_action)
Created automatically when the Action Assignment is created. Same thing occurs when you create a classic UI Action marked to show as a Workspace button. The UX Form Action table is used to bring those types of actions together so they can be organized as part of a UX Form Actions Layout (described below).
UX Form Actions Layout (sys_ux_form_action_layout)
Brings together Declarative Actions and classic UI Actions in one action bar layout for a Workspace. These UX Form Actions are linked to the layout via UX Form Action Layout Item (sys_ux_form_action_layout_item) records where you can define where each button will display, how it will be styled, and more.
Showing the “Preview Letter” Action Button
With all the setup described above, we now have a new button in the action bar, displayed amongst other classic UI Actions.
Now make the “Preview Letter” action button work…
Client State Parameters
For my use case, there were a couple of client state parameters needed to retrieve the attachment and update the Document display component to allow the user to preview the file.
- getLetterAttachmentParams: Object with attributes bound to parameters of the Data Resource (described below) that will retrieve the attachment record.
- letterFileId: Bound to the Document display component to define what attachment it will display.
Document display Component
After trying the Document display component in various locations around the record page, the layout design that matched the user experience when accessing the file from the “Attachments” side panel tab was to place the component in a “Fullscreen”-sized modal.
The Document display component is data bound to the letterFileId client state parameter that holds the sysId of the Attachment to preview. This Attachment ID is retrieved by the Data Resource described below.
Data Resource to get attachment
I setup a ‘Transform’ data resource to query the Attachment table to retrieve the PDF file to preview. I tried using the global “Look up a single record” data resource, but I could not query the Attachment table from my scoped app, so I went with the ‘Transform’ data resource. The resource fetch is triggered by the bound client state parameter which is updated in the event handler for clicking the “Preview Letter” button (described below).
Event Mapping for “Preview Letter clicked” Handled Event
When the user clicks the “Preview Letter” action button, the “Preview Letter clicked” event is fired. I added an event mapping to update the getLetterAttachmentParams client state parameter bound to the data resource to force the fetch of the attachment linked with the primary record.
Display of File Preview
The data resource’s Data Fetch Succeeded event is handled by a client script to do the following:
- Update the letterFileId client state parameter bound to the Document display component.
- Open a modal showing the Document display component to the user.
The document preview overlays the entire content area of the Workspace, example below.
Hope this was helpful!
Jamie Stroud
