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.

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

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

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:

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.
   1. Process its response in the callback-function listed below.
5. The answer variable contains the value return by the getDuration() method.

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:

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:

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);
}