Welcome to the third article in our Advances MID Server Series, where our Technical Architect, Callum Ridley, looks into Advanced MID Server solutions. This time he's explaining Standard MID Server Classes, giving a full description on each, and some advice on what you can do with them.
Introduction
The MID Server’s script environment provides a number of classes available to the developer beyond that of the MID Server Script Includes that you see in platform. If you’ve taken some time to explore the MID Server Script Includes, you’ll probably have noticed that most of them are dedicated to discovery and orchestration. This isn’t all that odd considering the reason that the MID Server exists in the first place.
In this article, we will take a look at the classes available to you as a developer, some of these will be what are known as “ScriptableObjects”, and the others just simple MID Server Script Includes.
What’s a ScriptableObject?
Simply put, a ScriptableObject is a javascript object defined within the Java Rhino environment. It’s surfaced to the javascript environment, but the code that runs is native Java. The most commonly used example of this is GlideRecord. Even in the platform, you’ll never find the code that makes up GlideRecord, this is because it’s a ScriptableObject, defined in the Java element of the platform and surfaced to the javascript environment.
The MID Server also makes a number of these objects available to you, albeit not as numerous as the main platform.
MIDSystem
MIDSystem is the first of these objects. There’s no need to instantiate this object using the new keyword, instead you can think of this as the little brother of GlideSystem. GlideSystem, as you are probably aware, is available in all platform server-side scripts using the variable name “gs”. It’s smaller brother is accessed in a similar fashion, using the variable “ms”. So what can we do with the MIDSystem?
Method
|
Description
|
log(String message)
|
Logs the given message with a standard prefix to indicate that the message was generated by JavaScript.
|
getConfigParameter(String parameter name)
|
Returns the value of the named configuration parameter.
|
include(String script include)
|
Include the MID Server script include with the given name into the current context.
|
getName()
|
Returns the name of the MID Server.
|
getSysID()
|
Returns the sys_id of the MID Server.
|
toJavaScript(Object)
|
Converts the given Java object into the equivalent JavaScript object.
|
Of course, all of that information is available directly from ServiceNow docs pages. I’m not going to cover exactly what each method above does, but there’s a couple worth discussing.
ms.getConfigParameter(String parameterName)
This useful method can get you all sorts of details about the MID Server and the parameters used throughout various things like discovery. As of Vancouver, there are over 400 parameters, I’ve no reason to list them all out here, the script below will log them out into the ECC queue for you if you wish. Some important ones that you’ll probably find yourself using are.
Parameter Name
|
Description
|
url
|
The URL of the instance the MID Server is connected to
|
mid.instance.username
|
Username for authenticating with the ServiceNow instance
|
mid.instance.password
|
Password for authenticating with the ServiceNow instance
|
mid.instance.use_proxy
|
Whether the MID Server connects to the instance via a proxy or not.
|
mid.proxy.host
|
The URL of the instance proxy (if being used)
|
mid.proxy.username
|
The username used for connecting via proxy (if being used)
|
mid.proxy.password
|
The password used for connecting via proxy (if being used)
|
getMIDParameters: function() {
var MIDConfigParameter = Packages.com.snc.commons.MIDConfigParameter;
var arr = MIDConfigParameter.getAll();
var params = {};
for(var i = 0; i < arr.size(); i++) {
var param = arr.get(i);
params[param.getName()] = param.getLabel();
}
return JSON.stringify(params, null, 4);
}
GlideRecord
Yep, you’re old favourite is indeed available in MID Server scripts, there would be very little benefit in telling you about GlideRecord and it’s methods. It’s one of, if not the most used APIs used on the ServiceNow platform, but in MID Server scripts there are a few differences.
Security
GlideRecord in MID Server scripts is actually more akin to GlideRecordSecure, it will respect ACLs on the table you’re querying data from or updating/inserting/deleting data to. What’s very important to understand here is that it does not use the context of the user who triggered the script to execute. All GlideRecord operations performed in a MID Server script are executed by the MID Server user (the one it authenticates to the instance with).
In Practical terms, this means that your MID Server user will need to have the roles required in order make changes to the tables GlideRecord is being used on.
Tip: Ensure you set the “Internal Integration User” & “Web service access only” and field to true on the MID Server user record, that way it will be exempt from licensing.
It does not have direct database access
Unlike it’s platform based twin, GlideRecord on a MID Server does not have access to the underlying database. If you think about it, this makes sense. The MID Server is not hosted in the ServiceNow data centre, and it’d be a incredibly bad idea for ServiceNow to allow database level connections from outside their private network.
To get around this, but still give the developer a familiar API to work with, GlideRecord on the MID Server can be thought of more as a web service, a remote GlideRecord if you will. In fact it actually uses SOAP web services to communicate with the instance. Why do I bother pointing this out? Well as developers we have a duty to be responsible in our development work. Using the MID Server to update ten thousand records is the equivalent of making ten thousand API calls to the platform. This would not be good or responsible.
So yes, you do have access to GlideRecord, but think carefully about what you’re doing with it. If you do need to update multiple records, maybe that could be performed directly on platform as a result of your MID Server scripts output to the ECC Queue, rather than executing directly from the MID Server.
Probe
The MID Server script environment automatically provides you with a variable called “probe” that can be used to interact with the JavascriptProbe that instigated the running of the script on the MID Server. Below are outlined the most common methods that you’ll use.
Method
|
Description
|
getParameter(String paramName, String defaultValue)
|
Get’s a parameter from the probes payload and returns it as a string. defaultValue is optional.
|
getIntParameter(String paramName, Integer defaultValue)
|
Get’s a parameter from the probes payload and returns it as an integer. defaultValue is optional.
|
getBooleanParameter(String paramName, Boolean defaultValue)
|
Get’s a parameter from the probes payload and returns it as a boolean. defaultValue is optional.
|
Most commonly, you’ll find yourself using the probe.getParameter(String paramName, String defaultValue) method. This is the usual method of retrieving parameters from the probes payload. As you can see though, there are some helper methods for getting the value is specific types, integer and boolean. Be careful with these methods though, if the source data does not match the intended type, it may cause an error.
All of these methods are capable of handling encrypted data. That’s data that has been added to the probe using the AutomationAPI. See part 2 of this series if you’re unsure what that means.
ArrayUtil
The ArrayUtil that you may be familiar with from platform server side scripting is also available on the MID Server. This allows you to easily work with arrays, whether they are the Java type, or the JavaScript type. ArrayUtil is already very well documented by ServiceNow.
JSUtil
Again, another API that you might be familiar with from the platform. This one provides lots of useful utility functions to make the life of the developer easier such as checking is a variable is null, converting variables into booleans and xml string escaping to name just a few. Again, JSUtil is fully documented by ServiceNow.
So there we have it, you now know about all of the standard classes available to you in MID Server scripts. In the next post, we’ll be looking at File Management on the MID Server, how we can handle attachments and move files around the file system, this is where we begin to step outside the realm of the standard classes made available to use and begin in earnest getting to grips with “Package” calls.
Thanks Callum for such providing such a valuable list of descriptions, and uses for the different classes. If you're looking to maximise how ServiceNow is supporting your business, UP3 has a team of ServiceNow experts ready to support your digital transformation, take a look at our ServiceNow Managed Service page to see how.