Script includes are used to store JavaScript that runs on the server.

Create script includes to store JavaScript functions and classes for use by server scripts. Each script include defines either an object class or a function.

Consider using script includes instead of global business rules because script includes are only loaded on request. See Privacy settings on client-callable script includes and Discovery script includes for more information.

For additional examples of scripts, see Useful scripts.

Script include form

Script includes have a name, description, and, script. They also specify whether they are active or not, and whether they can be called from a client script. View existing or create a new script include using the Script Include form.

To access script includes, navigate to System Definitions > Script Includes.

Table 1. Script include form
Field Description
Name The name of the script include. If you are defining a class, this must match the name of the class, prototype, and type. If you are using a classless (on-demand) script include, the name must match the function name.
API Name The internal name of the Script Include. Used to call the Script Include from out-of-scope applications.
Client callable The script include is available to client scripts, list/report filters, reference qualifiers, or if specified as part of the URL. Client callable script includes are invoked from GlideAjax and require that users satisfy an ACL associated with the script include. When selected, the Access Controls Related Link is available. See Privacy settings on client-callable script includes for more information.
Mobile callable The script include is available to client scripts called from mobile devices.
Sandbox enabled The script include is invoked from the script sandbox, such as a query condition. This method does not require any authentication. For more information about the sandbox, see Configuring Script sandbox property.
Application The application where this script include resides.
Accessible from
Sets which applications can access this script include:
All application scopes
Can be accessed from any application scope.
This application scope only
Can be accessed only from the current application scope.
Active Enables the script include when selected. Deselect the active field to disable the script include.
Description Provides descriptive content regarding the script include.
Script Defines the server side script to run when called from other scripts.

The script must define a single JavaScript class or a global function. The class or function name must match the Name field.
Package The package that contains this script include.
Created by The user who created this script include.
Updated by The user who most recently updated this script include.
Protection policy
Sets the level of protection for the script include:
None
Allows anyone to read and edit this downloaded or installed script include.
Read-only
Allows anyone to read values from this downloaded or installed script include. No one can change script values on the instance on which they download or install the script include.
Protected
Provides intellectual property protection for application developers. Customers who download the script include cannot see the contents of the script field. The script is encrypted in memory to prevent unauthorized users from seeing it in plain text.
Related lists on the form view:
Versions Shows all versions of the script include. Use this list to compare versions or to revert to a previous version. See Versions.
Access Controls Becomes available when the Client callable check box is selected and is hidden from standard script includes. Use to protect a CCSI against unauthorized use when public access is not granted.

Use script includes

Script includes are found under System Definition or System UI. You can call existing script includes from a script or create a new script include.

To create an entirely new script include, you can follow the format of any of the existing script includes. In this example, the name of your script include is NewInclude and there is a single function called myFunction. It is important that the name of the script include match the name of the class, prototype, and type. When you create a new script include and give it a name, the system provides a code snippet with the class and prototype properly set up.

var NewInclude =Class.create();
 
NewInclude.prototype={
  initialize :function(){},
 
  myFunction :function(){<Put function code here>},
 
  type :'NewInclude'};

You could then use the myFunction line like this:

var foo =new NewInclude();
foo.myFunction();

Client-callable script includes

Client Callable Script Includes (CCSI) make the script include available to client scripts, list/report filters, reference qualifiers, or if specified as part of the URL.

Before you begin

Role required: admin

Procedure

  1. Navigate to System Definition > Script Includes.
  2. Select New or select an existing script include for viewing or editing.
    See Use script includes for additional information on writing script includes.
  3. Complete the form and select the Client callable check box.
    A role selector pops up to select a user role and automatically create an Access Control entry. Select a user role and click OK.Select a user role window.
    Note: To disable the role selector window, set the glide.script.ccsi.enable_acl_create_ux to false.

    A new CCSI record with a role-based Access Control is created. The Access Control Related Link becomes available with the selection of the Client calIable check box.

    Displays the Script Include form and Access Controls Related Link when Client callable is selected.

Privacy settings on client-callable script includes

Privacy settings for client-callable script includes (CCSI) determine who can access a client-callable script include.

Private privacy-setting

The private privacy-setting means that guests who access public pages cannot access the client-callable script-include. A private script cannot be executed by a non-logged-in user.

Public privacy-setting

A public privacy-setting means that the client script can be executed by non-logged-in users that create an appropriate HTTP request. This can create a security problem if the client script provides confidential information.

The following script includes remain public by default because Make UI pages public or private need to access them:
  • GlideSystemAjax
  • SysMessageAjax
  • KnowledgeMessagingAjax
  • KnowledgeAjax
  • PasswordResetAjax

Set privacy on all client-callable script includes

Change the privacy setting on all client-callable script includes.

To provide further control over all client-callable script includes, administrators can add the glide.script.ccsi.ispublic property. This property changes the visibility of client-callable script includes by making them all public or private. Configure the property as follows:

Table 2. Configure property
Title Property
Name glide.script.ccsi.ispublic
Type true|false
Value false
Note: To learn more about this property, see Require authentication by default for client-callable script includes [Updated in Security Center 1.3] in Instance Security Hardening Settings.

Change privacy on a single client callable script include

Change the privacy setting for a single client-callable script include by adding the isPublic() function.

The isPublic() setting takes precedence over the glide.script.ccsi.ispublic property. For example, if the property is set to false, making all client-callable script-includes private, and a script sets isPublic() to true, the script is public.

To change the privacy for a single client-callable script include, add the following method to the script include:

isPublic:function(){return[true/false];},
Example
Make the NewInclude client script private. 
var NewInclude =Class.create();
 
NewInclude.prototype={
   initialize:function(){},
 
   myFunction:function(){//Put function code here},
   isPublic:function(){return false;},
 
   type:'NewInclude'};

Security on client callable script includes

Protect your client callable script include (CCSI) against unauthorized use. For all CCSI records which are created a customer application, recommendations display that may help reduce security risk.

When creating a CCSI, the system displays the following security recommendations if they have not yet been configured:

  • Add or define an Access Control, unless the CCSI has public access.
  • Use GlideRecordSecure instead of GlideRecord API for better security, if the script queries the database.

    CCSI security recommendations.

    Note: To disable the security recommendation messages, set the property glide.script.ccsi.customer_scoped.security_msgs_enabled to false in the sys_properties table. The default value is set to true.

See Instance Security Hardening Settings for additional information on security compliance.

Discovery script includes

Discovery script includes define JavaScript classes that you can use to accomplish Discovery tasks.

Note: Users with discovery_admin role can write script includes. Follow best practices for server-side and client-side scripting to prevent security issues. See knowledge article KB0550828 for more information.

Using GlideRecordUtil to Work with GlideRecords

GlideRecordUtil is a utility class that provides methods that are useful for working with GlideRecords during Discovery. Refer to GlideRecordUtil for descriptions of available methods.

Getting a GlideRecord Instance

To get a GlideRecord instance for a given configuration item, and of the correct class and table, use the getCIGR(sys_id) method. For example, the following code gets the GlideRecord of a CI with the sys_id of 2dfd7c8437201000deeabfc8bcbe5d56:
var now_GR = new GlideRecordUtil().getCIGR("2dfd7c8437201000deeabfc8bcbe5d56");
To retrieve any hierarchical table without knowing its class type, use the getGR(base_table, sys_id) method. For instance, to get a GlideRecord for a computer class CI, you might have to distinguish whether it is a computer class, Windows server, or Linux server class. Using this method guarantees a GlideRecord with the correct class. Different classes have different attributes. In this use case, a Windows server has attributes different from a Linux server. The following example shows how to get a GlideRecord in the correct class with its attributes.
var now_GR = new GlideRecordUtil().getGR( "cmdb_ci_computer", "2dfd7c8437201000deeabfc8bcbe5d56");

Getting All the Fields In a GlideRecord

The getFields(now_GR) method returns a JavaScript object, such as a hashmap, of all the fields or attributes that exist in a given GlideRecord.
var now_GR = new GlideRecordUtil().getGR("cmdb_ci_computer", "2dfd7c8437201000deeabfc8bcbe5d56");
var fields = new GlideRecordUtil().getFields(now_GR);
gs.log(fields.join(" ")); // List all the fields that are in a computer CI

Populating GlideRecord Object Fields

The populateFromGR(hashmap, gr, ignore) method enables you to take a GlideRecord object and populate its fields and values into a JavaScript object. The third argument (ignore) is an optional JavaScript object that enables you to exclude certain fields. For example, you may not care about sys_created_by or sys_updated_by fields in a GlideRecord.
var objectToPopulate = { }; 
var now_GR = new GlideRecordUtil().getGR("cmdb_ci_computer", "2dfd7c8437201000deeabfc8bcbe5d56"); 
var ignore = {"sys_created_on": true, "sys_updated_by": true}; 
new GlideRecordUtil().populateFromGR(objectToPopulate, now_GR, ignore); 
// Now the objectToPopulate contains field/value pairs from the computer GlideRecord
The mergeToGR(hashmap, gr, ignore) method enables you to populate a GlideRecord with a field/value-paired object. The ignore argument stops specified fields from being updated. The following code example updates a computer record's name and os fields, but does not update the sys_created_by field:
var now_GR = new GlideRecordUtil().getGR("cmdb_ci_computer", "2dfd7c8437201000deeabfc8bcbe5d56"); 
var obj = {"name": "xyz", "os": "windows 2000", "sys_created_by", "aleck.lin"};
var ignore = {"sys_created_by": true}; 
new GlideRecordUtil().mergeToGR(obj, gr, ignore);
gr.update();

Getting Table Hierarchies

The getTables(table) method returns a list of table hierarchies, as shown in the following example:
var tables = new GlideRecordUtil().getTables("cmdb_ci_linux_server");
gs.log(tables.join(",")); 
// The result would be "cmdb_ci, cmdb_ci_computer, cmdb_ci_server, cmdb_ci_linux_server".

Using DiscoveryException and AutomationException

When writing Discovery sensors and sensor-related scripts, you may want to use DiscoveryException or AutomationException to indicate that an exception has come from Discovery.

The DiscoveryException script include extends AutomationException, which extends the GenericException class. The following example uses DiscoveryException to throw an exception:
function foo() { 
  if(//condition matches) throw new DiscoveryException("The message", "The cause"); }
The first argument takes the message of the exception and the second argument (optional) takes the cause of the exception. You may also want to catch the exception and log it as shown in the example below:
try {
  foo(); 
} 
catch(e) { 
   if(e instanceof DiscoveryException)
     gs.log("A DiscoveryException occurred. It is " + e. getMessage() + " caused by " + e.getCause()); }

The above example also applies for AutomationException. DiscoveryException is typically used to provide exception processing specifically for Discovery, while AutomationException is used for exception processing that applies to both Orchestration and Discovery.