This article explains how to implement a UI policy to toggle the disabled/mandatory states of two fields based on their values.

The goal is to control the accessibility and mandatory setting of two fields, based on their values, such as if the first field is set, then the other field becomes disabled and vice-versa.

There could be various way to implement this, and this article proposes to do it with a UI policy.

For instance, let’s say we have two fields: Company and Person. The user must populate either one of these fields, as shown in this recording:

Implementation

To achieve this, we can create a UI policy named “Toggle disabled state of Company and Person” on the table.

Conditions

In the conditions, you need to checks whether either field contains any value, by using “Company Is Anything or Person is Anything” (companyANYTHING^ORpersonANYTHING^EQ).

Scripts

Then, in the Script tab, set “Run scripts” and enter the two scripts like in the examples below.

When the Condition is True

The condition evaluates to true when at least one of the fields (“company” or “person”) contains a value.

The script then disables the field that does not have a value while leaving the field with a value enabled.

This ensures that users input data into only one of these fields.

If by any chance both fields contain values, neither of them is disabled, allowing the user to retain or modify the existing data in both fields.

function onCondition() {
	/*
		The condition is true when at least one of the two fields has a value set.
		In this case, we disable the other field, except for the case where both fields are set.
	*/
	// Names of the fields
	let companyField = "company";
	let personField = "person";

	// Get the value of the fields
	let companyValue = g_form.getValue(companyField);
	let personValue = g_form.getValue(personField);
	
	// If both values are set (e.g., set from the list), return as we don't want to disable any of them.
	if (companyValue && personValue) {
		return;
	}
	
	// If the company is set, disable the person field
	if (companyValue) {
		g_form.setMandatory(personField, false);
		g_form.setDisabled(personField, true);
	}
	// If the person is set, disable the company field
	if (personValue) {
		g_form.setMandatory(companyField, false);
		g_form.setDisabled(companyField, true);
	}
}

When the Condition is False

The condition becomes false when neither the “company” nor “person” fields have values set.

The script then enables both fields, making them available for user to input data, and sets them as mandatory.

The user is required to populate at least one of these fields for the form.

function onCondition() {
	/*
		The condition is false when both fields are not set.
		In this case, we enable both fields as they are open for input.
	*/
	// Names of the fields
	let companyField = "company";
	let personField = "person";

	// Get the value of the fields
	let companyValue = g_form.getValue(companyField);
	let personValue = g_form.getValue(personField);
	
	// If the company field is not set, enable the person field
	if (!companyValue) {
		g_form.setMandatory(personField, true);
		g_form.setDisabled(personField, false);
	}
	// If the person field is not set, enable the company field
	if (!personValue) {
		g_form.setMandatory(companyField, true);
		g_form.setDisabled(companyField, false);
	}
}

What does the ISANYTHING operator do ?

Now you are maybe wondering what is the ISANYTHING operator that we are using the UI policy.

According to ServiceNow documentation¹, it means that it matches on the following values: any value, empty, null.

Also in the KB article KB0815207², it says:

By design, the “is anything” filter operator always evaluates to true whether a field is empty or not."

But is this really true ?

The explanations above were all I could find in the documentation (admittedly I didn’t look much more). But then, if it is always true, why do we need a script for the false condition ?

To be sure, I made a test by displaying a message in each script, so to know which one is executed when, like this:

// Test execution 
let msg = `condition TRUE\ncompanyField=${companyValue} (${companyValue==null}/${companyValue==""})\npersonValue=${personValue} (${personValue==null}/${personValue==""})`;
alert(msg);

You can see the result here:

So we can see that:

• when loading the empty form, it evaluates to false
• when entering a value in one of the field, it evaluates to true
• when emptying the field, it evaluates to false

So we can observe that it doesn’t really behave like it is suggested in the documentation.

But fortunately we can circumvent this discrepancies by using both the true and false script and achieve what we aimed for.

Despite of having two scripts, the UI policy solution is in my opinion more elegant than using Client Script. Using Client Script would require to have a script for each field and duplicate the code in different places. The UI policy allows to keep everything tidy in one place.

Since the Vancouver release, there is a new API GlideJsonPath¹ that allows to query a JSON string with jsonPath².

The jsonPath can be viewed as the JSON equivalent of the XPath for XML. It allows to perform queries like $.library.bools.*.title for example. Jsonpath is offically a RFC since february 2024³

I suspect the under the hood, it use the implementation JsonPath⁴.

Usage of the GlideJsonPath

The official documentation¹ is very succint and there is a couple of extra information that can help:

• the GlideJsonPath expect a String, not an object as parameter
• the read function seems to return an array of JavaObject, which are not the same as the javascript objects. It might need some kind of converstion before being able to use it.

To ease the usage, I suggest to use a function like this one, that accept an Object as parameter and return also a javascript Object:

/*
	@name executeJSONpath
	@description execute the JSON path on the given object and return the result 
	@param {Object} [obj] - Object on which to execute the json path
	@param {String} [jsonPath] - Json path to use for the query
	@return {Object} Object after applying the jsonPath read
*/
function executeJSONpath (obj, path){
  try{
    // Convert the object to a JSON string
    var jsonString = JSON.stringify(obj);

    // call and retrieve the result from GlideJsonPath
    var gjp = new GlideJsonPath(jsonString);
    var gjpResult = gjp.read(path);

    return gjpResult;
    
  } catch (exception){
    gs.error("Error in function 'executeJSONpath' : " + exception + JSON.stringify(exception));
  }
}

JSON path syntax

The JSON path syntax can be summarized as follow:

dot-notation or bracket-notation

the JsonPath can use either a dot-notation, like $.store.book[0].title or a bracker-notation $['store']['book'][0]['title']

It can also use a mix of both, like this example: $['store']['book'][0].title

Also in the bracket notation, it is possibe to specify mutliple attribute to retrieve, for example: `$[‘store’][‘book’][0].[“title”, “author”]

Elements

The JsonPath can use the following elements ²³⁴:

• $: The root element to query. This starts all path expressions.
• @: The current node being processed by a filter predicate.
• *: Wildcard. Available anywhere a name or numeric are required.
• ..: Deep scan. Available anywhere a name is required.
• .<name>: Dot-notated child
• ['<name>' (, '<name>')]: Bracket-notated child or children
• [<number> (, <number>)]: Array index or indexes
• [start:end]: Array slice operator
• [?(<expression>)]: Filter expression. Expression must evaluate to a boolean value.

Functions

The specification gives several functions (min(), max(), …), but unfortunately it seems thay are not supported by the ServiceNow implementation.

Operators

For use in the expression, we can use the “classic” operator like “==”, “!=”, “>”, “=>”, etc. It also supports:

• =~: left matches regular expression [?(@.name =~ /foo.*?/i)]
• in: left exists in right [?(@.size in [‘S’, ‘M’])]
• nin: left does not exists in right
• subsetof: left is a subset of right [?(@.sizes subsetof [‘S’, ‘M’, ‘L’])]
• anyof: left has an intersection with right [?(@.sizes anyof [‘M’, ‘L’])]
• noneof: left has no intersection with right [?(@.sizes noneof [‘M’, ‘L’])]
• size: size of left (array or string) should match right
• empty: left (array or string) should be empty

Limitations

• functions: functions are not supported, as stated above
• unique values: There is not way to ask for unique values: there can be duplicated entries (for example when listing all categories)

Example of JSON path

This table show the result of various jsonPath from the GitHub JsonPath documentation⁴.

When creating a new jsonPath, you can use this online evaluator⁵ to test it

Sample JSON

Here is the sample JSON used for the tests:

{
    "store": {
        "book": [
            {
                "category": "reference",
                "author": "Nigel Rees",
                "title": "Sayings of the Century",
                "price": 8.95
            },
            {
                "category": "fiction",
                "author": "Evelyn Waugh",
                "title": "Sword of Honour",
                "price": 12.99
            },
            {
                "category": "fiction",
                "author": "Herman Melville",
                "title": "Moby Dick",
                "isbn": "0-553-21311-3",
                "price": 8.99
            },
            {
                "category": "fiction",
                "author": "J. R. R. Tolkien",
                "title": "The Lord of the Rings",
                "isbn": "0-395-19395-8",
                "price": 22.99
            }
        ],
        "bicycle": {
            "color": "red",
            "price": 19.95
        }
    },
    "expensive": 10
}

This article explains how to implement a dynamic countdown message in the portal. This can be used in various scenarios where a countdown or other variable, dynamic information is updated in the message, like session timeouts, limited-time offers, etc.

For example, it can be a message like “You have MM:SS remaining to complete this action”.

Approach

The idea is to get the base message with gs.getMessage() in the server script and replace the dynamically the timer using a client script.

Why not simply use a static Angular message

Angular offers a way to bind dynamic data to the HTML template, but it has limitations when the message itself is partially static with only one part that change dynamically. To my knowledge there isn’t a way to easily replace a placeholder (like “MM:SS”) within the message itself every second.

Implementation

Server Script

In the Server Script, we basically retrieve the messages and the different options for the time options.

// get the widget options
data.timer = options.timeout; // initialize the timer, in milliseconds
data.timeout = options.timeout; // keep the timeout value, used when resetting the time

// get the count down message
data.countDownMessage = gs.getMessage(options.countdownmessage);

Client script

In the Client Script, we first need a function to format time in the “MM:SS” format and set the timer value used in the message:

// Set the initial value of the time to display to the user
c.data.timeMMSS = formatMillisecondsToMMSS(c.data.timer);

// Function to convert the millisecond in minutes:seconds (MM:SS) format
function formatMillisecondsToMMSS(milliseconds){ 
	var seconds = parseInt(milliseconds / 1000, 10); 
	var minutes = parseInt(seconds / 60, 10);   
	seconds = seconds % 60;
	minutes = minutes % 60;   
	var formattedTime = minutes.toString().padStart(2, '0') + ":" + seconds.toString().padStart(2, '0');   
	return formattedTime;
}

Then we need to set the timer for the countdown, that will update the time displayed to the user:

// Start updating the timer every second
$timeout(updateTime, 1000);
function updateTime(){
	c.data.timer -= 1000; // Decrease the timer by 1 second

	// check if the time is over
	if (c.data.timer <= 0) {
		// Set the displayed time to zero (so we never show negative time)
		c.data.timeMMSS = formatMillisecondsToMMSS("0");
		// perform the required action when time is over, for example redirect somewhere else
		window.location.href = "/somewhere.do";
	} else /*update counter*/ {
		c.data.timeMMSS = formatMillisecondsToMMSS(c.data.timer);
		$timeout(updateTime, 1000); // Update again after 1 second
	}
}

In some cases, we want to reset the countdown, for example when the user is interacting with the page:

// Reset the timer when navigating in the page 
$rootScope.$on('$locationChangeStart', function(event, newUrl, oldUrl) {
	resetTimer();
});  

// Reset the timer on click and keydown events
document.addEventListener('click', resetTimer); 
document.addEventListener('keydown', resetTimer);   

// Function to reset the timer 
function resetTimer() { 
	// reset the timer 
	c.data.timer = c.data.timeout; 
	c.data.timeMMSS = formatMillisecondsToMMSS(c.data.timer);
}

HTML template

And the last, but not the least, here is the HTML template. To display the dynamic message, it call the function formatCountDownMessage() with the message and the time in the MM:SS format.

<span class="countdownmessage">{{c.formatCountDownMessage(data.countDownMessage, data.timeMMSS)}}</span>

and the corresponding function (in the client script!):

// Add the formatCountDownMessage
c.formatCountDownMessage = function(message, timeMMSS) { 
    if (!message || !timeMMSS) return message; 
    return message.replace('MM:SS', timeMMSS);
};

Putting all together in the Client Script

Here is the complete Client Script with all the part detailled above. You can also find the complete widget in the References section below.

api.controller = function($timeout, $rootScope) {
    /* widget controller */
    var c = this;

    // Set the initial value of the time to display to the user
    c.data.timeMMSS = formatMillisecondsToMMSS(c.data.timer);

    // Start updating the timer every second
    $timeout(updateTime, 1000);

    // Reset the timer when navigating in the page 
    $rootScope.$on('$locationChangeStart', function(event, newUrl, oldUrl) {
        resetTimer();
    });

    // Reset the timer on click and keydown events
    document.addEventListener('click', resetTimer);
    document.addEventListener('keydown', resetTimer);

    // Function to update the timer 
    function updateTime() {
        c.data.timer -= 1000 // Decrease the timer by 1 second
			
        // check if the time is over
        if (c.data.timer <= 0) {
            // Set the displayed time to zero (so we never show negative time)
            c.data.timeMMSS = formatMillisecondsToMMSS("0");
            // perform the required action when time is over, for example redirect somewhere else
            window.location.href = "/somewhere.do";
        } else /*update counter*/ {
            c.data.timeMMSS = formatMillisecondsToMMSS(c.data.timer);
            $timeout(updateTime, 1000);//  Update again after 1 second
        }
    }
    // Function to reset the timer 
    function resetTimer() {
        // reset the timer 
        c.data.timer = c.data.timeout;
        c.data.timeMMSS = formatMillisecondsToMMSS(c.data.timer);
    }

    // Function to convert the millisecond in minutes:seconds (MM:SS) format
    function formatMillisecondsToMMSS(milliseconds) {
        var seconds = parseInt(milliseconds / 1000, 10);
        var minutes = parseInt(seconds / 60, 10);
        seconds = seconds % 60;
        minutes = minutes % 60;
        var formattedTime = minutes.toString().padStart(2, '0') + ":" + seconds.toString().padStart(2, '0');
        return formattedTime;
    }

    // Add the formatCountDownMessage
    c.formatCountDownMessage = function(message, timeMMSS) {
			if (!message || !timeMMSS) return message;
			
        return message.replace('MM:SS', timeMMSS);
    };

};

References

1.A complete example widget is availlable in github

This article shows how to use the Google Vision API to extract text from attachments and to make this text searchable in Service-Now.

In this quick demo, we can see that attaching printscreens to an incident will trigger a call to the Google Vision API and extract the text in a field Extracted field on the attachment table and consolidate all the attachment texts in a field Attachment text on the incident.

Then we can search string that are present only on the screenshots, like “Wikipedia” or “Croissant” in this case.

Now, let’s see how to implement this solution.

Setup the google APi

First of all, you will need a Google Cloud account.

If you don’t already have a Google Cloud account, you can setup your account here: https://cloud.google.com/

When done, go in the Google Cloud console and follow the instruction in the starting guide[1] and in the Detect text in images guide[2].

Basically you will need to:

• create a new Project
• activate the Vision API for your project
• Create an API key in the credential
  • Go in the menu, the “API & Services” - “Credentials”

    

  • Then click “Create Credential” - “API key”

    

  • Then copy and keep the key for later reference.

You should now be ready to use the google API.

Obviously, for real life usage, you may want to use other authentification methods and/or add some more security. To do so please refer to the Google Cloud documentation or consult a Google Cloud specialist.

Adapt the attachment table

The idea is to store the extracted text from the image in a text field on the attachment table.

Before doing so, I suggest to work in an Scoped Application: so please create and use a new Application “OCR Attachment”.

Then, let’s create a new field u_extracted_text on the table sys_attachment, of type String and of a sufficient size of 4000.

Then we need give access at our application “OCR Attachment” to the Attachment table:

• go in “System Definition” - “Tables”
• select the sys_attachment table
• on the “Application Access” tab set “Can Update” to true.

  

• To avoid potential issues later, please also reset the cache by doing a cache.do in the Filter Navigator.

Create the REST message

Now we need to create a REST message and the corresponding HTTP method.

Simply create a new REST message “Google Vision API” and set the endpoint to

https://vision.googleapis.com/v1/images:annotate

Then open the prefefined HTTP method that is automatically created when saving the REST message and

• renamne it to “POST”
• Set the HTTP method to “POST”
• Set the endpoint to https://vision.googleapis.com/v1/images:annotate?key=${apikey}
• On the “HTTP request” tab, set the Content to

  {
     "requests":[
  	  {
  		 "image":{
  			"content":"${base64Image}"
  		 },
  		 "features":[
  			{
  			   "type":"TEXT_DETECTION"
  			}
  		 ]
  	  }
     ]
  }
  

The important points are the variable names apikey and base64Image, that we will use in the Business Rule later.

Testing the rest message

To test you REST message and HTTP request, you can add 2 entries in the Variable Substitution related list:

• apikey: containing the API you created before in the Google Cloud console
• base64Image: containing a base64 encoded image that have text in it.
  • You can use this online base64 converter to convert your image.

Then you can use the test related link and you should get a code 200 and a json string with the text extracted from your image.

Create a Business Rule on the attachment table

Now that both the table and the REST message are ready, we can create a new Business Rule:

• Name : “Extract text from image”
• Table: sys_attachment
• Advanced: true
• When to Run
  • When: async
  • On insert
  • Condition: Extracted Text is Empty and File name ends with .jpg, .jpeg or .png (adapt the list to your taste)

The in the Advanced tab, you can use and adapt the following code:

(function executeRule(current, previous /*null when async*/) {


	try {
		// get base64 string from file 
		var base64Str = new GlideSysAttachment().getContentBase64(current);

		// get API key 
		var apiKey = gs.getProperty('x_12270_ocr_attach.googleVision_api_key');

		if (base64Str && apiKey){
			// build request
			var request= new sn_ws.RESTMessageV2('x_12270_ocr_attach.Google Vision API', 'POST');
			request.setStringParameterNoEscape('base64Image', base64Str);
			request.setStringParameterNoEscape('apikey', apiKey);

			// execute request
			var response = request.execute();

			// extract response
			var responseBody = response.getBody();
			var httpStatus = response.getStatusCode();
			// if success
			if (httpStatus == '200'){
				responseObj = JSON.parse(responseBody);
				if (responseObj && responseObj.responses[0] && responseObj.responses[0].fullTextAnnotation){
					var text = responseObj.responses[0].fullTextAnnotation.text;
					if (text){
						current.u_extracted_text = text.toString();
						current.update();
					}
				}
			}
		}


	} catch (exception){
		gs.error("Error in Business rule 'Extract text from image': " + JSON.stringify(exception));
	}


})(current, previous);

Then the last step is to create a new system property googleVision_api_key and set there the API key you created from the Google Cloud Console.

Searching tasks using attachment’s text

Now the last part is to be able to search records (like incidents, etc.. ) where the related attachment contains the searched text.

The easiest way for this is to create a new field on the Task table that will contains the extracted text of all the attachments. This way the text contained in this field (the text extracted from the attachments) will be included in the Zing search on tasks.

So, let’s create a new field attachment_text on the table task, of type String and of a sufficient size of 4000.

Then we need a new Business Rule on the table sys_attachment:

• Name : “Maintain extracted text on related task”
• Table: sys_attachment
• Advanced: true
• When to Run
  • When: after
  • On insert, update, delete
  • Condition: Extracted Text changes
• Conditions:

new GlideTableHierarchy(current.table_name).getRoot() == "task" /*check that the related table is child of task*/

The in the Advanced tab, add the following code:

(function executeRule(current, previous /*null when async*/) {
	try{
		// get the related table
		var taskGr = new GlideRecord(current.table_name);
		if (taskGr.get(current.table_sys_id)){
			// to hold the attachment texts
			var attachmentTextObj = {};
			// make sure the attachment text field is valid
			if (taskGr.isValidField('x_12270_ocr_attach_attachment_text')){ /*ADAPT according you Application mame, etc...*/
				// if the attachment text field exist and is not empty, parse it
				if (taskGr.x_12270_ocr_attach_attachment_text){ /*ADAPT according you Application mame, etc...*/
					attachmentTextObj = JSON.parse(taskGr.x_12270_ocr_attach_attachment_text); /*ADAPT according you Application mame, etc...*/
				}
				// if we delete the attachment, remove the corresponding text
				if (current.operation() == 'delete') {
					delete attachmentTextObj[current.getUniqueValue()];
				} else /*otherwise, set the text*/ {
					attachmentTextObj[current.getUniqueValue()] = current.u_extracted_text.toString();
				}
				// Set back the attachment text to string and update
				taskGr.x_12270_ocr_attach_attachment_text = JSON.stringify(attachmentTextObj); /*ADAPT according you Application mame, etc...*/
				taskGr.update();
			}
		}
	} catch (exception){
		gs.error("Error in Business rule 'Maintain extracted text on related task': " + JSON.stringify(exception));
	}
})(current, previous);

Testing

You can now take a print screen with text in it and attach it to a record like an Incident:

• The sys_attachment record now have the text extracted in to the Extracted textfield.
• The incident record record now have also the text in the attachment_text field.

You can now search for a String that is present on the screenshot and you incident should show up in the search result

References

1. Cloud Vision API - Documentation - Quickstart: Setup the Vision API https://cloud.google.com/vision/docs/setup
2. Cloud Vision API - Documentation - Detect text in images https://cloud.google.com/vision/docs/ocr

For this purpose, we will create a portal Widget and make it interact with a list to show the records related to the choosen location.

Instead of relying on the google map services, it use instead OpenStreetMap (OSM) data ¹

To achieve this, it relies on the open-source Javascript library Leafletjs to render interactive maps².

While there are a number of other libraries to render maps, like OpenLayers³, Leaflet has the advantage of being lighweight and easier to use.

So as we don’t need to cope with more complexe stuff like geo projections and handling various geo data sources, Leaflet offer all the functionnalities we need for a simple map and is enough for our needs.

A simple use case…

The use case in scope for of this article is quite simple: we want to show the users on a map, grouped by location if there are more than one, and then filter a list of users according the location the we click on the map.

There are mainly 3 parts:

1. Create a Widget to show the map
2. Query the data for ServiceNow and show them on the map
3. Enable interaction with the ServiceNow Portal when a location is selected on the map

We will now go through all the steps and build incrementally the map widget.

How Leaflet works

As said before, we are using the Leaflet.js API for all our mapping needs.

Before jumping in ServiceNow to build the widget, I suggest you to take a few minutes to read at least the Leaftet’s Quick Start Guide⁴.

The key points are mainly:

• We need the library and css in the page
• The HTML part is very simple, just a <DIV> tag
• Then in the code we need:
  • to create the map with L.map and make the link with the <DIV>tag
  • Use setView to indicate where to center the map and the scale to use
  • build the tileLayer with L.tileLayer, and that where we incidcate the OpenStreetMap tiles server
  • Add the features on the map with L.marker
  • We need then to react on click to interract with the portal and also center the map on the clicked feature

Building the map widget

To start buidling the map widget, I recommand using a custom scoped application in ServiceNow.

When your application is created, create a new Portal Widget:

• Name : Leaflet Map
• ID: leaflet_map

store the Leaflet API scripts as widget dependencies

When creating the dependencies, you can either use a link to the Leaflet script online or store a copy in the ServiceNow instance.

I recommand storing a copy, so we don’t depedant on other servers availlability for this part.

To do so, start by downloading the Libraries, either from the UNPKG repository ⁵ or from the Leaflet web site ⁶.

We need the two following files:

• leaflet.js
• leaflet.css

Then create a new Widget Dependency called “Leaflet” and add a new JS include and a new CSS include containing repectively the content of file leaflet.js and leaflet.css.

Set the HTML, CSS and client script for a first test

Set the HTML part as follow:

<div id="map"></div>

Then the CSS part:

#map {
  position: absolute;
  top: 0px;
  left: 0px;
  width: 500px;
  height: 500px;
}

And finally the client script:

api.controller=function() {
	/* widget controller */
	var c = this;

	// build the map
	var map = new L.Map('map');

	// get the tile layer
	var url = 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png';
	var tilelayer = new L.tileLayer(url,{
		attribution: '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors' /*required as per OSM license - https://www.openstreetmap.org/copyright/en */
	});
	
	// add layer to the map
	map.addLayer(tilelayer);

	// set the view
	var latitude = c.options.start_position_latitude;
	var longitude = c.options.start_position_longitude;
	var scale = c.options.start_scale;
	map.setView(L.latLng(latitude, longitude), scale);
};

As a good practice, we should avoid to hardcode the values in the script and use options instead. So we still need to add this JSON in the Option schema of the widget. You can of course change the default value to suit your needs or change them later in the widget instances.

[
   {
      "name":"start_position_longitude",
      "section":"other",
      "default_value":"6.6327",
      "label":"Start position longitude",
      "type":"string"
   },
   {
      "hint":"",
      "name":"start_position_latitude",
      "section":"other",
      "default_value":"46.5218",
      "label":"Start position latitude",
      "type":"string"
   },
   {
      "name":"start_scale",
      "section":"other",
      "default_value":"13",
      "label":"Start scale",
      "type":"string"
   }
]

Make sure the widget option Has preview is checked and you can now vizualize the result with the Widget Editor:

Query the data from ServiceNow

Now that we have a map displayed, we need to add informations coming from the ServiceNow tables.

In this example we will show Users from the table sys_user. The position of each user will be determined by the location field.

Then we will use the longitute and latitude from the referenced Location (table cmn_location).

geoJSON format

To indicate Leaflet what to display and where, we need to provide the API with a geoJSON string ^{7 8}.

Each “object” to put on the map is called a feature.

The GeoJSON standard specify various type of data that can be represented, but the one that suits our needs the best is the FeatureCollection, where multiple Features can be represented (but it work also if there is only one feature).

The format is as follow:

 {
	"type": "FeatureCollection",
	"features": [
		{
			"geometry": {
				"type": "Point",
				"coordinates": [
					x,
					y
				]
			},
			"type": "Feature",
			"properties": {
				"popupContent": "text",
				"iconText" : "iconText",
				"locationId" : "sys_id of location"
			}

		}
	]
}

The properties part is free, so we can set everything we need. For the example, there is

• popupContent, that contains the text to show on a pop-up when clikcing the location,
• iconText that is shown on the map (will be used for the count of record on each location,
• locationId that contains the sys_id of the location’s record.

Retrieving the data

To retreive the data, we will use a GlideAggregate on the table and group by the location. Note that the table, the name of the field that refernece the location table and the query on the table are coming from the Widget options:

	// get the options values
	var sourceTableName  = options.features_source_table;
	var locationFieldName = options.feature_location_field;
	var sourceTableQueryStr = options.feature_table_query;

	// get the data from the table to shown as features
	var featureGa = new GlideAggregate (sourceTableName);
	if (sourceTableQueryStr){
		featureGa.addEncodedQuery(sourceTableQueryStr);
	}
	featureGa.addNotNullQuery(locationFieldName);
	featureGa.addAggregate('COUNT');
	featureGa.groupBy(locationFieldName);
	featureGa.query();

Building the GeoJSON

To build the GeoJSON, we will use two functions: one to give the main GeoJSON object and another to build each Feature that will be added to the main GeoJSON object.

/**
	@name getGeoJSONFeaturesCollectionObject
	@description get the main GeoJSON Feature Collection Object
	@returns {object} GeoJSON Feature collection Object
**/
function getGeoJSONFeaturesCollectionObject () {
		return {
			"type": "FeatureCollection",
			"features": []
		};
	}


/**
	@name getFeatureObject
	@description Get the Feature part of the GeoJSON
	@param {GlideRecord} [loationGr] - GlideRecord from the Location table (cmn_location)
	@param {String} [popUpContent=] - Text for the feature's popup. If not provided, will default to the location's display value. Can contains "{0}", that will be replaced by the location's Display Value
	@param {String} [iconText=] - Text to show on the feature's icon. If not provided, will default to the location's display value.
	@returns {object} GeoJSON Feature collection Object
**/
function getFeatureObject (locationGr, popUpContent, iconText){
		popUpContent = popUpContent || locationGr.getDisplayValue();
		iconText = iconText || locationGr.getDisplayValue();

		return {
			"geometry": {
				"type": "Point",
				"coordinates": [
					parseFloat(locationGr.longitude),
					parseFloat(locationGr.latitude)
				]
			},
			"type": "Feature",
			"properties": {
				"popupContent": gs.getMessage(popupContent, [locationGr.getDisplayValue()]),
				"iconText" : iconText,
				"locationId" : locationGr.getUniqueValue()
			}

		};
	}

Then we use those functions when looping on the featureGa records to generate the GeoJSON:

	// get the GeoJSON object
	var geoJSONobj = getGeoJSONFeaturesCollectionObject();

	// for each feature
	while (featureGa.next()){
			// set the popup content from the options, ot use the displayValue if not set
			var popupContent = options.feature_popup_content || featureGa.getDisplayValue();
			
			// get the feature object
			var featureObj = getFeatureObject(
				featureGa[locationFieldName].getRefRecord(), /*get the referenced location record*/
				popupContent, 
				featureGa.getAggregate('COUNT') /*use the count as the iconText*/
			);

			// add in the GeoJSON features
			geoJSONobj.features.push(featureObj);
		}
	// set the geoJSON in the data, so it can be used on the client script	
	data.geoJSONobj= geoJSONobj;

Don’t forget to add the options…

As you may have notice, we use the widet’s options to set the table, the fields, and so in the server script. You need to add the following options in the Option Schema of the widget:

   {
      "hint":"Name of the table to show as features on the map",
      "name":"features_source_table",
      "section":"other",
      "default_value":"sys_user",
      "label":"Features Source Table",
      "type":"string"
   },
   {
      "hint":"Name of the field that reference the location on the table shown as features on the map",
      "name":"feature_location_field",
      "section":"other",
      "default_value":"location",
      "label":"Feature location field",
      "type":"string"
   },
   {
      "hint":"Query string to apply on the table shown as features on the map",
      "name":"feature_table_query",
      "section":"other",
      "default_value":"location.nameSTARTSWITHLausanne",
      "label":"Feature table query",
      "type":"string"
   },
      {
      "hint":"Supports {0}, that will be replaced by the location display value. Supports HTML.",
      "name":"feature_popup_content",
      "section":"other",
      "default_value":"This is the feature '{0}'",
      "label":"Feature popup content",
      "type":"string"
   }

Display the features on the map

Now that we have a geoJSON availlable, we need to handle it in the client script. For this we will use the API geoJSON function and we will define onEachFeaturefunction that will set up the popup content and trigger the function clickActionwhen the feature is clicked. We will also define pointToLayer to draw an icon and display the iconText on the map.

	var geoJSONobj = c.data.geoJSONobj;
	L.geoJSON([geoJSONobj], {

		onEachFeature: function(feature, layer) {
			// prepare the popup content with the feature's properties
			var popupContent = "";
			if (feature.properties && feature.properties.popupContent) {
				popupContent += feature.properties.popupContent;
			}
			// set the popup content and call clickAction on click
			layer.bindPopup(popupContent).on('click', clickAction);
		},

		pointToLayer: function (feature, latlng) {
			// prepare the icon text
			var iconText = "";
			if (feature.properties && feature.properties.iconText) {
				iconText = feature.properties.iconText;
			}
			
			// create a DIV icon.
			var myIcon = L.divIcon({ 
				className: 'map-label-content', /*important to style it with CSS*/
				iconSize: [29,29],
				html:iconText /*this is the text shown on the map*/
			});
			
			// return a marker with the icon
			return L.marker(latlng, {icon: myIcon});
		}
	})
		.addTo(map);
	
	function clickAction(e) {
		// center on the clicked feature
		map.setView(e.target.getLatLng(),map.getZoom());
	}

Then (and this is important, otherwise it doesn’t work), we need to define the CSS code for our icon (the one with the class name map-label-content). You can drop this code in the CSS section of the Widget:

.map-label-content {
  background:red;
   border:5px solid rgba(255,255,255,0.5);
  text-align: center;
  position: absolute;
  overflow: hidden;
  background-repeat: no-repeat;
  background-position: center;
  color: #fff;                    // icon color
  width: 29px;
  height: 29px;
  border-radius: 50%;             // make a circle
 /* line-height: 22pt;*/
  font-size: 15px;
  font-family: 'FontAwesome';     // anything goes
  filter: drop-shadow(2px 2px 2px rgba(0,0,0,0.5));
}

The CSS is probably not perfect, but it does the job. If there is any CSS freaky around that have hints for improvements, please feel free to contact me 🙂.

A simpler alternative….

If you want something simpler, without displaying the number of records on each location, you can replace the content of the function pointToLayer with this code:

pointToLayer: function (feature, latlng) {
	/* The simpler alternative*/
	return L.circleMarker(latlng, {
		radius: 8,
		fillColor: "#ff7800",
		color: "#000",
		weight: 1,
		opacity: 1,
		fillOpacity: 0.8
	});
}			

You can then also drop the CSS part for map-label-content

Enable interaction with the ServiceNow Portal

Trigger an event from the map, when cliking a feature

The last addition to our map widget is to broadcast an event when a feature is clicked.

To do so, you can simply add this line of code in the clickAction function in the client script of the widget:

	// trigger event
	$rootScope.$broadcast('mapFeatureClick', e.target.feature.properties.locationId);

This will send an event mapFeatureClick with the sys_id of the location.

Now the map widget is ready, it is time to start preparing the widget responsible for the list and then put them together on a page

A quick and dirty list widget

For our list widget, we will clone the existing widget “Simple List” (widget-simple-list).

⚠ To avoid the handling the script parts that are using ServiceNow functions that are not availlable in scoped application, I strongly suggest to set your scope to global. Otherwise prepare yourself to adapt the Simple List widget clone to make it work in a scoped application…

So, make sure to be in the global scope and clone the “Simple List” widget to “List linked to map”.

Then add a listener in the client script of you new widget, to react when mapFeatureClick is broadcasted:

	$rootScope.$on('mapFeatureClick', function(event,data) {
		c.data.locationFilter =  data;
		c.server.update();
	});

This will set a new variable locationFilter in data.

Then we need to modify the server script to use this locationFilter to filter the records that are shown on the list:

/* to insert just after line 30:
...
if (input && input.filterText)
	gr.addEncodedQuery(options.display_field + "LIKE" + input.filterText)
*/
if (input && input.locationFilter)
		gr.addQuery('location', input.locationFilter);

/*
options.title = options.title || gr.getPlural();
...
*/

You can then save the widget.

Creating the portal page and test it

The last step is now to create a simple portal page and add the two widgets to it.

Set the list widget options to query the user table (sys_user) and select the primary and secondary fields.

Then make you have users in the correct location and test you page. The list will be filtered according the location you select on the map.

Conclusion

In this article we created a basic map widget, that can be used to interact with the service portal. There is plenty of room for improvements and for adding extra features, but I believe it is a good starting point.

I enjoyed digging in the geo data and map rendering world and I will probably follow up this article with other implementations, like positionning the map when a record is selected in a list, or displaying a custom floor plan and so on. So stay tuned 😉

Please leave you comments or questions below.

ℹ All the code for the map widget is availlable in GitLab.

⚠ IMPORTANT Remarks about OpenStreetMap server usage

As you probaly noticed, we are using the OpenStreetMap server to get the Tiles for our map. This is perfectly fine for some tests and for playing around, but there are some points that need to be considered if this is going to be used “in real life”.

The OSM foundation policy ⁹ states:

We are in principle happy for our map tiles to be used by external users for creative and unexpected uses – in contrast to most web mapping providers, which insist that you use only their supplied API.

However, OpenStreetMap’s own servers are run entirely on donated resources. They have strictly limited capacity. Heavy use of OSM tiles adversely affects people’s ability to edit the map, and is an abuse of the individual donations and sponsorship which provide hardware and bandwidth. As a result, we require that users of the tiles abide by this tile usage policy.

Therefore I would recommand to use a commercial Tile server or even to setup your own Tile server for your maps. You can find a list of Tile servers here ¹⁰ and some information about setting up a Tile server here ¹¹.

The plugin “Transformation Service Plugin” provides a transfomer API that allows to process JSON or XML data by applying transformations and rules and returning a key/value object with the result.

We will see in this post how it work and what are the limitations and go through a few examples.

Before going further, make sure that the plugin “Transformation Service Plugin” (com.glide.transform) is activated in your instance. If not activate it.

Overview of the API

There are in fact 3 APIs designed to work together to achieve the transformation of the data.

The 3 APIs are:

• Transformer API, that provide the necessary functions to perform the transformation and retrieve the results;
• TransformerDefinition API, that allows to define the transformation, using a set of rules and a path;
• TransformerRuleList API, used to defined the transform rules to apply.

In a nutshell, you need to create all the transformation rules with TransformerRuleList, add the rules list to the TransformerDefinition and use the this definition with Transformer to actually process and transform the data.

Test case

For this post, we will use data coming from the user table, via a REST api call.

For the sack of simplicity, we will connect to the same instance. The goal here is just to get the data in a JSON format and play with the transform functionnality.

If necessary, for the REST message creation, you can have a look to the post about Using Remote Tables in Service-Now, as we are reusing the message here.

From now, we will aways use the following code to get the data with the subsequent examples:

var r = new sn_ws.RESTMessageV2('x_12270_remote_tab.my users', 'Get');
var response = r.execute();
var responseBody = response.getBody();

As a result, we get a JSON like this one, containig all the fields from the user table in the variable responseBody:

{
  "result": [
    {
      "calendar_integration": "1",
      "country": "",
      "user_password": "jF9fbZrY7c",
      "last_login_time": "2019-04-05 22:16:30",
      "source": "",
      ....
    },
	.....
  ]
}

Transformation rules

The first step is to define the transformation rules.

In our scenario we will start with rules to :

• Concatenate the first_name and last_name and add a String “User " in front;
• Replace the “email” user name by stars (”***"), but keep the domain part (“user@domain.com” becomes “***@domain.com”);
• Define a “type”, that is either ACTIVE, INACTIVE, based on active field;
• Use a few more fields as it

This gives us the following code, wrapped in a function getTransformerRuleList:

function getTransformerRuleList () {
var transformerRuleList = new sn_tfrm.TransformerRuleList()
  .fromJSON() /* indicate it is from JSON*/
  .setName('Margin per users') /*name of the rule list*/
  /* Rules for user concatenated name */
  .addRule('first_name', '$.first_name')
  .addRule('last_name', '$.last_name')
  .addRule('user')
  .thenConcat('User ')
  .thenConcatSymbol('first_name')
  .thenConcat(' ')
  .thenConcatSymbol('last_name')
  /* Rules for email */
  .addRule('email', '$.email')
  .thenSplit('@', '***@$2')
  /* Rules for active field*/
  .addRule('active', '$.active')
  .thenApplyMap({'true': 'ACTIVE', 'false':'INACTIVE'});
  
  return transformerRuleList;
}

The .fromJSON() is here to indicate that we will parse a JSON source. We would use .fromXML() in case of an XML source.

Then the .setName()is used to give a name to the rule list.

For the rules themself, the logic is always to add a new rule with .addRule() where we give the resulting name and then where the value is coming from in the source. For example .addRule('first_name', '$.first_name').

After the .addRule(), we can add one or several .thenSomething method to further modify the value, like for example concatenate with .thenConcat, map with .thenMap and so on. You can find the full list in the API documentation.

executing the transformation

Now that the rules are defined, we can create a TransformerDefinitionand start the transformation with Transformer.

// Create a transformer definition and use the rule list and the record path 
var path = '$.result.*';  // all the records in the JSON are below "result"
var transformerDefinition = new sn_tfrm.TransformerDefinition(getTransformerRuleList(), path);
 
// Instantiate the transformer object.
var transformer = new sn_tfrm.Transformer(transformerDefinition, responseBody); 

// Transform all the records of the source, push them in array results and display the the row
var results = []; 
while (transformer.transform()) { 
  var row = transformer.getRow() 
  results.push(row);
  gs.info(JSON.stringify(row));
} 

transform()is executing the transaction for the next row and getRow() retrieve the row, in the form of an object with key-value pairs, as defined in the rule list.

Calculation failure

I wanted to explore the calculation functions provided and see how it works. Unfortunatly I couldn’t make them work when involving two differents elements from the source.

For example, in order to play with the calculations, I added some fields to the user table:

• Two currency fields
  • u_invoiced_price_per_hour
  • u_cost_per_hour
• and on integer field:
  • u_hours_by_day

Then I tried to calculate the margin price for a user by substracting the u_cost_per_hour from u_invoiced_price_per_hour.

According the documentation it can be achieved by adding the following code to the getTransformerRuleList function:

/* Rules for margin */
.addRule('margin', '$.u_invoiced_price_per_hour')
.thenSubtract('$.u_cost_per_hour');

Unfortunatly it doesn’t work and return errors like this one:

Evaluator: java.lang.NumberFormatException
   Caused by error in script at line 21

     18: } 
     19: 
     20: function getTransformerRuleList () {
==>  21:     var transformerRuleList = new sn_tfrm.TransformerRuleList()
     22:         .fromJSON() /* indicate it is from JSON*/
     23:         .setName('Margin per users') /*name of the rule list*/
     24:         /* Rules for user concatenated name */

java.math.BigDecimal.<init>(BigDecimal.java:497)
java.math.BigDecimal.<init>(BigDecimal.java:827)
com.glide.transform.adapter.CalculationAdapterRule.<init>(CalculationAdapterRule.java:222)
com.glide.transform.adapter.CalculationAdapterRule.createMultiplicationAdapterRule(CalculationAdapterRule.java:60)
com.glide.transform.transformer.AdapterRuleBuilder.thenSubtract(AdapterRuleBuilder.java:78)
com.glide.transform.transformer.js.TransformerRuleList.jsFunction_thenSubtract(TransformerRuleList.java:85)
sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
java.lang.reflect.Method.invoke(Method.java:498)
... 

I try various syntaxes, I try adding a parseInt()and so on, but I couldn’t make it work.

The only way it work was to replace the '$.u_cost_per_hour' by a number, like in the code below, but this would not by useful in our case.

/* Rules for margin */
.addRule('margin', '$.u_invoiced_price_per_hour')
.thenSubtract(15); /*.thenSubtract('$.u_cost_per_hour');*/

Alternative

Bases on this tests, I have the feeling that simply parsing the JSON and performing the necessary transformation directly would be easier and more flexible.

For example, we can achieve the same without using the Transformation Service Plugin with a script like this one:

// parse the response
var responseObj = global.JSON.parse(responseBody);

// get the records/rows inside the "result"
var records = responseObj["result"]

var altResults = [];

// Loop all records[i]
for (var i = 0; i < records.length; i++){
    var resultObj = {};
    resultObj.first_name = records[i].first_name;
    resultObj.last_name = records[i].last_name;
    resultObj.user = "User " + records[i].first_name + " " + records[i].last_name;
    // email
    var email = "";
    if (records[i].email.indexOf('@') > -1 ){
        email =  "***@" + records[i].email.split('@')[1];
    }
    resultObj.email = email;
    // active field
    var active = "ACTIVE";
    if (!records[i].active){
        active = "INACTIVE";
    }
    resultObj.active = active;
    
    // margin
    invoicePriceHour = parseInt(records[i].u_invoiced_price_per_hour);
    resultObj.u_invoiced_price_per_hour = invoicePriceHour;

    costHour = parseInt(records[i].u_cost_per_hour);
    resultObj.u_cost_per_hour = costHour;
    
    resultObj.margin = invoicePriceHour - costHour;

    altResults.push(resultObj);
    gs.info(JSON.stringify(resultObj));
} 

It is quite straightforward and easy to follow for any ServiceNow developper.

Performances

Also it seems that using Transformation Service Plugin is a bit slower than the JSON parsing alternative.

To figure out how much slower exactly, I added some code to record the time before and after the “transformer” script and the “parser” script and calculate the duratio in milliseconds. Here are the results:

transfomerStart=1592997620426, transfomerEnd=1592997620556, total=130
parserStart=1592997620556, parserEnd=1592997620581, total=25

I ran it several time and get always similar results, with the “transformer” script running about 5 times slower the the “parser” script.

Conclusions

My guess is that it will still be improved and the issues will resolved, but for the time being, unless there is a very specifc reason, I would avoid using this plugin.

For example, it is a pitty that I could not make the calculation work. I odn’t know if I am doing something wrong or if the functionnality is somehow broken, but this would be very usefull.

It is not possible to handle conditional cases by setting values based on the values of other fields.

Also when performing mapping, there is no way to reject the value in case it is not in the mapping definition. similarly, there is no possibility to use a default value in such case.

In my opinion, it is (still?) not as flexible and versatile as using a JSON (or XML) parser directly and adding the necessary code to perform all the concatenations, controls, mapping and calculation directly.

However, I am speaking from my point of view and having in mind the transformations I need to perform regularly. But there should be use cases where this plugin is usefull and where it would be advantageous to use it, but I am currently not aware of them.

References

⚠ When I last checked I noticed that the current documentation for the API is not 100% accurate. For example .fromJSON() and .fromXML() are not detailed (they are just mentionned in the introduction) and in the examples there is sometime methods that doesn’t exist, like a .addMultiply. Also the examples involving calculation using elements of the source are not working well, as we saw above.

1. ServiceNow documentation, Transformer API, accessed 2020 06 22
2. ServiceNow documentation, TransformerDefinition API, accessed 2020 06 22
3. ServiceNow documentation, TransformerRulesList API, accessed 2020 06 22
4. complete script snippet can be accessed here

Since the Orlando release, it is possibe to use the Studio to develop Applications in the Global Scope.

We will see in this post how to achieve this and what are the limitations compared to scoped applications in the Studio.

Why use the Studio for Global Apps?

Before jumping in the how, let’s take a minute to summarize the why would we use the Studio for global applications.

Using the Studio offers several advantages for the developpement:

• Leverage the publication of the apps, instead of using update sets;
• Apply protecttion to the application’s assets: you can grab for example a change done to incident and protect it
• Use the Studio interface for developpment
  • Create new files from Studio
  • Use the Application Explorer
  • Code Search
  • Work on multiple files with the tabbed interfaces
  • and so on…

Enable the global scope in the Studio

First step is to enable or allow the global scope in the Studio.

To do so, we need to add a system property: set (or create of it do not exist) the system property sn_g_app_creator.allow_global and set it to true.

Let’s create a Global application

To create a Global application, go to the System Applications - My Company Applications and click Create New.

Then fill the Name, the description and under Advanced settings choose Global. Then click Create.

You can then continue the wizard as with a Scoped application or just click Continue in Studio (Advanced) if you don’t want to create roles, tables, etc.. now.

Adding existing files

In the studio, you can create new files or you can also import existing files from the Global Scope into your application.

When adding existing files, there are three options:

• Add by update set: this will import the content of the udpate set in the app
• Add a table
• Add by name: providing the name of the element to add in the app

Limitations

There is no source control availlable on Global Application. The reason is that it would take the instance name and then can cause troubles when deploying somewhere else. Also the way it work now is that it deploy all the files and doing do in the Global can lead to important files to be overwritten and so on.

But this will change with the Paris release: ServiceNow will offer Git repository support for Global Scope via ‘delta loading’. The delta will avoid overwritting of essential files.

Working with the Visual Studio extension

In my tests, I could not edit the existing files added to the application from the Visual Studio. How ever, I could edit files that were created from the applications.

References

1. Chuck Tomasi, NOWCommunity Live Stream - Topical Deep Dive - Global apps in Studio, broadcasted 2020 04 23
2. ServiceNow documentation, Allow global application development in Guided Application Creator, accessed 2020 06 15
3. ServiceNow documentation, Global application file management, accessed 2020 06 15

This overview is mostly a coming from the breakout presentation done by Peter Bell during knowledge 2020.

Currently this feature is not available in the platform but is part of the ITAM plugin. However it will likely be available in future releases like Paris or Quebec.

In the meantime, it is possible to activate GlideQueryin your personal instance. See below the instructions to do so.

There is also a Cheat Sheet available for help you playing around with this functionnality.

What is GlideQuery

• GlideQuery is Server script API
  • it consists of 2 global script includes:
    • GlideQuery, to which we can have a look (non protected)
    • GlideQueryEvaluator, which is protected, therefore it is not possible to have a look at it.
• It is said that it use GlideRecord under the hood, probably inside the GlideQueryEvaluator script
• It also replace GlideAggregate in some cases (in particular for counting records)
• it is 100% JavaScript.

So it will not replace GlideRecord, but it proposes an additional layer on the top of it, that offers several benefits to the developers. Mainly it should reduce the likelihood of errors and mistakes when manipulating GlideRecord and make it’s usage clearer and easier.

Three principles of GlideQuery

Peter Bell states that GlideQuery has 3 principles, that are:

• Fail fast: runs into errors as soon as possible, offering a quick feedback loop
• Be JavaScript: behave like a normal JavaScript library. The GlideRecord is sometime confusing and behave more like Java.
• Be expressive: allows to do more with less code

We will se below more in details what that means.

Fail fast

By “Fail fast” it means that the query should run into error if anything is potentially wrong and therefore this can be spotted and corrected early. For example:

• Field name checking
• Choice value checking
• Type checking
• Check if any Business Rule rejects the update/insert

Here below are some examples that shows the differences between GlideRecord and GlideQuery

Field Name Checking

GlideQuerychecks that the field name used in the query are valid and if not it will raise an error.

For example, running the following code with GlideRecord, it will delete all the records from the Users table, even if the field activated is wrong:

var gr = new GlideRecord('sys_user');
gr.addQuery('actived', '!=', true);
gr.query();
gs.info(gr.getRowCount());
gr.deleteMultiple();

If we run the equivalent with GlideQuery, it will fail and give an error instead:

new GlideQuery('sys_user')
	.where('activated', '!=', true)
	.del();

This will return an error:

*** Script: Unknown field 'closed_date' in table 'task'. Known fields:
[
  "parent",
  "made_sla",
  ...
]

Choice value checking

GlideQueryis also checking for the choice value when choice fields are involved in the query.

For example, running the following code with GlideRecord, it will not return anything.

var gr = new GlideRecord('task');
gr.addQuery('approval', 'donotexist'); // we use an invalid value for the choice field 'approval'
gr.query();
while (gr.next()) {
	gs.info(gr.getDisplayValue());
}

If we run the equivalent with GlideQuery, it will fail and give an error instead:

var tasks = new GlideQuery('task')
	.where('approval', 'donotexist') // we use an invalid value for the choice field 'approval'
	.select('number')
	.forEach(gs.log);

This will return an error:

*** Script: Invalid choice 'donotexist' for field 'approval' (table 'task'). Allowed values:
[
  "not requested",
  "requested",
  "approved",
  "rejected",
  "cancelled",
  "not_required",
  "duplicate"
]: no thrown error

Strangely, it seems to work only with choice fields that have String value. For example this code do not raise any error, despite the state 8 doesn’t exist

var tasks = new GlideQuery('task')
	.where('state', 8 /*do not exist!*/)
	.select('number')
	.forEach(gs.log);

Type checking

GlideQueryis also checking if there the value is of the correct type. For example:

var tasks = new GlideQuery('task')
	.where('approval', 3) // we pass an Integer instead of a String
	.select('number')
	.forEach(gs.log);

Will return an error:

** Script: Unable to match value 3 with field 'approval' in table 'task'. Expecting type 'string': no thrown error
Root cause of JavaScriptException: org.mozilla.javascript.NativeError

Check if any Business Rule rejects the update/insert

This is another difference with GlideRecord: when a Business Rule abort the insert or update action, then the script would continue, ignoring this error. With GlideQuery, it would rather stop.

For example, running the following code with GlideRecord, it will continue executing, despite that a business rule aborted the action due to start date being after the end date.

var gr = new GlideRecord('change_request');
gr.get('c83c5e5347c12200e0ef563dbb9a7190');
gr.setValue('work_end', '2016-01-01');
gr.setValue('work_start', '2020-01-01');
gr.update();

gs.info("executing this line?"); //yes, it will execute this line despite the error in the Business rule preventing the start data after the end date

If we run the equivalent with GlideQuery, it will fail and give an error instead:

new GlideQuery('change_request')
	.where('sys_id', 'c83c5e5347c12200e0ef563dbb9a7190')
    .update({
    	work_end: new GlideDateTime('2016-01-01'),
    	work_start: new GlideDateTime('2020-01-01')
    });

gs.info("executing this line?");

This will return an error:

*** Script: {
  "message": "Failure to update table",
  "table": "change_request",
  "lastGlideError": "Operation against file 'change_request' was aborted by Business Rule 'Actual Start/End Date Validation^c83c5e5347c12200e0ef563dbb9a7190'. Business Rule Stack:Actual Start/End Date Validation",
  "changes": {
    "work_end": {},
    "work_start": {}
  }
}: no thrown error

Be JavaScript

Stringly typed values

WIth GlideRecord there is frequently issues with the type of value returned. For example:

var gr = new GlideRecord('sys_user');
gr.addQuery('first_name', 'Abel');
gr.query();

if (gr.next()) {
    gs.info(gr.first_name); // -> Abel
    gs.info(gr.firt_name === 'Abel'); // -> false 🤔
    gs.info(typeof (gr.first_name)); // -> object
}

The reason is that the first_nameis a java object. Another example with GlideRecord:

var gr = new GlideRecord('sys_user');
gr.query();
if (gr.next()) {
	if (!gr.getValue('active') { // will return "0" or "-1" as string, and it evaluated always as true...
		//doSomething(gr); 
	}
}

Last example with GlideAgregate

var taskGa = new GlideAgregate('task');
taskGa.addAggregate('COUNT');
taskGa.query();
taskGa.next();
var rowCount = taskGa.getAggregate('COUNT'); // -> return a String ("123")

// With GlideQuery
var rowCount = GlideQuery('task').count(); // -> return a number (123)

With GlideQuery all this example are solved: it return a javascript object, where the key is the field name and the value the actual value of the field:

var gr = new GlideQuery('task')
	.whereNotNull('parent');
	.selectOne('description', 'active', 'parent.urgency')
	.get()
gs.info(JSON.stringify(gr));

/* returns
{
  "description": null,
  "active": false,
  "parent": {
    "urgency": 3
  },
  "sys_id": "801a087adba52200a6a2b31be0b8f520"
}
*/

Be expressive

For reading the data, there is Stream, that apply when reading multiple records and Optional, used for a single record.

Here below are code examples that shows some of the methods in action.

Example with map and forEach

new GlideQuery('sys_user')
	.whereNotNull('name')
	.select('name')
	.map(function (user) {return user.name.toUpperCase(); })
	.forEach(gs.log);

// will return a list of name in upper case

Example with some and every

var hasOnlyShortDescription = new GlideQuery('task')
	.whereNotNull('description')
	.select('description')
	.every(function (task) { return task.description.length < 10; })
// checks that all records match the condition

var hasLongDescriptions = new GlideQuery('task')
	.whereNotNull('description')
	.select('description')
	.some(function (task) { return task.description.length < 1000; })
// checks that at least one record matched the condition

Examples with insert, update, delete

// Insert
new GlideQuery('sys_user')
	.insert({
    	active: true,
    	name: 'Sam Meylan',
    	city: 'Geneva'
	})
	.get();

// delete
new GlideQuery('task')
	.where('priority', 5)
	.disableWorkflow() // disable the business rules
	.deleteMultiple();

// update
new GlideQuery('incident')
	.where('sys_id', id)
	.update({priority: 1});

new GlideQuery('incident')
	.where('priority', '>' 2)
	.updateMultiple({order: 1});

Examples with aggregation

var companyCount = new GlideQuery('core_company')
	.where('city', 'Berlin')
	.count();

var maxReopenCount = new GlideQuery('incident')
	.where('priority', 3)
	.max('reopen_count')
	.orElse(0);
// will return the max count or 0 if there is no

new GlideQuery('task')
	.where('active', true)
	.groupBy('priority')
	.aggregate('sum', 'reassignment_count')
	.having('sum', 'reassignement_count', '>', 4)
	.select()
	.toArray(10)
/* return
[
  {
    "group": {
      "priority": 1
    },
    "sum": {
      "reassignment_count": 11
    }
  },
  {
    "group": {
      "priority": 2
    },
    "sum": {
      "reassignment_count": 3
    }
  },
  ...
  */

Flags

Flags are additional indicators that can be added to the field name to request thinks like the display ($DISPLAY) value or the currency code ($CURRENCY_CODE).

new GlideQuery('sys_user')
	.select('company$DISPLAY')
	.forEach(doSomething);

new GlideQuery('core_company')
	.selectOne('market_cap', 'market_cap$CURRENCY_CODE')
	.get()

Complex queries

Complex queries are queries involving OR conditions or nested conditions.

For example with GlideRecord:

var taskGr = new GlideRecord('incident');
taskGr.addQuery('active', true)
	.addCondition('priority', 1)
	.addOrCondition('severity', 1);

How will this be evaluated? it is ambiguous and it could be :

1. (active = true AND priority = 1) OR severity = 1
2. active = true AND (priority = 1 OR severity = 1)

The correct answer is the second one. With GlideRecord, OR has priority over AND.

With GlideQuery, the ambiguity is reduced and things are clearer:

// active = true AND (priority = 1 OR severity = 1)
new GlideQuery('incident')
	.where('active', true)
	.where(new GlideQuery()
          .where('priority', 1)
          .orWhere('severity', 1)
          )
	.select('description', 'assgined_to')
	.forEach(doSomething)

// manager is NULL OR ( title = 'Vice President' AND state = 'CA')
new GlideQuery('sys_user')
	.whereNull('manager')
	.where(new GlideQuery()
          .where('title', 'Vice President')
          .orWhere('state', 'CA')
          )
	.select('name')
	.forEach(doSomething)

The main difference is the use of a GlideQuery inside the GlideQuery. This force the parenthesis explicitly in the query.

performance

The use of the `GlideQuery’ add an overhead of about 4% to 6%, mainly due to the conversions done from java to javascript.

But we need to keep in mind that in many cases we would do this conversions anyway after the query, when using the data retrieved from the database.

Also it force good practices from a performance point of view. For example, when querying for a single record with GlideRecord, we should add .setLimit()but it is often forgotten. GlideQueryuses selectOne() for this purpose.

Also the getRowCountshould not be used to count the record, as the underlying query to the database will query all the records. The GlideAggregatewith a countshoud be used instead. GlideQueryoffers here an easiest way to achieve this with .count().

Immutability and reuse

The GlideQueryis an immutable object. This means that it can be passed to a function and we don’t care what the function is doing with it, unlike with GlideRecord.

It allows also to reuse the query and extend it. Here below some examples:

var highPriorityTasks = new GlideQuery('task')
	.where('active', true)
	.where('priority', 1);
generateReport(highPriorityTasks);
notifyOwner(highPriorityTasks);

var avgReassignmentCount = highPriorityTasks
	.avg('reassignment_count')
	.orElse(0)

How to enable it on your instance (for testing)

So now that we went through a lot of explanations, you will probably want to try by yourself. As stated at the beginning, it is (still) not included in a vanilla instance, but it is part of the ITAM plugin.

Luckily, despite being part of the ITAM plugin, it is possible to enable GlideQuery on your instance and play with it.

Do to so, run the following script:

⚠Try this in your personal instance only. I would not recommend to use this in a productive environment at the moment. It will likely be evolve and will eventually be integrated in Paris or Quebec release.

var pluginArr = ['com.sn_glidequery'];
var pluginMgr= new GlideMultiPluginManagerWorker();
pluginMgr.setPluginIds(pluginArr );
pluginMgr.setProgressName("Plugin Installer");
pluginMgr.setBackground(true);
pluginMgr.start();

Checking the code

Now that is it installed, you can go in the script includes and look for the GlideQuery script include. It is open and you can read all the code. It is quite interesting well documented. It can also gives you some insights about what can be done and how to use it.

Cheat Sheet

There is a Cheat Sheet available for help you playing around with this functionnality.

References

1. Peter Bell, breakout GlideQuery: A modern upgrade to GlideRecord CCB3052, accessed 2020 06 12
2. Jace Benson, What is GlideQuery, 2020 04 28

Since the New York release, ServiceNow offers a new functionality called remote tables.

Remote tables allows to query and retrieves data from other systems, via REST/SOAP and use them almost seamlessly in service-now.

The remote table can be used like a standard, local, table:

• They can be queried by script;
• We can see the records in lists or in forms;
• Reports can be run on the data;
• They can be used as reference from other tables (both local or remote tables);
• They support, like standard tables, sorting, aggregating and filtering like internal tables;

The obvious case is to retrieve data from a remote system, but there is nothing that prevent us to also use local tables or a mix of remote and local tables and present them as one remote table. We can also see the remote tables like a kind of enhanced database view, that allows for example to :

• aggregating data from multiple sources, both local or remote;
• Making calculations;
• Applying logic and complex conditions;

There is also an option to cache the data that has been retrieved for a certain time, to reduce the load and improve performances.

As you can see, Remote tables are a nice feature to use external data in ServiceNow and have them always up to date. It can be use in numerous scenario where external data need to be always up to date and when it is OK to have it read-only in ServiceNow.

In this article, we will play around and try different use of the remote tables. It will of course not cover all the use cases but it will give a good overview of what can be achieved.

The different use cases

For this test case, we will link an external table to ServiceNow using the remote table functionality.

As a first step, we will link the user table from an ServiceNow instance, using REST. We will include a few fields, including one reference field to Company and see how it react.

Then we will see how to retrieve the Company data in the remote table (like the company name) and see how to include also local data and set custom data in the remote table like calculation result.

Next step will be to use our remote table in a reference field on a local table (like on the incident table) and see what happen

Then we will create a new remote table for companies and see how we can make a reference from a remote table to another table

Finally we will see during all the article what should be done to optimize the query of the remote table, as the default behavior of our setup is to query always all the records.

For the sack of simplicity, both the source table and the remote table are on the same instance. But for make it more realistic (like if we are not querying another ServiceNow instance), we will not rely on the sys_id of the remote user table and we will user the UserId as the key. For the company table, we will use the sys_id, in order to not overcomplicate the example.

Creation the Remote Table

Let’s start by creating our remote rable.

There are three main steps:

• Define the table in the dictionary, where we set the table name, the columns and all the standard options for a table;
• Create a REST message to connect to the source table we want to query;
• Create the related Script Definition that query the source with the REST message and present the data in the Remote Table.

⚠Remote table plugin activation

Before using the Remote tables, check that the corresponding plug-in (com.glide.script.vtable) is activated. If this is not the case, activate it.

Define the table in the dictionary

To define the table in the dictionary, go in the menu System Definition - Remote Tables - Tables and click New.

⚠ there is currently no possibility to create Remote Table from the Studio. You need to create them from the menu and only after this they will appear in the Studio.

Fill in the name and choose whether or not you want to create a module, and check all the usual options for table creation (roles, etc.).

Then you need to add in the Columns list all the fields that you want on your Remote Table.

For now, we will keep it simple with only the First Name, Last Name, Company, Active, Phone and Email.

ℹ The Sys_id field is automatically created. Note that there is not the other usual systems fields like sys_created_on, sys_update_by, etc.

Create the REST message

Let’s create a REST message to the user table in our own instance, using the following settings:

• Endpoint : https://xxx.service-now.com/api/now/table/sys_user
• Authentication: basic - Create a profile and set your own user/password for example
• add an HTTP method: Get
• add the HTTP Query parameter (in the HTTP method);

Create the related script definition

Now the next step is to create a script definition for our new Remote Table. Go to System Definition - Remote Tables - Definitions and click New.

In table select the table you created before and let’s start writing the script that will retrieve the remote records and make them available in the Remote Table.

ℹ You will notice that there is a huge comment at the beginning of the script: it contains the explanation about how to prepare the script and how to use the APIs. I suggest you keep it in your script for reference, as there is not this information elsewhere in the documentation.

Now the goal of the script is to add rows to the Remote Table, using v_table.addRow. This function expect an object containing all the values. The name of each property in the object should match the name of the field defined in the Remote Table.

So let’s write the following script, where we query using the REST message and then build and add the rows to our Remote Table.

(function executeQuery(v_table, v_query) {

	try { 
		// get the REST message
		var message = new sn_ws.RESTMessageV2('x_12270_remote_tab.my users', 'Get');

		// execute it
		var response = message.execute();

		// get the response
		var responseBody = response.getBody();
		var httpStatus = response.getStatusCode();

		// if there is an error, log and return
		if (response.haveError()) {
			v_query.setLastErrorMessage(response.getErrorMessage());
			gs.addErrorMessage(response.getErrorMessage());
			return ;
		}

		// Parse response
		var json = new global.JSON();
		var responseObj = json.decode(responseBody);
		var resultArr = responseObj.result; // all the records are contained in an array 'result'

		for (var i=0; i< resultArr.length; i++){
			//build the row
			var row = {};

			// map fields from the result
			row.first_name = resultArr[i].first_name;
			row.last_name = resultArr[i].last_name;
			row.active = resultArr[i].active;
			row.email = resultArr[i].email;
			row.phone = resultArr[i].phone;
			row.company = resultArr[i].company.value;

			// add the row to the remote table
			v_table.addRow(row);
		}
	} catch(ex) {
		v_query.setLastErrorMessage(ex.message);
		gs.addErrorMessage(JSON.stringify(ex));
	}

})(v_table, v_query);

Now we can test it with the following script (to run in Background script):

var grX_12270RTSRU = new GlideRecord('x_12270_remote_tab_st_remote_user');
grX_12270RTSRU.query();
while (grX_12270RTSRU.next()) {
    gs.info('active: ' + grX_12270RTSRU.getValue('active'));
    gs.info('company: ' + grX_12270RTSRU.getValue('company'));
    gs.info('email: ' + grX_12270RTSRU.getValue('email'));
    gs.info('first_name: ' + grX_12270RTSRU.getValue('first_name'));
    gs.info('last_name: ' + grX_12270RTSRU.getValue('last_name'));
    gs.info('phone: ' + grX_12270RTSRU.getValue('phone'));
}

Also if we open the list of the table, you should see records in it:

So far so good: we can see the data from the ‘remote’ table and use it.

However, if we look carefully, we can see that for the company we only have the sys_id. This is because we do not have the display value in the payload. To get a more user friendly information, like the name of the company, we need to query it and use it in the script definition.

Getting the company name instead of the sys_id

One easy solution that comes to mind to solve this is to query the remote system with another HTTP method in the same REST message as before and get the company name. Let’s see how to do this.

First, let’s create a new HTTP method (in the existing REST message) for the company table, in a similar way that the one for querying the users, but with this endpoint: /api/now/table/core_company/${id} (and set a name like GetCompany and use it the the script below).

Then let’s create a function getRemoteCompanyName to retrieve the remote company and get the name.

function getRemoteCompanyName (id) {
    try {
        // get the REST message
        var message = new sn_ws.RESTMessageV2('x_12270_remote_tab.my users', 'GetCompany');

        // set the id of the company we want to retrive
        message.setStringParameter("id", id);

        // execute it
        var response = message.execute();
        // get the response
        var responseBody = response.getBody();
        var httpStatus = response.getStatusCode();

        // if there is not error, continue
        if (!response.haveError()) {
            // Parse response
            var responseObj = new global.JSON().decode(responseBody);
            var resultObj = responseObj.result;

            // check if the reuslt if ok and return the name
            if (resultObj){
                return resultObj.name;
            }
        }

        // default empty string
        return "";


    } catch (ex){
        gs.addErrorMessage(JSON.stringify(ex));
        return "";
    }
}