Script Include Patching

The complete server-side logic of b+s Connects for ServiceNow is provided in the form of Script Includes. More precisely, Script Includes that inherit from the AbstractAjaxProcessor. These Script Includes are called from the agent desktop (gadget) via GlideAjax.

It may happen that the Script Includes provided by b+s do not meet your needs. Or a bug has crept in and you do not want to wait for the next release, because unfortunately the ServiceNow certification takes several weeks. In these cases it may be appropriate to overwrite the existing Script Includes. Or as we call it: patch a Script Include method.

danger

We try to make the product as flexible as possible and Script Include Patching is one of the tools that should be used only under extreme conditions. Please contact the b+s Connects for ServiceNow DevOps team in this case. We are happy to help.

Step-By-Step

The following Step-By-Step instructions show an example of how to patch a Script Include. Specifically, the rejectWorkitem method in the AwaProcessor Script Include is patched.

1. Create a new Script Include.

   For example create a Script Include named AwaProcessorPatch, which contains a method called rejectAndTransferWorkitem. Inside the method body, implement your desired logic.

2. Create a new System Property.

   Name it x_busag_cnx.patch.awa_processor.reject_workitem.v1 and set the Value to AwaProcessorPatch.rejectAndTransferWorkitem.

3. Test your implementation with an actual agent login.

tip

In case of problems, check the application log under https://<instance>.service-now.com/syslog_app_scope_list.do.

How it works

When a Script Include is patched, individual functions are overwritten, not entire classes. Script Include methods which can be replaced include the following code:

var patchResult = new PatchProcessor().tryRunPatch(
  this,
  'x_busag_cnx.patch.<script_include>.<method>.<version>'
);

if (patchResult.isPatched) {
  return patchResult.data;
}

Every patchable method passes a scope-wide unique key as the second argument to the tryRunPatch function (x_busag_cnx.patch.<script_include>.<method>.<version>). This argument contains the name of the Script Include (<script_include>), the name of the method contained in the Script Include (<method>) and a version parameter (<version>). To override a Script Include method, the resulting string must be used as the name of a new System Property.

The PatchProcessor then checks whether a System Property exists for the given key. If yes, it checks if a script and a method exist as specified in the Value field of the System Property. Only then, the corresponding method in your Script Include is executed. The return value will be returned to the original Script Include, from where the gadget request will be answered.

caution

The System Property as well as the Script Include must be created in the "b+s Connects for ServiceNow" scope.

Parameters from the gadget

To get to the data that is transferred from the gadget to the Script Include, the instance of the original Script Include is passed directly as a parameter to your Script Include. This means that the known functions like getParameter are directly available:

var AwaProcessorPatch = Class.create();
AwaProcessorPatch.prototype = {
  rejectAndTransferWorkitem: function (originalProcessorInstance) {
    var gaHelper = new GlideAjaxHelper();

    // Get the parameters from the Gadget
    var workItemId = gaHelper.getStringFromParameter(
      originalProcessorInstance.getParameter('sysparm_work_item_id')
    );
    var rejectReasonId = gaHelper.getStringFromParameter(
      originalProcessorInstance.getParameter('sysparm_reject_reason_id')
    );

    // Your logic follows here
  },

  type: 'AwaProcessorPatch'
};

Always query parameters as shown in the example above.

Experience has shown that on some ServiceNow instances a call to the getParameter function returns a Java string instead of a Java Script string. When this occurs, it leads to phenomena that are difficult to debug. For example, obviously correct triple equal checks (===) all of a sudden fail.

System Properties

In order to create a new System Property, navigate to https://<instance>.service-now.com/sys_properties.do?sys_id=-1.

The following default values are recommended by b+s. Some settings may differ for your organization. Please refer to the official ServiceNow documentation.

Name	Description	Recommended value	Required
Suffix	Name of the property you are creating.	patch.<script_include>.<method>.<version>	yes
Application	The application the System Property is part of.	x_busag_cnx *	yes
Name	Defines if client-side scripts can call the Script Include using GlideAjax.	x_busag_cnx.patch.<script_include>.<method>.<version>	yes
Description	Documentation explaining the purpose of the System Property.	n/a **	no
Choices	Comma-separated values for a choice list.	Empty *	no
Type	Appropriate data type contained in the Value field.	string *	yes
Value	Select if the Script Include is executable.	<ScriptInclude>.<MethodName>	yes
Ignore cache	Determines whether to flush this property's value from all server-side caches.	true	yes
Private	Exclude this property from being imported via update sets.	false	yes
Read roles	Defines the roles that have read access to this property.	Empty	yes
Write roles	Defines the roles that have write access to this property.	admin	yes

* Must not deviate from the recommended value | ** Optional but highly recommended

Custom Script Include

In order to create a new Script Include, navigate to https://<instance>.service-now.com/sys_script_include.do?sys_id=-1. Alternatively you can edit an existing one.

The following default values are recommended by b+s. Some settings may differ for your organization. Please refer to the official ServiceNow documentation.

Name	Description	Recommended value	Required
Name	Name of Script Include.	n/a	Yes
API Name	Used to call the Script Include from out-of-scope applications.	n/a	Yes
Client callable	Defines if client-side scripts can call the Script Include using GlideAjax.	false	Yes
Application	The application the Script Include is part of.	x_busag_cnx *	yes
Caller Access	Scoped Application Restricted Caller Access configuration.	-- None --	yes
Accessible from	Specifies the scope(s) that can use the Script Include.	This application scope only	yes
Active	Select if the Script Include is executable.	true	yes
Description	Documentation explaining the purpose and function of the Script Include.	n/a **	no
Script	The logic to execute.	n/a	yes
Protection policy	Manage visibility on other instances.	n/a	yes

* Must not deviate from the recommended value | ** Optional but highly recommended

caution

Make sure that your Script Include returns data in exactly the same form as the original Script Include does. Otherwise you risk gadget crashes.

Upgrades

As with any busy application, requirements change or scale over time. To ensure that the application works even in case of breaking changes, we have versioned Script Include Patches. If the interface changes with an update and your Script Include is no longer compatible, we change the version suffix in the name of the System Property. This means that the default implementation of b+s will be used automatically, so that you have enough time to decide whether your Script Include Patch should be adapted or not used at all.

Such breaking changes are shown in the Changelog.