Leveraging Now Experience UI Components
With the Orlando release of ServiceNow, it's now possible to create components within Agent Workspace. It seems that per the documentation these components can be used in 3 places:
- Agent Workspace Modals
- Agent Workspace Landing Pages via UI Builder
- Agent Workspace Record views
Though with number 3 the documentation doesn't specifically go into much detail about using components within record views. It specifically says, "You can add custom or standard components to the component area in the Workspace record view." I wasn't able to find a way to create a record view component. I assume this will come in a later release but for the purpose of this guide we are going to use a Modal.
Recently I ran into an issue with leveraging Dot-Walked journal fields (comments & work notes) on a Catalog task from within Agent Workspace. ServiceNow Support stated this is a known issue with no workaround currently. That left me needing to find an elegant solution to the problem. This was the perfect opportunity to dive into the new UI components released in Orlando.
Create a UI Action & Register a Scripting Modal
Follow the documentation to create a new registered scripting modal, with a few items to note. We will be leveraging the component for the "Activity stream".
- When creating the scripting modal, use the "now-activity-stream-compose-connected" (instead of the "sn-workspace-header" as listed in the documentation) component for now. We will come back and update it.
- When creating the UI action, be sure to check off "Client" to make it a client side UI action.
At this point, if you were to click the UI action, nothing would happen. If you notice within the Workspace Client Script, some additional parameters are passed to the component in order to make it work. The only issue is, what parameters are required by the "now-activity-stream-compose-connected" component?
params: {
primaryValue: 'THIS IS A PRIMARY VALUE',
secondaryItems:{}
}
Locating the Component Attributes
- Navigate to the "now-activity-stream-compose-connected" UX component defintion page. You should see a related list of "Component Attributes":
These are exactly what we need to render our component and are actually provided in a handy format. Navigate back to your UI action and update them based on your needs, in my case I will hard code them for now.
params: {
table: 'sc_req_item',
isNewRecord: false,
sysId: '04e276944f131300ef21b4a18110c7b4',
componentId: 'cid1',
}
I was feeling pretty good about this, although not documented anywhere, it actually wasn't too hard to find. I tested my UI action... and I got a blank Modal! What gives?!
Reverse Engineering a NOW UI Component
Back on the "UX Component definition" I noticed the "Source Script" field, when I navigated to it, I could see a script link of some minified JavaScript. When I opened it, it wasn't much use even when I unminified it...I poked around in hopes of finding more information, but it was not that helpful. As I was poking around, I noticed some references to a .min.js.map files. Typically source maps are helpful for debugging and returning useful errors to developers. Surely - there must be a way to use the source map to my advantage here.
After a bit of Googling, I was able to find a GitHub Project "maximize" that sounded promising. Even more promising was a web based version of maximize so I didn't need to install anything. SrcBrowse.com. This website became my friend very quickly.
- Navigate to your ServiceNow instance > UX Component definition (from your scripting modal) > Jump to the Source Script record (sysuxlibsourcescript) then click the source script link. This will show you the minified JS.
- Append .map to the end of your URL (.min.js.map), depending on your browser settings, this should download a file.
- Head back to our handy source map browser > upload the .map file, then either download the .zip file, or view in browser.
At this point, we have what we need. After looking around within the files, I think I found what was missing within the nowActivityComboElement.js. ServiceNow actually has some good documentation inline within the code. See below:
/**
* Id for the component.
* @type {string}
*/
componentId,
/**
* Table name of the record that we want to display the activity stream for.
* @type {string}
*/
table,
/**
* Unique identifier for the record.
* @type {string}
*/
sysId,
/**
* Object containing journal fields available. For example:
*
* ```
* {
* "comments": {
* name : "comments",
* label : "Additional comments (Customer Visible)",
* sys_readonly: false,
* readonly : false,
* visible: true,
* type: 'journal_input',
* maxLength: 1000
* },
* "work_notes": {
* name : "work_notes",
* label : "Work Notes",
* sys_readonly: false,
* readonly : false,
* visible: true,
* type: 'journal_input',
* maxLength: 2000
* }
* }
*```
*
* @type {object}
*/
Making the Component Work
With the additional parameters defined, I though that maybe the missing piece was the "fields" object as defined above. Head back into your UI action and update the workspace client script code with the additional fields object param:
params: {
table: 'sc_req_item',
isNewRecord: false,
sysId: '04e276944f131300ef21b4a18110c7b4',
componentId: 'cid1',
fields: {
"comments": {
name: "comments",
label: "Additional comments (Customer Visible)",
sys_readonly: false,
readonly: false,
visible: true,
type: 'journal_input',
maxLength: 1000
},
"work_notes": {
name: "work_notes",
label: "Work Notes",
sys_readonly: false,
readonly: false,
visible: true,
type: 'journal_input',
maxLength: 2000
}
}
}
At this point our UI action should be functional, with one issue. The modal only shows the "Compose Section".
I was really looking to include the entire Compose and Activity sections in the popup. So what happened? Did we choose the wrong component? Back in our Registered Scripting Modal, the only other "tag" containing activity is "now-activity-stream-connected", perhaps this is the correct component.
This time if I test my UI action, I only have the Activity stream and not the Compose section:
It seems like this "combo" component that includes both isn't included as a UX component definition.
Creating a UX Component Definition
- Navigate back to the "now-activity-stream-compose-connected" UX Component Definition, it will show as private and non-editable. Choose the Hamburger Menu (or right click) and Choose Insert & Stay.
- Change the "Tag" field to "now-activity-combo" (this was found in our zip file).
- Update your Registered Scripting Modal to leverage this new component:
Component that combines `now-activity-stream-connected` and now-activity-stream-compose-connected`.
* Basic usage:
*
* ```
* <now-activity-combo
* component-id="cid1"
* table="incident"
* sysId="85071a1347c12200e0ef563dbb9a71c1"
* />
We are now leveraging the component from the source files that we found.
A few notes
- This was done with an Orlando Instance.
- This is likely NOT supported by ServiceNow. Please use carefully!
- ServiceNow may add this "now-activity-combo" component in the future and this workaround may not be needed, or they may fix the bug in Workspace so you can dot-walk to journal fields.
Wrap Up
I hope this was a helpful deep dive into the new UI framework that ServiceNow is laying the groundwork for. I am very excited to use these components and excited to build additional custom components. I hope that others are able to leverage this and perhaps use other existing components as they see fit!
Jonathan