One Easy Trick to Make Your Apps 10X More Powerful

Grant Hulbert · ‎06-15-2020

TL;DR: Make your apps more powerful and useful to a broader audience by giving them APIs that enable other developers to easily integrate with them
Who should care: developers and architects who write ServiceNow apps, and product managers who influence development teams. Anyone who wants their apps to be more widely used
Key actions:
- Encapsulate app logic in centralized utility functions, for easy re-use
- Add Scripted REST API endpoints that wrap those utility functions
- Add Flow Designer Actions that wrap those utility functions

Intro:

You’ve written the perfect ServiceNow app. It does everything your manager asked for and is completely bug-free. The use-cases you dreamt up are covered, so now it’s time to publish, sit back and reap the rewards of your hard work.

But wait! What if you could make it even more powerful and useful by doing just one easy thing?

I’m talking about something you probably wish other developers would do too: provide a public API so the app can be used safely and reliably by other apps and in ways you never thought.

Why add an API? There are many benefits:

Better code organization makes your own work easier, more stable, and more maintainable
Your teammates and others in your company can reliably connect to your app
Customers are happy they can integrate with your apps and use them in broader workflows
Broader adoption puts the law of surprise into effect: You never know how someone else will use your app. Our founder Fred Luddy was constantly delighted to see how customers re-used and connected to his apps!
Using your Actions Spoke, no-code developers can control and connect to your app simply by dragging and dropping in Flow Designer
Adding an API eliminates the hacking that other developers inevitably do to your app anyway

Convinced but worried it’s too much work? Nonsense! Here, we’ll cover three simple techniques for adding an API to your app: one pattern that is common to all programming languages and two easy ones that are unique to ServiceNow. We will also layer these techniques so they build on each other.

These are the three specific actions we’ll discuss in this article:

Encapsulate app logic into centralized utility functions for easy re-use
Add Scripted REST API endpoints that wrap those utility functions
Add Flow Designer Actions that wrap those utility functions

Cleanly-Factored Code: Encapsulate App Logic into Centralized Utility Functions

Because this is central to all good programming practices in general, you’ve probably already done this. However, if you’re new to ServiceNow, you may want to see an example that shows where to put your library of reusable functions.

Have you ever noticed that you sometimes write the same little snippet of code in several places? They’re usually inside a couple Business Rules, a Form Action, perhaps even a Transform Script. Nowadays, with the advent of Integration Hub, you might even have some scripts inside Flow Actions as well. No worries – we all do it as we’re building apps, and we also all get that little voice in our heads telling us this probably needs to be refactored.

Notice I’ve copied the same snippet of code into both a UI Action and a Business Rule:

How can we make this better? Here’s a simple example from one of my own projects.

It’s always a good idea to refactor your code by creating a single function and calling it from those places, rather than having copies of the same code all over the place. Here’s the refactored code, placed into a tidy Script Include.

Nothing earth-shattering here; this is standard practice, so I’m probably not telling you anything new, except for ServiceNow’s terminology for Script Includes and how to call them from other places in your app.

Script Include

UI Action’s script

Business Rule’s script

API Name: <your app scope>.Util
Accessible from: [All application scopes]

Script:

var Util = Class.create();
Util.prototype = {
 initialize: function() {
 },

doSomethingAmazing: function() {
 // Your reusable utility function goes here
 },

type: 'Util'
};

var util = new <your app scope>.Util();
util.doSomethingAmazing();

var util = new <your app scope>.Util();
util.doSomethingAmazing();

Note: it’s super-important to choose “All application scopes” in your Script Include’s “Accessible from” field. This enables other apps on the same instance to call your public functions.

Now that you’ve refactored your code into beautifully simple utility functions inside Script Includes, it’s time to expose them to outside callers via REST. This one simple practice makes your app visible and useful to the cloud so that other systems (maybe even outside ServiceNow) can call your app and do useful things with it. By doing so, other developers won’t be tempted to make private table API calls deep into your app, because now you’ve given them a nice tidy contract with reliable interfaces for them to safely call.

Let’s jump in!

From Studio, create an application file of type “Scripted REST API”
Give it a name, such as “Utils”, and click [Submit]
At the bottom of the form, in the Resources tab, click [New]
Set the name to “doSomethingAmazing”, and Relative path to “/doSomethingAmazing”

Inside the Script, call your utility and return the value it generates

(function process(/*RESTAPIRequest*/ request, /*RESTAPIResponse*/ response) {
  var util = new <your app scope>.Util();
  return util.doSomethingAmazing();
})(request, response);

Click [Update]
To test your new REST API, click the link “Explore REST API”

Congratulations, your instance now has a REST API endpoint that exposes your useful function! It should look something like this:

https://<yourinstance>.service-now.com/api/<your_app_scope>/utils/doSomethingAmazing

And the response should look something like this:

{
  "result": {
    "object": "isAmazing"
  }
}

Note: Make sure you protect your Scripted REST API endpoints with authentication; you don’t want to expose your app to unauthorized users or scripts.

Add Flow Designer Actions to Enable No-Code Developers to Use Your App in Their Own Flows

Now that external callers can use your app from the cloud, let’s turn inward to ServiceNow developers who want to use your app from within the same instance. For example, perhaps a customer has installed your app and wants to include its features in their own custom workflows. Wouldn’t it be great if they could just drag and drop your app actions into their own Integration Hub Flows?

Here’s how you add an Integration Hub Action, which will become a part of your app’s Spoke:

From Studio, create a Flow Designer Action
Give it a name, e.g. “doSomethingAmazing”
Click the little green [+] between Inputs and Outputs
Choose Script from the utilities section
Scroll to the bottom of the Script step and add an output variable named “result” of type JSON

From the script, call your utility function, and output the result

(function execute(inputs, outputs) {
  var util = new <your app scope>.Util();
  outputs.result = util.doSomethingAmazing();
})(inputs, outputs);

Click [Test] and confirm that your Action produces JSON output
Click [Publish]

That’s it! You’ve exposed your app’s function to other Flows. Now, after customers install your app, they will be able to choose your Actions while designing their own Flows, as seen here:

What Have We Accomplished?

A lot! By exposing your app’s API in several key places, other developers can now:

Call your app’s utility functions from other applications, even from ones you’ve never imagined
Integrate with your app from across the cloud using REST APIs
Drag and drop your app’s functions into other Flows

All that’s left is to try it in real life, and I promise you’ll be surprised by the many ways other developers use your app in their own workflows.

Additional resources:

Flow Designer: https://developer.servicenow.com/blog.do?p=/tags/flow-designer/
Scripted REST API: https://developer.servicenow.com/blog.do?p=/tags/scripted-rest-api/
YouTube: https://www.youtube.com/watch?v=bJGLvPIPxGA

Authors:

Grant Hulbert, Director, Office of Innnovation
Zach Dubin, Thought Leadership Researcher & Writer