Open Site Navigation

Working Through Now Experience Components

Updated: Oct 21



Overview


At this point in my blogging journey I have explored some of the basic workings of Now Experience Workspaces in the UI Builder. There's still a ton of features regarding out-of-the-box components I've yet to explore or understand, but did want to dip my toe into custom components as sooner or later the need for one will arise. I'll start with an overview of the concepts I've learning from the components course on NowLearning, and then jump into an example by following this exercise on the developer site.


I'm going to preface this post and state that this is not a complete overview of components. I barely scratch the surface, and there's a lot of great content already put out there by ServiceNow. This post is meant to be more of a learning exercise, and aggregation of helpful content.


Now Experience UI Framework


Per ServiceNow, the Now Experience UI framework is a proprietary JavaScript framework based on the web component framework.


To keep it short, per MDN documentation: Web Components is a suite of technologies allowing you to create reusable custom elements - with their functionality encapsulated away from the rest of your code - and utilize them in your web apps.


Why is this important? For one, it allows ServiceNow to build components that any customer can use, and any project/application scope within that customer's development environment can use. It also allows for customers to create components within their organization that any Now Experience can use, for example a CSM workspace can utilize a component created originally for XYZ scoped app workspace, bind the necessary data, and stylize the component as needed.


There's tons of stuff out there about web components if you want to know more, just know ServiceNow has their own version of this framework called Now Experience, or you may see some developers refer to it as Seismic.


Now Component Library


ServiceNow documents all of the components they create on the Now Component Library .I'm going to go on the assumption that if you're creating components within your customer instances, that you should also have some sort of component documentation available.


You'll see Available in UIB or UI Builder and/or Available in NPM (Node Package Manager, i.e. Now Command Line). Some may only be available in UI Builder, or NPM, or both. I'm assuming if I want to use any of the ones available in NPM, I have to run the install command, I'm not sure if I have to do this every time, or once, I'm going to assume every time, please update me in the comments if you know other wise. Make sure you install the NPM package before trying to deploy your app with the referenced code in it, or you'll see all kinds of errors. Here's a quick list (Quebec) on components you can call in NPM.



You can play around with the properties of a component in the Now Component Library and even copy your code from there, so this should make some of the heavy lifting a little easier.


Definitely check out the lesson on using Now Experience components in the linked training, as it goes through the layout of the land, and how you should use components.


UI Builder


This is the internal tool in ServiceNow to add components to workspaces or portal pages. There are two versions of UI Builder as of the Quebec release, a fully featured one for Now Experiences, and a scaled down version for Agent Workspace. You can create custom components and view them in both UI Builder versions.


Now Experience CLI


This is where you boot up Terminal (Mac/Linux) or Windows Command-Line to support in the development of components. You'll do all of the fancy component work in VSCode or whatever editor you use, but in order to connect your instance, create projects, develop, and deploy you'll need to use the Now CLI. Keep in mind there are now two versions of Now CLI, the older one for Paris/Orlando and the newer one for Quebec, which is what I use in this article. The course on NowLearning focuses on the Paris/Orlando version of Now CLI and the Agent Workspace UI Builder as of the writing of this post. Here's a quick link to all the tools that are used in component building.


Quebec Now CLI Setup


I noticed some issues when working through this on my older Mac, even on Big Sur, versus a newer Mac. It seems like this experience is more seamless on Windows, if you encounter issues just keep searching on community and keep trucking through. For some reason the developer site still points to the old version and old commands, despite Quebec being selected, so if you're on Quebec and you see documentation pointing to 'now-cli' this is the Paris version. Since there is a new Now Command Line for Quebec you'll want to follow the steps in this guide.


ServiceNow CLI User Guide
.pdf
Download PDF • 382KB

A couple of things to note:


You need to install the ui-component extension before you can use any of the project, develop, deploy commands. This is different from the previous Now CLI in Paris/Orlando which from what I remember are already packaged in. This is in the document but to do this, after you login/configure your default profile run:

snc extension add --name ui-component

Building a Component


There's a component course on the NowLearning site that is pretty good, for this walkthrough I'll use what's on the Developer site since it's been more geared towards Now Experience and incorporates the use of the component playground. I'm not going to get into all of the in's and out's of creating a project and deployment, just know if you're on Quebec you have to use the Quebec commands instead of the one's on the Developer site since they're for Paris.


Here's the Quebec code I put in to create a project:

snc ui-component project  --name @blog/developer-site --description 'Creating a component from the Developer site'

Some things to note when creating a project:


Get in the habit of just sending npm install right after you create any project, it'll reduce confusing errors and messages later on.


Find a nice cheat sheet or create a sticky note of directory commands, for example cd and mkdir. Once you create your project, it puts all of the goodies in that folder for you, and then just open the entire folder with your editor of choice. You may see errors stating 'Cannot scaffold a project in a non-empty folder' so make sure whatever directory you're working in is empty on your local machine.


The files you're going to want to work with are located in the src (or source)> component name folder > index.js That's the index.js file you're going to want to work with, there's another index.js that is in the src folder, but it's the one within the component folder that you'll be working with.


As a side-note some time had passed since I connected to my instance and creating my project, so I got some errors relating to 'Could not find an active connection to a ServiceNow instance' so I had to login again using:


snc ui-component login {instance_url (with https)} basic {username} {password}

Alright, let's jump in. Now that I'm in the index.js file in my editor of choice, I'm going to skip around and create the People Counter component. You'll see links sprinkled in this paragraph to different pages of the course because they contain a lot of great content that I don't need to replicate here.


What we're doing in this exercise is building out HTML framework of the component we're building and importing another component to utilize within that framework, basically everything that's in the <div> tags in the code below. The developer site is going to take us through understanding the Now Component Library which I mentioned above, but to expedite things, I imported the now-button component and went through the steps to configure what I needed in the playground. One thing to note, it's not enough to reference or import the button component in your component code, you need to run the install command first:


npm install @servicenow/now-button

At this point following along on the Developer site, i've gotten the user interface of my component built and running it locally. If you get any errors when attempting to run snc ui-component develop, go ahead and run npm install and try again. The nice part about snc ui-component develop is you can leave it running while making changes to your component and it will recompile once you save the changes in your editor. Note: To stop developing in Now CLI, use ctrl-c.


And here's what the index.js looks like:


import {createCustomElement} from '@servicenow/ui-core';
import snabbdom from '@servicenow/ui-renderer-snabbdom';
import '@servicenow/now-button'
import styles from './styles.scss';

const view = (state, {updateState}) => {
    return (
        <div><h1>People Counter</h1>
            <span><now-button label="+1" variant="primary" size="lg" icon="" config-aria={{}} tooltip-content="Add one person to the count"></now-button>
      </span>
            <span><now-button label="-1" variant="primary-negative" size="lg" icon="" config-aria={{}} tooltip-content="Remove one user from the count"></now-button></span>
        </div>
    );
};

createCustomElement('x-redacted-developer-site', {
    renderer: {type: snabbdom},
    view,
    styles
});

Now, I'll move on to the state portion of a component. To provide a very brief overview, state is both a component's state and its properties, and non-dynamic and dynamic states can be utilized in a component. For this next exercise we're going to set an initialState of 0 for the variable peopleState, and utilize the updateState helper function to change the value of the peopleState variable.


import {createCustomElement} from '@servicenow/ui-core';
import snabbdom from '@servicenow/ui-renderer-snabbdom';
import '@servicenow/now-button'
import styles from './styles.scss';

const view = (state, {updateState}) => {

    // Create a peopleCount variable of type const. Get the initialState for peopleCount
    const {peopleCount} = state;
    return (
        <div><h1>People Counter</h1>
            {/* Display the value of peopleCount */}
            <div><h1>{peopleCount}</h1></div>
            {/* When the +1 button is clicked, increment peopleCounter by one. */}
            <span><now-button label="+1" variant="primary" size="lg" icon="" config-aria={{}} tooltip-content="Add one person to the count" on-click={() => updateState({peopleCount: (peopleCount + 1)})}></now-button>
      </span>
            <span><now-button label="-1" variant="primary-negative" size="lg" icon="" config-aria={{}} tooltip-content="Remove one user from the count" on-click={() => updateState({peopleCount: Math.max(peopleCount -1, 0)})}></now-button></span>
            <span><now-button label="Clear" variant="secondary" size="lg" icon="" config-aria={{}} tooltip-content="Reset the count back to zero" on-click={() => updateState({peopleCount: 0})}></now-button></span>
        </div>
    );
};

createCustomElement('x-redacted-developer-site', {
    renderer: {type: snabbdom},
    view,
    styles,
    initialState: {
        peopleCount: 0
    }
});

Next, we'll add some styling to our component, instead of adding CSS directly inline with the HTML framework, we create a scss file within the project folder and call it via id or class tags. There's a styles.scss file that is created in the project folder automatically. The following code is going to be added in under the import line:


h1 {
    font-family: Arial;
    color: rgb(76,86,106);
    padding-left: 3%;
}

now-button {
    padding: 15px;
}


Now that we have the component's framework, gave it some actionable input via state updates, and some styling, we'll deploy it to our instance.


If you want to make your component available to UI Builder, you'll need to modify the now-ui.json file in your package, else you'll just keep seeing 'My Component' everywhere. So I'm going to update the label, icon, and description.


{
  "components": {
    "x-redacted-developer-site": {
      "innerComponents": [],
      "uiBuilder": {
        "associatedTypes": ["global.core", "global.landing-page"],
        "label": "People Counter Developer Site",
        "icon": "user-plus-outline",
        "description": "The people counter component from the developer site",
        "category": "primitives"
      }
    }
  },
  "scopeName": "x_redacted_blog_de_0"
}

Now I can go ahead and deploy this up to UI Builder, and put it on a page to test it out. Again, the developer site has an example with the Orlando/Paris CLI, if on Quebec you'll need to use:


snc ui-component deploy

And here's my success message:



Note: If you need to deploy a new version of a component you'll need to use deploy --force to overwrite your existing one. Also double check your syntax and run your component locally because code with syntax errors more than likely won't deploy.


One important thing to note, is that components deploy into their own application scope. You can determine the scope when creating a project, or ServiceNow will automatically create for you. You'll be able to see the application in the Application Picker and under My Company's Applications.


Lets's step into UI Builder now and put this on a page to test it out. So first off, I can see the icon didn't apply, but that's ok, I can see my component in the list:




My theme styling is overriding the primary/secondary variants of the buttons, which is what I want. Let's test this out in real-time.



Takeaways


There is definitely a learning curve to component building. It seems if you have studied React and its various libraries you'll be a little more in tune on this, despite ServiceNow's proprietary implementation of it. I hope with more time dedicated to learning Now Experience UI Framework and more work with it out in the real world I feel more comfortable creating custom solutions with Now Experience UI Framework.


UI Builder has been built to alleviate some of the component building work and I suggest looking at how you can configure components to meet your needs, but there are always going to be complex use cases that require component building, especially when using third party APIs.


Go through the courses, they will definitely save you some time and headaches in figuring things out, even simple stuff like ctrl-c, that those of us that don't live in command line don't remember. Be sure to check out the Reference material on UI Framework, it has a lot to go through and provides examples and best practices. But remember some of the material may not be updated for the Quebec command line so you're going to have to substitute in the commands rather than following the courses verbatim.


I'm sure some of you are asking how to link the data we've gathered in a component to the instance, as this example was pretty simple and this post covered a lot of basics. I'll have future posts to come as I dig a little deeper into component building and into some more advanced concepts.



Resources


Build My First Now Experience UI Framework Custom Component

- keep in mind this is geared towards Paris Now CLI, so if you're on Quebec you'll have to do some translating in the steps in the course.


NowLearning: Introduction to External Component Development and Deployment - keep in mind this is geared towards Paris Now CLI, so if you're on Quebec you'll have to do some translating in the steps in the course.


Getting started with the Now Experience UI Framework



1,015 views0 comments