How to make a Cross Origin Resource Sharing (CORS) Component in UI Builder (UIB).
What is CORS?
For security reasons web browsers cannot make arbitrary calls to paths and APIs that are not part of the originating server, i.e. the server that rendered the page that the script is executing on. However, the ability to do this can be a valuable, and indeed safer, way to access data from 3rd party systems or data secured behind a firewall and not accessible from their ServiceNow instance.
To solve this, while still remaining secure, Cross Origin Request Sharing (CORS) is a web standard for making direct client-to-api calls from a browser to an API on a different domain. This is a W3C standard and when properly configured is a valid (even common) technique for securely accessing data on second party systems, especially from an application behind a firewall. Authentication for the second party application is handled by the browser like any other web application and neither the ServiceNow instance nor the application needs to store credentials or handle authentication.
Why use CORS?
Consider a managed service provider whose staff uses ServiceNow to manage their customers’ equipment, but also host an internal only application that preserves credentials. They may want to control access and authentication to their credential application, secure it behind a firewall, and ensure that data never traverses another app, while still rendering information within a ServiceNow workspace so that users can see a list of credentials on a case without switching applications. By configuring CORS such an application can request a list of credentials from this service directly from the browser even though the URL is different from the instance which is using it (e.g. a workspace in myprod.service-now.com could call an API on credentials.internalwebsite.com and render it within a workspace).
How to CORS from UI Builder
As a W3C standard it has long been possible to retrieve data client-side using XMLHttpRequest or Fetch from any web application, including a Jelly or Service Portal based web application in ServiceNow.
UI Builder (UIB), however, does not offer this capability by default. While you can make API calls from the client, the data resources which we provide are only able to call APIs on your instance. Luckily there is a straightforward if not exactly “simple” solution.
Heads up—we are moving strictly into a pro-dev world, so experience with web application development, Node.js and other web frameworks and processes is going to be helpful. If you’re interested in implementing CORS, though, I’m betting that you’re reasonably experienced and once you get this set up you will hopefully be able to leverage it quickly and easily when you need this capability.
ServiceNow Command Line Interface (CLI)
The ServiceNow Command Line Interface (ServiceNow CLI or “SNC CLI”) is a tool which you can install and use it to make your own custom components which you can then leverage on a UIB page much like other components which ServiceNow has developed for your use.
To get started follow the instructions within the ServiceNow CLI documentation.
A couple of pointers to increase the odds of success.
- Do NOT upgrade the dependencies. Throughout the installation of the third-party tools (e.g. NPM) the tools will beg you to upgrade. The CLI requires specific versions so be sure that you are working with those versions so do not upgrade.
- After installing the SNC CLI you may receive the scary-sounding warning "this instance does not support dynamic commands"—just use the following command to authenticate and you will be fine going forward.
snc ui-component login {instance_url} basic {user_name} {password} - After installing the SNC CLI and before you can start developing you must install version 12.16.1 of Node and version 6.13.4 of NPM. Use these instructions to install NVM (Node version manager) and switch to version 12.16.1.
- On the “Setup your project” page don’t forget to run the last step (npm install).
- Continue with the “hello world” component sample in the docs, but in the last step of the “Develop a Component” page use the following command instead of their suggestion:
snc ui-component develop --open
- Before deploying your component to your instance be sure to follow the instructions to configure the now-ui.json file which is created for you so that you can use it directly from UIB.
- You should have your first component up and running and you are good to go!
Basic Design of a CORS Custom Component
Code built within a custom component has pretty much maximum flexibility. Anything that you can do using JavaScript and HTML5 and NPM dependencies you can do in a custom component.
- Pass the URL that you wish to query, and any request configuration, into your component.
- Make the request using the Fetch API.
- Your component will then fire an event with a payload containing the results of the request.
- Add a second event to emit errors.
- On the page which is using your component add event handlers to then pass the payload to a page script or a client state parameter which can then be used elsewhere on the page (e.g. rendered in a repeater).
That's the basic design--once you get everything setup hopefully it makes sense and you will have the freedom to implement whatever you need. If you need any help reach out to the Next Experience Product Success team @Jon G Lind or @Thomas Belkowski.
