Script Includes

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

Creating 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, please 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 changes.

Script Include form fields

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

Practical case

You can use client callable script includes in case you need to use server-side methods on the client-side. For more clarity, let us consider two simple examples of calling a script include from:

• a client-side
• a server-side

Using client callable script include on forms

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

For this, let us create script include with parameters like shown below:

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, we use SimpleAjax:

1. Create a SimpleAjax instance.
2. Transfer the called method name using the reserved parameter sysparm_name.
3. Transfer values from a form using the sysparm_start, sysparm_end, sysparm_schedule parameters.
4. Call an include script using the getXML(callback) method.
   1. Process its response in the callback-function listed below.
5. The answer variable will contain 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);
    }
}

Using client callable script include on lists

Another example is the calculation of list items after filtering.

For this, let us 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 code will be 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);
}