Custom Components At A High Level

An Introduction To Custom Components

As many of you have already seen, the SeviceNow’s new UI Builder has hit the scene and has already started to see some adoption. It truly is an amazing and powerful low code/no code tool that has enabled developers to easily create beautiful and interesting pages. Although, in my humble opinion, using low code/no code options, while being fantastic for getting things up and running quickly, can sometimes be difficult to really unlock the true power of a system. While ServiceNow has provided many highly configurable components ready to deploy (ServiceNow's components link), I’m sure you all are aware that sometimes a template is not always enough.

As you get deeper into UI Builder and really explore the tech, some limitations start to apply. ServiceNow has done a truly amazing job at creating a diverse set of components to use, but no one can account for every possible configuration and sooner or later you will run into some requirements that are not able to be done with the current component library. A possibility can be you even have to handle a requirement that doesn’t even have anything close to similar in the library because it is so unique to your specific needs. While limitations are always present in no code/low code solutions, there is a way to have the best of both worlds, custom components!

Custom components are ways to use ServiceNow’s UXF to create any components that your heart desires. No guardrails here, you get a fully featured front end framework designed to work directly with your ServiceNow instance. This allows you the complete freedom to create any custom solution from scratch, or to use NPM (node package manager) to download any of ServiceNow’s pre-made components to serve as a base and then use them as components within your personal components (using components from npm). You really do have the freedom to start from as blank of a canvas as you want!

Custom components are ServiceNow's way of not restricting it’s developers from building truly unique and interesting pages that are unique to you and your organization's needs. With UXF anyone with just a little front end web development experience can produce beautiful and responsive components that suit any need you may have. We hope you are as excited about the possibilities as we are!

We’ll give a high level overview of how custom components work. After that, there will be a CLI setup guide.

How Custom Components Work; An Overview

Custom components are created much like any front end component, but using ServiceNow’s custom framework known as UXF. One of the fantastic benefits of using UXF is that by using ServiceNow's CLI (command line interface) you can easily run your application locally on your machine connected to your ServiceNow instance and use the tables, REST APIs and records contained within. A largely integral feature of this is ServiceNow’s CLI which, once installed, allows you to use your computer's terminal to easily interact with ServiceNow instances as well as create, develop and deploy UXF custom components. 

Working with UXF is actually really easy if you are at all familiar with traditional front end web development, and honestly not too bad even if you aren’t. By creating a folder on your computer, you can then use the CLI to set up your directory to have a blank project in it (more on setting up the CLI and more advanced commands in the next section). After creating that folder, you must then install the dependencies (required files that are needed). Good news, in creating your project, ServiceNow automatically sets everything up for you so all you have to do is type "npm install" and the rest is taken care of. 

Now that you have your folder prepared we are ready to take a closer look at exactly what we are working with. Looking closely we have our imports at the top.

As you can see we currently have three imports. These are the createCustomElement function which allows us to create the now experience components, the snabbdom renderer which is a renderer that we use inside of our components and your style sheet which allows you to apply css styles to your component (and bonus, it uses scss by default which opens up a lot of cool options and organizational advantages). While we can add more as desired, these are what we start with and represent a minimum requirement for components.

Below that is our view function.

This represents the visual elements of our component. UXF utilizes a virtual DOM to render our HTML instead of utilizing an HTML file like you might be familiar with using Service Portal. This might seem intimidating at first glance but it’s actually really powerful and easy to use when you get used to it. This works by returning HTML that is contained within a single tag. This might take some getting used to, but in return it offers great rewards to those who are able to master it. In addition to being easily modifiable using some advanced tricks, it also offers something called selective rendering. This powerful technology greatly improves the performance of your html by only re-rendering what has changed rather than the whole thing. If you change a list representing the latest 5 incidents you shouldn’t also need to re-render all your buttons, headers and other elements now should you? Since rendering HTML is computationally expensive, by selectively re-rendering only what needs to be changed you can save considerable computational power rendering components that can instead be used for other tasks making your components that much faster!

An important thing to keep in mind for the view is that all must be contained within a single tag. While later on we can do more complicated things, to keep this simple now we’ll just use a <div/> tag. All we place in the view and render must be contained within this tag. For example if we want a header and a paragraph we can simply place those tags within the div like so and it will render

And that will render to the screen like this

While that is fine and dandy for rending static views, what about if we want to get a little more… dynamic?  By using escapes, we can utilize javascript at any time allowing us to use variables within our views or even logic.  

And this is our new screen

We are also not restricted to using logic just in the return statement but can use it in the view as well potentially changing the entire view displayed. In addition to just conditionals and logic we can also get our variables from state (more on that later, state is something that will need an entire article just to do it justice!) or run them through algorithms to generate. The possibilities are way too many to really delve into in such a surface level article but keep your eye out on this space for more view tips and tricks to come!

Below our view we have our actual component that we are creating.

As you can see there are only three things we have currently being used. The renderer (don’t worry about this for now, it just means you are using snabbdom as your renderer). The view, which takes in the view function you just created and serves as the visual portion of your component. Finally, you have the stylesheet that is being used in your component that is taking in the styles import from up top and feeding it into the component. That is just our basic setup though. I always find it useful to at least add properties and action handlers to allow the use of those more basic things.

Properties should be familiar with those of you who have react experience as they are very similar to react props. These allow you to set data in higher level components which is then passed into lower level components. At the highest level component it can even get props passed in by UI Builder. Here is a quick sample prop that takes a name and defaults to “user”

Action Handlers are how you handle events. Anything like a button press or a text entry can dispatch an event. By placing an action handler in a component we can then trigger a change. Here is an example of an event that changes the user's name to bob. Don’t worry if some of these concepts are a little much right now, we’ll go over them in more detail in a later blog post.

By dispatching this event from another component we can have this component change its name, just one of the ways we can transfer data between components.

These are just some of the things we can configure our component with, from transformState which can create calculated states before we render our view and many others.

There really are way too many things going on with components to cover in a single article, but I hope I have offered a glimpse into how custom now experience components work. And hopefully this broad strokes overview of the architecture of a component has whetted your appetite as this is truly an amazing framework that allows you to truly unlock the full potential of the new Now Experience!

CLI Setup Guide

In the following steps we will walk you through how to get your environment set up and the ServiceNow CLI installed. ** We want to make it clear that this guide is a work in progress. ** We use this for our new internal teammates to get ready to develop so we will continue to update this as we learn more. We have found many oddities through this process with various teammates running into unique issues. If you work through this and have feedback, please share it with us.

Step 1 - Create Empty Folder

We won’t use this right away, but go ahead and create an empty folder for your project locally on your computer. It doesn’t matter what you name this and really shouldn’t matter where you put it. I put it in my Documents folder.

Step 2 - Install Visual Studio Code

You don’t necessarily need to use Visual Studio Code as your dev environment, but that is what we use internally and will reference throughout. If you don’t already have this installed, you can download and install here:

https://code.visualstudio.com/download

Step 3 - OPTIONAL - Install NVM

NVM, or Node Version Manager, allows you to quickly install and use different versions of Node. This is not required, but will likely make your life easier down the road as the ServiceNow CLI continues to mature.

Here is an article that outlines how to install NVM via Homebrew:

https://tecadmin.net/install-nvm-macos-with-homebrew/

Step 4 - Install Node.js and NPM

If you don’t already have Node.js and NPM installed, you will need to have these. There are various methods to install these. Below are 3 separate routes to install. An important note is that the latest versions of Node don’t seem to work currently with the ServiceNow CLI. We have found v14 of Node to work well.

Install via NVM

If you installed NVM, all you have to do is run the following command in your terminal:

Install via Homebrew

Many of us here use Homebrew (if you use Mac or Linux) to install Node via the terminal. Here are links to Homebrew and instructions on how to install Node via Homebrew:

https://brew.sh/

https://changelog.com/posts/install-node-js-with-homebrew-on-os-x

Manually Install

You can also install via file download here:

https://nodejs.org/download/release/v14.18.2/

To confirm that you have installed Node, enter the following command into the terminal:

To confirm you have installed NPM, enter the following command into the terminal:

Step 5 - Install ServiceNow CLI

The ServiceNow CLI is what will actually allow you to create and test custom components. Currently the only way to get the CLI is by downloading it from the ServiceNow Store. You will need to use your ServiceNow SSO login credentials (aka the same that you would use when logging into the ServiceNow Community, Developer site, etc.).

Once you have logged into the Store, navigate to the following link for the CLI and download:

https://store.servicenow.com/sn_appstore_store.do#!/store/application/9085854adbb52810122156a8dc961910/1.1.0?referer=%2Fstore%2Fsearch%3Flistingtype%3Dallintegrations%25253Bancillary_app%25253Bcertified_apps%25253Bcontent%25253Bindustry_solution%25253Boem%25253Butility%25253Btemplate%26q%3Dcli&sl=sh

When the download is complete, open the file and follow the installation instructions. Where you install this shouldn’t be an issue. Installing it in Applications should work. IMPORTANT: make sure add to PATH is checked.

To confirm that the installation was successful, run the following command in the terminal:

Step 6 - Configure SNC Profile

We need to configure our profile to allow us to access the server. To start this process, run the following command in the terminal:

That will begin a prompt to add details about the ServiceNow Instance you want to connect to. First enter the name of the ServiceNow instance you wish to use (including the https://). Example:

https://dev1991.service-now.com/

Next, it will prompt you to choose your authentication method. Select basic.

Lastly, type in your ServiceNow username for that instance followed by your password.

If you made it through here with no errors, you can move to the next step.

Step 7 - Install SNC UI-Component Extensions

The CLI is configurable in that you can add things called extensions to enhance its feature. In this case we are adding an extension called ui-component which will allow us to create custom components.

Run the following command in your terminal:

This installation will take a minute, but when it is done you should be able to use the snc version and get not only a CLI version but also a version for your ui-component extension. To confirm, run the following command in your terminal:

Step 8 - Open Your Empty Folder From Step 1

In Visual Studio Code, go ahead and open the empty folder you created in Step 1.

Step 9 - Log Into ServiceNow Instance

Now that our environment is all set, we are ready to create our first component. First we need to log into our instance. Run the following command in your terminal:

snc ui-component login {your instance URL} basic {your ServiceNow username} {your ServiceNow Password}, replacing the text in the brackets with your own information.

Example:

Step 10 - Create Your Component

The next command we will run will create the shell of a custom component for you to use. Note, you will likely need to open a new terminal in Visual Studio Code in the same place where you opened your empty folder. The general format of this command is:

snc ui-component project --name {Project name that must include at least 1 ‘-’ character} --description “{your components description}”

One issue we have noticed is that sometimes we need to put 2 “ at the very end of the command. Below is an example of a command that you should run in your terminal.

You should now see files added to your previously empty folder.

Now, we need to install dependencies. UXF has quite a few libraries included so this download is over 1GB and might take awhile. To kick it off, run the following command in your terminal:

Step 11 - Run Your Component Locally

Now that you have a component, you can test it locally. Run the following command in your terminal to start your local host:

If this runs successfully, it should tell you in the output what port to use. Once you find that, you can go to a browser and enter the following into the url bar (replacing the port number with whatever port it gives you):

http://localhost:8081

Troubleshooting CLI issues

There are many common issues to get then installing the CLI. In the interest of helping the community, we are talking about how we have solved some of the basic issues that have cropped up.

First off we have had situations where it was not added to PATH despite having that box checked. You will then have to give yourself permissions to do so and manually add it to PATH. We have also had windows users when getting a “keytar error” have to install python from the windows store specifically while another user had to download specifically python 2.7. Another fixed that problem by downloading the Microsoft build tools. We have also had developers have failed ui-component installs, by removing (using snc extension remove --name ui-component and re-adding the ui-component extension they were able to fix it. Another developer had to completely uninstall and reinstall the whole CLI before it would work.

We hope our struggles provide you all with a little direction when trying to install it and good luck with your exploration of the exciting work of the Now Experience!