Skip to main content
Version: 1.22.3

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.

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.

Parameter(s):

NameTypeMandatoryDefault value
messageStringYN
paramsObjectN{}

Return:

TypeDescription
VoidThis 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.

Parameter(s):

NameTypeMandatoryDefault value
messageStringYN
paramsObjectN{}

Return:

TypeDescription
VoidThis 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.

Parameter(s):

NameTypeMandatoryDefault value
messageStringYN
paramsObjectN{}

Return:

TypeDescription
VoidThis 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.

Parameter(s):

NameTypeMandatoryDefault value
messageAnyYN

Return:

TypeDescription
VoidThis 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.

Parameter(s):

NameTypeMandatoryDefault value
messageAnyYN

Return:

TypeDescription
VoidThis 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.

Parameter(s):

NameTypeMandatoryDefault value
messageAnyYN

Return:

TypeDescription
VoidThis 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.

Parameter(s):

NameTypeMandatoryDefault value
messageAnyYN

Return:

TypeDescription
VoidThis 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.

Parameter(s):

NameTypeMandatoryDefault value
nameStringYN
currentSimpleRecord objectYN
param_1StringNnull
param_2StringNnull
param_3StringNnull
param_4StringNnull
param_5StringNnull

Return:

TypeDescription
VoidThis 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):

NameTypeMandatoryDefault value
nameStringYN
currentSimpleRecord objectYN
process_started_atSimpleDateTime objectYN
param_1StringNnull
param_2StringNnull
param_3StringNnull
param_4StringNnull
param_5StringNnull

Return:

TypeDescription
VoidThis 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.

Return:

TypeDescription
StringThis 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 Action done 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 ''.

Parameter(s):

NameTypeMandatoryDefault value
userIdStringYN
scriptStringYN
expireStringYN

Return:

TypeDescription
StringThis 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.

Return:

TypeDescription
StringThis 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.

Parameter(s):

NameTypeMandatoryDefault value
nameStringYN

Return:

TypeDescription
StringThis 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.

Parameter(s):

NameTypeMandatoryDefault value
nameStringYN
valueStringYN
descriptionStringNnull

Return:

TypeDescription
VoidThis 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.

Return:

TypeDescription
SimpleSession objectThis 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.

Return:

TypeDescription
SimpleRecord objectThis 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.

Return:

TypeDescription
StringThis 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.

Parameter(s):

NameTypeMandatoryDefault value
tableIdStringYN
recordIdStringYN

Return:

TypeDescription
StringThis 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.

Parameter(s):

NameTypeMandatoryDefault value
docIdStringYN

Return:

TypeDescription
StringThis 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.

Parameter(s):

NameTypeMandatoryDefault value
docIdStringYN

Return:

TypeDescription
StringThis 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.

Parameter(s):

NameTypeMandatoryDefault value
roleStringYN

Return:

TypeDescription
BooleanThis 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.

Parameter(s):

NameTypeMandatoryDefault value
nameStringYN

Return:

TypeDescription
BooleanThis 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.

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 recommendedRecommended
https://instance.example.com/record/task/record/task

Parameter(s):

NameTypeMandatoryDefault value
urlStringN""

Return:

TypeDescription
VoidThis 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