Script Include

Script Includes are used to store JavaScript functions and classes that are executed on the server. Include scripts generally specify either an object class or a function.

tip

Role required: admin.

Create a script include

A script include has a name, a description, and a script itself. Also, it is possible to specify options active or client-callable.

To create a new script include, complete the following steps:

1. Navigate to System Settings → Script Includes.
2. Click New and fill in the fields.
3. Click Save or Save and exit to apply the changes.

Script Include form fields

Field	Mandatory	Description
Name	Y	Specify the script include name. It should match the class name used in the script field. Also, the script include name should be unique and cannot contain spaces.
Description	N	Add a short description of the action.
Active	N	Select this checkbox to activate this script. When selected, the script is executed when it is called; otherwise, it is not executed.
Client callable	N	Select this checkbox to make this script available to call on the client-side scripts.
Disable ACL check	N	Select this checkbox so that the script include does not go through an ACL check when it is executed within the Client Scripts.
Script	Y	Define the server-side script to run when called from other scripts.

When invoking script includes in other server-side scripts, use the ss.importIncludeScript method of the SimpleSystem class, as shown below:

ss.importIncludeScript('EmailHelper');
const helper = new EmailHelper();

Otherwise, the script is not available.

Use cases

Use client callable script includes if you need scripts to use the server-side methods on the client-side. Consider two simple examples of calling a script include from a client-side and server-side.

Use a client callable script include on the forms

---

A use case is a calculation of the time period between two specified values using a specific schedule.

To do so, create a script include with the following parameters:

Field	Value
Name	DurationCalculator
Active	true
Client callable	true
Script	Enter the script below.

Client callable script include

ss.importIncludeScript('AbstractAjaxProcessor');

var DurationCalculator = Class.create();
DurationCalculator.prototype = Object.extendsObject(AbstractAjaxProcessor, {
    getDuration() {
        const start = new SimpleDateTime(this.getParameter('sysparm_start'));
        const end = new SimpleDateTime(this.getParameter('sysparm_end'));
        const scheduleID = this.getParameter('sysparm_schedule');
        const schedule = new SimpleSchedule(scheduleID);
        // value that would be passed to client-side
        return schedule.duration(start, end).getDurationSeconds() * 1000;
    }
});

On the client-side, use SimpleAjax:

1. Create a SimpleAjax instance.
2. Pass the name of the method to be called using the reserved parameter sysparm_name.
3. Pass the values from a form using the sysparm_start, sysparm_end, sysparm_schedule parameters.
4. Call the script include using the getXML(callback) method.
   • Process its response in the callback-function listed below.
5. The answer variable contains the value return by the getDuration() method.

Using script include on the client-side

if (s_form.getValue('start') && s_form.getValue('end') && s_form.getValue('schedule_id')) {

    const calculate = new SimpleAjax('DurationCalculator'); // call script include
    calculate.addParam('sysparm_name', 'getDuration'); // call method
    calculate.addParam('sysparm_start', s_form.getValue('start')); // pass param
    calculate.addParam('sysparm_end', s_form.getValue('end')); // pass param
    calculate.addParam('sysparm_schedule', s_form.getValue('schedule_id')); // pass param
    calculate.getXML(callback);

    function callback(response) {
     | // value received from server-side
        const answer = response.responseXML.documentElement.getAttribute('answer');
        s_form.setValue('duration', answer);
    }
}

Use a client callable script include on the lists

---

Another example is the calculation of list items after filtering.

To do so, create script include with parameters like shown below:

Field	Value
Name	getListItemsCount
Active	true
Client callable	true
Script	Enter the script below.

Client callable script include

ss.importIncludeScript('AbstractAjaxProcessor');
 
var getListItemsCount = Class.create();
getListItemsCount.prototype = Object.extendsObject(AbstractAjaxProcessor, {
    
  getCount() {
    const table_name = this.getParameter('sysparm_table_name');
    const condition = this.getParameter('sysparm_condition_query');
    const list = new SimpleRecord(table_name);
    list.addEncodedQuery(condition);
    list.selectAttributes('sys_id');
    list.query();
    // value that would be passed to client-side
    return list.getRowCount();
  }
  });

The client-side script is the following:

Using script include on the client-side

const queryString = window.location.search;
const urlParams = new URLSearchParams(queryString);

const sAjax = new SimpleAjax('getListItemsCount'); // initialize script include
sAjax.addParam('sysparm_name', 'getCount'); // call method
sAjax.addParam('sysparm_table_name', s_list.getTablesName()[0]); // pass param
sAjax.addParam('sysparm_condition_query', urlParams.get('condition') || '()'); // pass param
sAjax.getXML(callback);

function callback(response) {
    // value received from server-side
    const answer = response.responseXML.documentElement.getAttribute('answer');
    s_list.clearMessages();
    s_list.addInfoMessage(`List items count: ${answer}`, 2000);
}