Versions Compared

Old Version 2

changes.mady.by.user Dina Baksheeva

Saved on

compared with

New Version 3

changes.mady.by.user Dina Baksheeva

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Include scripts 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 an include script


An include script 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 SystemDefinition → ScriptIncludes.
  2. Click New and fill in the fields.
  3. Click Save or Save and Exit to apply the changes.

Script Include form fields

FieldMandatoryDescription
NameYSpecify the include script name. It should match with the class name used in the script field. Also, the include script name should be unique and can not contain spaces.
DescriptionNAdd a short description of the action.
ActiveNSelect this checkbox to activate this script. When selected, the script is executed when it is called; otherwise, it is not executed.
Client CallableNSelect this checkbox to make this script available to call on the client-side scripts.
Disable ACL CheckNSelect this checkbox so that the include script does not go through an ACL check when it is executed within the Client Scripts.
ScriptY

Define the server-side script to run when called from other scripts.

Note

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

Code Block
languagejs
themeEclipse
linenumberstrue
ss.importIncludeScript('EmailHelper');
const helper = new EmailHelper();

Otherwise, the script is not available.


Use cases


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

a

and server-side.

Use a client callable include script on the forms

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

To do this, create an include script with the following parameters:

NameDurationCalculator
Activetrue
Client Callabletrue
Script

Enter the following script:

Code Block
languagejs
themeEclipse
titleClient callable script include
linenumberstrue
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;
    }
});


Note

When you call values passing from the client-side, use this.getParameter like shown in the code example above to get the sysparm_ parameter value.


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 include script 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.
Code Block
languagejs
themeEclipse
titleUsing script include on the client-side
linenumberstrue
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 include script on the lists

Another example is the calculation of list items after filtering.

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

NamegetListItemsCount
Activetrue
Client Callabletrue
Script

Enter a script from the code example:

Code Block
languagejs
themeEclipse
titleClient callable script include
linenumberstrue
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();
  }
  });

Note

When you call values passing from the client-side, use this.getParameter like shown in the code example above to get the sysparm_ parameter value.


The client-side script is the following:

Code Block
languagejs
themeEclipse
titleUsing script include on the client-side
linenumberstrue
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);
}


Table of Contents
absoluteUrltrue
classfixedPosition

...