Setting up your environment for Now Experience and UI Builder custom component development
Developing custom Now Experience components requires more tooling than conventional ServiceNow development. You'll need to install some software locally onto your Mac, PC or linux computer. The official docs might not get you all the way. This is a step by step guide starting from scratch and ending by deploying your first custom Next component to your instance.
- A Service-Now instance (learn how to request one here)
- Admin privileges on your machine (you'll need to install software)
Step 1: Install VS Code
You'll need an IDE (Integrated Development Environment). Microsoft maintains a fantastic and popular open source IDE called VS Code. I recommend downloading and installing it from here.
VS Code also comes with a convenient terminal window. For any of the subsequent instructions where you need to type in a command you can do it from VS Code terminal. If it's not open already you can go on the top menu Terminal > New Terminal to open a new terminal window.
Step 2: Install NVM
To run the tooling we need to develop custom Next components, we need to install and use Node.js v14. As of this writing the most recent version of Node is 18.14. That is to say we need to use an older version of Node.js to make things work.
Luckily there is a tool that can help us install an older version of Node.js as well as switching between older and newer versions. Meet Node Version Manager (NVM). Below you'll find platform-specific instructions on how to install and use NVM.
On a Mac you'll need to install Homebrew (instructions here) and type the following command in your terminal:
brew install nvm
Add nvm to your shell profile:
source $(brew --prefix nvm)/nvm.sh
Install Node v14:
nvm install 14
Use the installed version:
nvm use 14
Confirm it's working:
node --version # returns v14.21.3
Step 3. Download and install the ServiceNow CLI.
CLI stands for Command Line Interface and this is simply a tool that let's you interface with a ServiceNow instance through the command line. The official docs tell you to install it from the ServiceNow Store, but somehow this was giving me issues. I recommend installing it through npm by typing this into your terminal:
npm i -g @servicenow/cli
Step 4. Install the
ui-component extension using the ServiceNow CLI
This is an extension for the ServiceNow CLI (official docs) and it allows us to create new UI Components with certain presets as well as deploying them to our ServiceNow instance. After downloading and installing the ServiceNow CLI (SNC for short) you can open a terminal window and type in the following:
snc extension add --name ui-component
This should download and install the
ui-component extension. Once it's finished you can type the following command to confirm it's installed and functioning correctly.
snc ui-component --help
Step 5: Install the CLI Metadata application on your instance1. Visit the ServiceNow Store and search for CLI Metadata. Then enable it for your instances.
2. On your instance navigate to System Definitions > Plugins. You'll be redirected to an overview of All Applications.
3. Here search for CLI Metadata. Select it and install it.
Step 6: Set up a named connection profile
The official docs guide you towards creating a default connection profile, but as of this writing this doesn't seem to work. An effective workaround is setting up a named connection profile as follows:
In your command-line tool enter the following to set up a default connection profile:
You'll be prompted for your instance URL and login details.
For testing purposes you can pick Login Method: Basic and Default Output Format: JSON.
The profile setup is saved to a config file in your home directory:
Step 7: Set up the project
To scaffold a project do the following:
This scaffolds a project and creates a list of dependencies. To install those dependencies type the following in the terminal:
Step 8: (Optional) fix issues
In my case running
npm install threw various errors. Run the following commands to see if they get rid of any errors you might be experiencing.
Install windows build tools to make sure you've got the required Python 2.7
Older versions of OSX will have Python 2.7 installed. Newer versions will need to install it. This is how you can accomplish that ^.
If you're running an M1 or M2 Mac then
brew will probably not work for you. You need to follow some additional steps. Then prefix your commands like this:
node-gyp is a tool that enables the compilation of native add-on modules for Node in multiple platforms. Somewhere in the dependency tree it appears to be included, so we need to make sure it's installed 3. Run this inside your project directory.
npm install -g node-gyp
Node-SASS seems to be a deprecated version of SASS used by the Now Experience framework. Make sure you're running Node 14 and install the legacy version of Node-SASS 1. Run in this inside your project directory.
npm install firstname.lastname@example.org
Step 9: Run the component locally
Now we're ready to run the component locally. Here's a link to the official docs.
snc ui-component develop
Step 10: Deploy the component to your instance
Once you're ready to deploy your component you can do so as follows:
snc ui-component deploy
Then navigate to your instance, open UI Builder, open the Component selection dialog and your component should be among those listed.
- Walkthrough of some example components from ServiceNow
- CLI Troubleshooting Thread on SN Forums