Version: 1.28.0

SimpleSystem

This class provides methods to get information about the system, the current user, and other.

This class has no constructor, use the ss global object to access the methods.

tip

The system checks the ACL rules configured for the current user for the required table, record and column before executing some of the methods of this class. If an error occurs during the execution of the method because the user does not have the required access rights, the system responds with an exception:

If the exception is not processed, the system adds a record to the Exception Log (sys_log_exception) table.
If the exception is processed, the system executes the logic created by the developer.

When a server script is launched by the system from a user's account (for instance, when a business rule, a notification rule, or an event script is executed), the ACL check is not performed in the script.

To learn about the ACL checks performed when a specific method is used, read the sections of this article about these methods.

ss.addInfoMessage(message, params)

Use this method to display an informational toast message in the lower right corner according to the current user locale. To do so, in the message parameter, enter the source_message value of a record from the app category. See Localization and Multi-Language Support to learn more. Use the params parameters to define values for the dynamic parts of the translated message.

When this method is executed, the system does not check the ACL rules configured for the user.

Parameter(s):

Name	Type	Mandatory	Default value
message	String	Y	N
params	Object	N	{}

Return:

Type	Description
Void	This method does not return a value.

Example:

ss.addInfoMessage()
ss.addInfoMessage('Three days left');
// OR
ss.addInfoMessage('{count} {noun} left', {"count": "Three", "noun": "days"});

ss.addErrorMessage(message, params)

Use this method to display an error toast message in the lower right corner according to the current user locale. To do so, in the message parameter, enter the source_message value of a record from the app category. See Localization and Multi-Language Support to learn more. Use the params parameters to define values for the dynamic parts of the translated message.

When this method is executed, the system does not check the ACL rules configured for the user.

Parameter(s):

Name	Type	Mandatory	Default value
message	String	Y	N
params	Object	N	{}

Return:

Type	Description
Void	This method does not return a value.

Example:

ss.addErrorMessage()
ss.addErrorMessage('"Name" cannot be blank');
// OR
ss.addErrorMessage('"{title}" cannot be blank', {title: "Name"});

ss.addSuccessMessage(message, params)

Use this method to display a success toast message in the lower right corner according to the current user locale. To do so, in the message parameter, enter the source_message value of a record from the app category. See Localization and Multi-Language Support to learn more. Use the params parameters to define values for the dynamic parts of the translated message.

When this method is executed, the system does not check the ACL rules configured for the user.

Parameter(s):

Name	Type	Mandatory	Default value
message	String	Y	N
params	Object	N	{}

Return:

Type	Description
Void	This method does not return a value.

Example:

ss.addSuccessMessage()
ss.addSuccessMessage('Successfully updated');
// OR
ss.addSuccessMessage('Successfully {action_name}', {action_name: "updated"});

ss.info(message)

Use this method to add an information message into the system journal located in the Main Log (sys_log) table.

When this method is executed, the system does not check the ACL rules configured for the user.

Parameter(s):

Name	Type	Mandatory	Default value
message	Any	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

ss.info()
const task = new SimpleRecord('task');
task.orderByDesc('sys_created_at');
task.setLimit(1);
task.selectAttributes('number');
task.query();
while(task.next()){
    ss.info(task.number);
}

ss.debug(message)

Use this method to add a debug message into the system journal located in the Main Log (sys_log) table.

When this method is executed, the system does not check the ACL rules configured for the user.

Parameter(s):

Name	Type	Mandatory	Default value
message	Any	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

ss.debug()
const insertedID = inquiry.insert();
if (insertedID == 0) {
    ss.debug(inquiry.getErrors());
} else {
    ss.debug(`Create inquiry with ID ${insertedID}`)
}

ss.warning(message)

Use this method to add a warning message into the system journal located in the Main Log (sys_log) table.

When this method is executed, the system does not check the ACL rules configured for the user.

Parameter(s):

Name	Type	Mandatory	Default value
message	Any	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

ss.warning()
const task = new SimpleRecord('task');
task.query();
while(task.next()){
  ss.warning(task.sys_id);
}

ss.error(message)

Use this method to add an error message into the system journal located in the Main Log (sys_log) table.

When this method is executed, the system does not check the ACL rules configured for the user.

Parameter(s):

Name	Type	Mandatory	Default value
message	Any	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

ss.error()
(function executeRule(current, previous /*null when async*/ ) {
    const nowDateTime = new SimpleDateTime();
    const targetDateTime = new SimpleDateTime(current.appropriate_datetime);
    const secondsLeft = targetDateTime.getNumericValue() - nowDateTime.getNumericValue();
    if (secondsLeft < 1800) { // less than half an hour left
        ss.addErrorMessage('Appropriate Datetime cannot be less than half an hour');
        ss.error(`Too Urgent Request: ${secondsLeft} to process`);
        current.setAbortAction(true);
    }
})(current, previous);

ss.eventQueue(name, current, param_1, param_2, param_3, param_4, param_5)

Use this method to queue an event based on its name and optional parameters.

The name argument should be the same as the record name in the Event Registers (sys_event_register) table.

The table of the passed current object should be the same as the table specified in the record of the Event Register (sys_event_register) table or the table extended from it.

When this method is executed, the system checks the ACL rules configured for the user for the Create operation in the Event (event) table. If the ACL check is disabled in server scripts, the system does not check this ACL rule for users with vendor privileges.

Parameter(s):

Name	Type	Mandatory	Default value
name	String	Y	N
current	SimpleRecord object	Y	N
param_1	String	N	null
param_2	String	N	null
param_3	String	N	null
param_4	String	N	null
param_5	String	N	null

Return:

Type	Description
Void	This method does not return a value.

Example:

ss.eventQueue()
if (current.state != '10') { // Not Closed
    ss.eventQueue('incident.close', current, ss.getUserID());
}

ss.eventQueueScheduled(name, current, process_started_at, param_1, param_2, param_3, param_4, param_5)

Use this method to queue an event and run it at a specified time.

The name argument should be the same as the record name in the Event Registers (sys_event_register) table.

The table of the passed current object should be the same as the table specified in the record of the Event Register (sys_event_register) table or the table extended from it.

Parameter(s):

Name	Type	Mandatory	Default value
name	String	Y	N
current	SimpleRecord object	Y	N
process_started_at	SimpleDateTime object	Y	N
param_1	String	N	null
param_2	String	N	null
param_3	String	N	null
param_4	String	N	null
param_5	String	N	null

Return:

Type	Description
Void	This method does not return a value.

Example:

ss.eventQueueScheduled()
if (current.state != '10') { // Not Closed
    const plusThreeDays = new SimpleDateTime(); // now
    plusThreeDays.addDays(3); // + 3 days
    ss.eventQueueScheduled('incident.autoclose', current, plusThreeDays, ss.getUserID());
}

ss.generateResetToken()

Use this method to generate a token, for example, when the password resetting has been requested.

When this method is executed, the system does not check the ACL rules configured for the user.

Return:

Type	Description
String	This method returns a password reset token.

Example:

generateResetToken()
const resetToken = ss.generateResetToken();
ss.info(resetToken);
//Info: l_kxwLi-TsTwmgLYk3euOCeXeA14nE2U_1610699284

ss.generateUrlAction(userId, script, expire)

Use this method to return a URL. After following it, the script specified in the script parameter is executed.

By default, the main page opens after following the URL. To redirect a user to another page, enter its address into the redirectUrl variable within the script.

A toast message The action is completed is shown by default. To change the message text, redefine the message variable within the script.

To deactivate the toast message, set the message variable as null or ''.

When this method is executed, the system checks the ACL rules configured for the user for the Create operation in the URL Action (sys_url_action) table.

Parameter(s):

Name	Type	Mandatory	Default value
userId	String	Y	N
script	String	Y	N
expire	String	Y	N

Return:

Type	Description
String	This method returns the action URL.

Example:

ss.generateUrlAction()
const simpleInstanceUri = ss.getProperty('simple.instance.uri');
const instanceUrl = simpleInstanceUri.startsWith('https://') ? simpleInstanceUri : 'https://' + simpleInstanceUri;


const аctionScript = `
    const task = new SimpleRecord('task');
    task.get('${current.sys_id}');
    if (task.state == '7') { // Completed
        task.state = '10'; // Closed
        task.update();
    }
    message = null;
    redirectUrl = '${instanceUrl}' + '/record/task/' + '${current.sys_id}';
`;
const nowDateTime = new SimpleDateTime();
nowDateTime.addDays(3);
const url = ss.generateUrlAction(current.getValue('caller'), аctionScript, nowDateTime.getValue());
ss.info(url);
//Info: your-instance-uri.simpleone.ru/url-action/run?key=Q2GqNFRXCRY2

ss.getApplicationId()

Use this method to return the ID of the application that the current user is using at the moment.

When this method is executed, the system checks the ACL rules configured for the user for the Create operation in the Application (sys_application) table.

Return:

Type	Description
String	This method returns the application ID.

Example:

ss.getApplicationId()
const appId = ss.getApplicationId();
ss.info(appId);
//Info: 155931135900000002

ss.getProperty(name)

Use this method to return a value from the specified in the name parameter record from the System Properties (sys_property) table.

When this method is executed, the system checks the ACL rules configured for the user for the Read operation in the System Property (sys_property) table and the Value (value) column.

Parameter(s):

Name	Type	Mandatory	Default value
name	String	Y	N

Return:

Type	Description
String	This method returns the property value if available; otherwise, the method returns null.

Example:

ss.getProperty()
ss.info(ss.getProperty('simple.passwordreset.enabled'));
//Info: false

ss.setProperty(name, value, description)

Use this method to verify, using the name parameter that there is a record in the System Property (sys_property) table.

If the record exists, the method updates its value and description.

When this method is executed, the system checks the ACL rules configured for the user for the Read, Create, Update operations in the System Property (sys_property) table.

Parameter(s):

Name	Type	Mandatory	Default value
name	String	Y	N
value	String	Y	N
description	String	N	null

Return:

Type	Description
Void	This method does not return a value.

Example:

ss.setProperty()
ss.setProperty('user.timezone.default', 'Europe/Moscow', 'Define the default user time zone');

ss.getSession()

Use this method to get information on the current authorization session.

When this method is executed, the system does not check the ACL rules configured for the user.

Return:

Type	Description
SimpleSession object	This method returns the SimpleSession object of the current session.

Example:

ss.getSession()
const session = ss.getSession();
const ipAddress = session.getClientIP();
ss.info(ipAddress);
//Info: 127.0.0.1

ss.getUser()

Use this method to return the SimpleRecord object of the current user.

When this method is executed, the system checks the ACL rules configured for the user for the Read operation for the record and columns of the User (user) table.

caution

The attributes of the Employee (employee) table and other User (user) child tables are not available in the returned object.

let user = ss.getUser();
user.work_schedule = '157165229904988595'; /* 24/7 */
user.update();

Return:

Type	Description
SimpleRecord object	This method returns the SimpleRecord object of the current user.

Example:

ss.getSession()
ss.info(ss.getUser().username);
//Info: admin

ss.getUserID()

Use this method to return the current user ID.

When this method is executed, the system checks the ACL rules configured for the user for the Read operation in the User (user) table.

Return:

Type	Description
String	This method returns the ID value of the current user.

Example:

ss.getUserID()
const approval = new SimpleRecord('sys_approval');
approval.addQuery('approver_id', ss.getUserID());
approval.addQuery('state', 'requested');
approval.selectAttributes('sys_id');
approval.query();
if (approval.getRowCount() > 0) {
  //...
}

ss.getDocIdByIds(tableId,recordId)

Use this methods to return a record Document ID (32-character UUID value) based on the table ID and the table record ID.

When this method is executed, the system does not check the ACL rules configured for the user.

Parameter(s):

Name	Type	Mandatory	Default value
tableId	String	Y	N
recordId	String	Y	N

Return:

Type	Description
String	This method returns a Document ID record (32-character UUID value).

Example:

ss.getDocIdByIds()
const docID = ss.getDocIdByIds(current.sys_db_table_id, current.sys_id);
const approval = new SimpleRecord('sys_approval');
approval.addQuery('item', docID);
approval.query();

ss.getTableIdByDocId(docId)

Use this method to return the table ID based on the Document ID record (32-character UUID value) specified.

When this method is executed, the system does not check the ACL rules configured for the user.

Parameter(s):

Name	Type	Mandatory	Default value
docId	String	Y	N

Return:

Type	Description
String	This method returns а table ID.

Example:

ss.getTableIdByDocId()
const tableID = ss.getTableIdByDocId(current.item);
const table = new SimpleRecord('sys_db_table');
table.get(tableID);
const record = new SimpleRecord(table.name);
const recordID = ss.getRecordIdByDocId(current.item);
record.get(recordID);
ss.addInfoMessage(record.sys_created_at);
//Info: 2020-05-24 16:30:21

ss.getRecordIdByDocId(docId)

Use this method to return a record ID based on the DocumentID record (32-character UUID value) specified.

When this method is executed, the system does not check the ACL rules configured for the user.

Parameter(s):

Name	Type	Mandatory	Default value
docId	String	Y	N

Return:

Type	Description
String	This method returns а record ID.

Example:

ss.getRecordIdByDocId()
const tableID = ss.getTableIdByDocId(current.item);
const table = new SimpleRecord('sys_db_table');
table.get(tableID);
const record = new SimpleRecord(table.name);
const recordID = ss.getRecordIdByDocId(current.item);
record.get(recordID);
ss.addInfoMessage(record.sys_created_at);

ss.hasRole(role)

Use this method to verify that the current user has the specified or the admin role. If the role specified has the Elevated privilege checkbox selected and the admin role is not elevated up to the specified one, the method returns false.

When this method is executed, the system does not check the ACL rules configured for the user.

Parameter(s):

Name	Type	Mandatory	Default value
role	String	Y	N

Return:

Type	Description
Boolean	This method returns true if the user has the specified or admin role; otherwise, it returns false.

Example:

ss.hasRole()
const isUserManager = ss.hasRole('process_manager'); // true or false
return isUserManager;

caution

The method always returns true if a user has a specific or admin role. To verify that the user has a particular role, use the following script:

ss.hasRole
const MANAGER_ROLE = 'process_manager'; 
const userHasRole = new SimpleRecord('sys_user_has_role');
userHasRole.addQuery('user_id', ss.getUserId());
userHasRole.addQuery('role_id.name', MANAGER_ROLE);
userHasRole.setLimit(1);
userHasRole.selectAttributes(['sys_id']);
userHasRole.query();
const isManager = !!userHasRole.next();
return isManager

ss.importIncludeScript(name)

Use this method to import script includes.

When this method is executed, the system does not check the ACL rules configured for the user.

Parameter(s):

Name	Type	Mandatory	Default value
name	String	Y	N

Return:

Type	Description
Boolean	This method does not return a value.

Example:

ss.hasRole()
ss.importIncludeScript('calculateCAB');
const approvers = [];
if (!!current.customized_cab) {
    approvers = approvers.concat(current.customized_cab.split(','));
}
if (!current.ignore_automatically_generated_cab) {
    const includeScriptResult = calculateCAB(current);
    approvers = approvers.concat(includeScriptResult);
}

ss.setRedirect(url)

Use this method to redirect a user to the specified URL. If the URL is not provided, the system refreshes the current page after calling the method.

When this method is executed, the system does not check the ACL rules configured for the user.

note

It is not recommended to pass an absolute URL as a parameter value for this method, because it leads to the scalability issues. Specify the paths in a relative way. See the example below:

Not recommended	Recommended
https://instance.example.com/record/task	/record/task

Parameter(s):

Name	Type	Mandatory	Default value
url	String	N	""

Return:

Type	Description
Void	This method does not return a value.

Example:

ss.setRedirect()
ss.setRedirect(`/list/${current.getTableName()}`);
// Redirect to the list view of the current table
 
ss.setRedirect('/record/task');
// Redirect to the default view of the Task table

ss.addInfoMessage(message, params)​

ss.addErrorMessage(message, params)​

ss.addSuccessMessage(message, params)​

ss.info(message)​

ss.debug(message)​

ss.warning(message)​

ss.error(message)​

ss.eventQueue(name, current, param_1, param_2, param_3, param_4, param_5)​

ss.eventQueueScheduled(name, current, process_started_at, param_1, param_2, param_3, param_4, param_5)​

ss.generateResetToken()​

ss.generateUrlAction(userId, script, expire)​

ss.getApplicationId()​

ss.getProperty(name)​

ss.setProperty(name, value, description)​

ss.getSession()​

ss.getUser()​

ss.getUserID()​

ss.getDocIdByIds(tableId,recordId)​

ss.getTableIdByDocId(docId)​

ss.getRecordIdByDocId(docId)​

ss.hasRole(role)​

ss.importIncludeScript(name)​

ss.setRedirect(url)​

ss.addInfoMessage(message, params)

ss.addErrorMessage(message, params)

ss.addSuccessMessage(message, params)

ss.info(message)

ss.debug(message)

ss.warning(message)

ss.error(message)

ss.eventQueue(name, current, param_1, param_2, param_3, param_4, param_5)

ss.eventQueueScheduled(name, current, process_started_at, param_1, param_2, param_3, param_4, param_5)

ss.generateResetToken()

ss.generateUrlAction(userId, script, expire)

ss.getApplicationId()

ss.getProperty(name)

ss.setProperty(name, value, description)

ss.getSession()

ss.getUser()

ss.getUserID()

ss.getDocIdByIds(tableId,recordId)

ss.getTableIdByDocId(docId)

ss.getRecordIdByDocId(docId)

ss.hasRole(role)

ss.importIncludeScript(name)

ss.setRedirect(url)