SimpleRecord Server-Side

This server class provides methods to operate database records.

SimpleRecord(tableName)

This method instantiates a SimpleRecord class object for a particular table.

Parameter(s):

Name	Type	Mandatory	Default Value
tableName	String	Y	N

Example:

SimpleRecord

const taskRecord = new SimpleRecord('task');

REM attribute object

The SimpleRecord class has a special object for Record Extended Models – rem_attr – containing information about the REM attributes. It is used to read and edit REM attributes values of the current record with other class methods as in the example below.

rem_attr has a number of methods equal to methods of the SimpleRecord:

For example:

record.rem_attr.getValue('my_rem_attribute');

Parameter:

Name	Type	Mandatory	Default Value
property	String	Y	N

Return:

Type	Description
SimpleRecord object	This method returns the SimpleRecord object from the defined RE model. The method returns null if the record does not have a RE model.

Example:

get using REM

const record = new SimpleRecord('task');
record.get('160638931615274614');
if (record.getReModelId()) {
    ss.info(record.rem_attr.description);
}

addOrCondition(property, operator, value)

This method appends a 2-or-3 parameter OR condition to an existing query. It works in conjunction with any of the addQuery() methods. In this method, you can use any preferred operator from the Condition Operators list, specified either in lowercase or in uppercase. Notice that you need to use the system name of the operator in your scripts.

Parameter(s):

Name	Type	Mandatory	Default Value
property	String	Y	N
operator	String (refer to the Condition Operators article for more information)	N	N
value	Integer or String or Boolean or Array or SimpleRecord object	Y	N

Return:

Type	Description
SimpleRecord	The query containing OR condition added to the SimpleRecord object.

Example:

addOrCondition

const record = new SimpleRecord('task');
record.addQuery('subject', 'like', 'not work')
record.addOrCondition('description', 'like', 'not work');
ss.info('Condition query: ' + record.getConditionQuery());
record.query();
// Info: Condition query: (subjectLIKEnot work)^OR(descriptionLIKEnot work)

It is possible to pass the SimpleRecord object as current.{reference_field_name} instead of the record ID as the addOrCondition() method value. The script example:

Passing SimpleRecord as an argument

const task = new SimpleRecord('task');
task.setLimit(1);
task.query();
if (!task.next()) {
  ss.info('No tasks found!');
  return;
}

const relatedTask = new SimpleRecord('task');
relatedTask.addQuery('caller', task.caller);
relatedTask.addOrCondition('assigned_user', task.caller);
relatedTask.query();
ss.info('Tasks count: ' + relatedTask.getRowCount());
// Info: Tasks count: 122

addQuery(property, operator, value)

This method adds a condition to make a selection of records from the database. In this method, you can use any preferred operator from the Condition Operators list, specified either in lowercase or in uppercase. Note that you need to use system name of the operator in your scripts.

Parameter(s):

Name	Type	Mandatory	Default Value
property	String	Y	N
operator	String (refer to the Condition Operators article for more information)	N	N
value	Integer or String or Boolean or Array or SimpleRecord object	Y	N

Return:

Type	Description
SimpleRecord	The query condition added to the SimpleRecord object.

Example:

addQuery

const task = new SimpleRecord('task');
task.addQuery('active', true);
task.addQuery('subject', 'like', 'email');
task.addQuery('sys_created_at', '<', '2019-04-01 00:00:00');
task.query();
ss.info('Count: ' + task.getRowCount());
// Info: Count: 0

It is possible to pass the SimpleRecord object as current.{reference_field_name} instead of the record ID as the method addQuery() value. The script example:

Passing SimpleRecord as an argument

const task = new SimpleRecord('task');
task.setLimit(1);
task.query();
if (!task.next()) {
  ss.info('No tasks found!');
  return;
}

const otherTask = new SimpleRecord('task');
otherTask.addQuery('caller', task.caller);
otherTask.addQuery('sys_id', '!=', task.sys_id);
otherTask.query();
ss.info('Tasks count: ' + otherTask.getRowCount());
// Info: Tasks count: 720

addEncodedQuery(condition)

This method adds encoded query and applies it to the current query method.

Decoded query is also applicable.

Parameter(s):

Name	Type	Mandatory	Default Value
condition	String	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

addEncodedQuery

const currentUser = ss.getUser();
const reciever = new SimpleRecord('employee');
reciever.addQuery('active', true);
if (currentUser.company.class === 'internal') {
    reciever.addEncodedQuery(`(company=${currentUser.getValue('company')})`);
} else {
    reciever.addEncodedQuery(`%28sys_db_table_id%3D158645243815904649%5Esys_created_byDYNAMIC156957117519820256%29`);
}
ss.info('Decoded condition: ' + reciever.getConditionQuery());
reciever.query();
// Info: Decoded condition: (active=1)^((sys_db_table_id=158645243815904649^sys_created_byDYNAMIC156957117519820256))

canCreate()

This method checks whether inserting new records in this table satisfies the Access Control Rule (ACL).

Also, you can use this method in your UI Actions to adjust its visibility more precisely.

Return:

Type	Description
Boolean	The method returns 'true' if this operation is permitted; otherwise, it returns 'false'.

Example:

canCreate

current.canCreate();

canDelete()

This method checks whether deleting records in this table satisfies the Access Control Rule (ACL).

Also, you can use this method in your UI Actions to adjust its visibility more precisely.

Return:

Type	Description
Boolean	The method returns 'true' if this operation is permitted; otherwise, it returns 'false'.

Example:

canDelete

current.canDelete();

canRead()

This method checks whether reading records in this table satisfies the Access Control Rule (ACL).

Also, you can use this method in your UI Actions to adjust its visibility more precisely.

Return:

Type	Description
Boolean	The method returns 'true' if this operation is permitted; otherwise, it returns 'false'.

Example:

canRead

current.canRead();

canUpdate()

This method checks whether updating records in this table satisfies the Access Control Rule (ACL).

Also, you can use this method in your UI Actions to adjust its visibility more precisely.

Return:

Type	Description
Boolean	The method returns 'true' if this operation is permitted; otherwise, it returns 'false'.

Example:

canUpdate

current.canUpdate();

deleteMultiple()

This method allows deleting multiple records in a query selection. Please note that attachments cannot be deleted using this method.

Do not use this method on tables with dependencies. Always delete each record individually.

Return:

Type	Description
Boolean	This method returns 'true' if records are deleted successfully; otherwise, it returns 'false'.

Example:

deleteMultiple

const record = new SimpleRecord('sys_activity_feed_item');
record.addQuery('content', 'isempty');
record.query();
ss.info(record.getRowCount());
ss.info(record.deleteMultiple());
// Info: 0
// Info: true

deleteRecord()

This method deletes the current record.

Return:

Type	Description
Boolean	This method returns 'true' if the record is deleted successfully; otherwise it returns 'false'.

Example:

deleteRecord

const task = new SimpleRecord('task');
task.get('155931135900000000');
if (!task.sys_id) {
  return;
}
const isDeleted = task.deleteRecord();
if (isDeleted) {
  ss.info('Task with ID ' + task.sys_id + ' was deleted!');
  return;
}
ss.error(task.getErrors());

get(propertyOrValue, value)

This method loads an object from a database by the field value, or, in a specific case, by the sys_id.

Parameter(s):

Name	Type	Mandatory	Default Value
propertyOrValue	String value of record ID or property name. If it is equal to the property name, then the second parameter 'value' is mandatory. Passing 'NULL' or an empty string as the propertyOrValue parameter value causes an exception: "Argument 1 passed to "get()" must not be empty".	Y	N
value	String or SimpleRecord object	N	NULL

Return:

Type	Description
SimpleRecord object	This method returns a SimpleRecord object from the table specified in the query.

Example:

get

const task = new SimpleRecord('task');
task.get('163663310116371174'); // get by ID

if (task.state == '18') { // Rejected
  const company = new SimpleRecord('org_company');
  company.get('c_website', task.c_customer_url); // get by Customer URL
  ss.eventQueue('notify.responsible', task, company.responsible.email);
}

It is possible to pass the SimpleRecord object as current.{reference_field_name} instead of the record ID as the get() method value. The script example:

Passing SimpleRecord as an argument

const task = new SimpleRecord('task');
task.setLimit(1);
task.query();
if (!task.next()) {
  ss.info('No tasks found!');
  return;
}

const user = new SimpleRecord('user');
user.get(task.caller);
user.language_id = '156628684306541141'; // English
ss.info(user.update());
// Info: 167515292501757147

getAttributes()

This method returns an object with current record properties as keys and properties values as key values.

Return:

Type	Description
Object	The array containing attributes.

getAttributes

const userRecord = ss.getUser();
ss.info(userRecord.getAttributes());
// Info: {"sys_id":"155931135900000001","sys_created_at":"2019-09-30 00:00:00","sys_updated_at":"2021-06-28...

getClassDisplayValue()

This method returns the table title. If the title is not set, then returns name.

Return:

Type	Description
String	Title or name.

Example:

getClassDisplayValue

const current = new SimpleRecord('task');
current.get('163663310116371174');
ss.info(current.getClassDisplayValue());
// Info: Task

getConditionQuery()

This method returns current query condition.

Return:

Type	Description
String	The query condition.

Example:

getConditionQuery

const task = new SimpleRecord('task');
const condition = task.addQuery('state', '7');
condition.addOrCondition('priority', '<', '3');
ss.info('Condition before query: ' + task.getConditionQuery());
task.query();
ss.info('Condition after query: ' + task.getConditionQuery());
// Info: Condition before query: (state=7)^OR(priority<3)
// Info: Condition after query:

getDisplayValue(property)

This method returns the value of display_by_ref field or record value. For example, for the reference field the entity name will be returned, but not the ID.

Parameter(s):

Name	Type	Mandatory	Default Value
Property	String	N	NULL

Return:

Type	Description
String	A field or record value.

Example:

getDisplayValue

const current = new SimpleRecord('task');
current.get('163663310116371174');
ss.info(current.getDisplayValue('caller'));
ss.info(current.getValue('caller'));
// Info: John Doe
// Info: 155931135900000001

getErrors()

If the record creating, updating or deleting fails, then this method will display an error message.

Use this method for control purposes if there any validation errors within your scripts.

Some validation errors may not be displayed within the debug process, so it is highly recommended to use this method.

For example, errors in condition queries passed by methods like addEncodedQuery(condition) or similar methods can be displayed by calling this method.

Return:

Type	Description
Array	The error value.

Example:

getErrors

const record = new SimpleRecord('user');
const insertedRecordId = record.insert();
if (insertedRecordId == 0) {
  ss.info(record.getErrors());
}
// Info: ["The \"\"First Name\" [first_name]\" field is mandatory. (record id: )",...

getLabel(property)

This method gets the field title.

The getLabel() method cannot be used with REM attributes. Instead, use the getTitle() method.

Parameter(s):

Name	Type	Mandatory	Default Value
property	String	Y	N

Return:

Type	Description
String	The field name.

Example:

getLabel

const current = ss.getUser();
const fieldLabel = current.getLabel('username');
ss.addErrorMessage('Field "' +  fieldLabel + '" cannot be blank');
// Field "Login" cannot be blank

getReModelId()

This method retrieves the ID of the RE model related to the current record. To set a new model ID use the setReModelId method.

Return:

Type	Description
String	The method returns the ID of the model. If model is not found, the method returns null.

Example:

getReModelId

(function executeRule(current, previous = null /*not null only when action is update*/) {
    if (current.getReModelId()) {
        const model = new SimpleRecord('sys_rmc_model');
        model.get(current.getReModelId()); // current model
        current.$$service = model.getValue('cmdb_service_id'); // pass service if field exists
    }
})(current, previous);

getRowCount()

This method gets the amount of items in a row.

Returns:

Type	Description
Integer	Items amount in a row specified.

Example:

getRowCount

const task = new SimpleRecord('task');
task.query();
ss.addInfoMessage('All Tasks Count: ' + task.getRowCount());
// All Tasks Count: 2

getTableName()

This method gets the current table name.

Return:

Type	Description
String	The current table name.

Example:

getTableName

const current = ss.getUser();
ss.info('/list/' + current.getTableName() + '/' + current.sys_id);
// Info: /list/user/155931135900000001

getTitle(attribute)

This method returns the title of the defined RE attribute.

Parameter:

Name	Type	Mandatory	Default Value
column	String	Y	N

Return:

Type	Description
String	This method returns the title of the attribute.

Example:

getTitle

const current = new SimpleRecord('task');
current.get('163638951512716126');
if (current.sys_id) {
    ss.info(current.rem_attr.getTitle('reviewed'));
}
// Info: Review completed

To return column titles which are not part of REM, use the getLabel() method.

getValue(property)

This method returns the value of the object property based on its name.

If the field is of the Reference or List types, then its sys_id value returns.

To speed up the script execution, use this method to get values of the fields of the Reference type instead of Dot-walking.

As an example, it is preferable to use the current.getValue('reference_field') structure instead of current.reference_field.sys_id one.

Parameter(s):

Name	Type	Mandatory	Default Value
property	String	Y	N

Return:

Type	Description
Mixed	The string value of the object property.

getValue

const current = ss.getUser();
const user = new SimpleRecord('user');
user.addQuery('timezone_id', current.getValue('timezone_id'));
user.selectAttributes('sys_id');
user.query();
ss.info(user.getRowCount() + ' users have the same timezone as you');
// Info: 24 users have the same timezone as you

hasAttachment()

This method checks whether the record specified has an attachment or not.

Return:

Type	Description
Boolean	Method returns 'true' if the record has an attachment; otherwise, it returns 'false'.

Example:

hasAttachment

const current = new SimpleRecord('task');
current.get('163663310116371174');
const hasAttach = current.hasAttachment();
if (!hasAttach) {
  ss.addErrorMessage('File should be attached');
  return;
}
current.state = '2'; // Open
current.update();

initialize()

This method populates all active empty fields with their predefined default values.

It works only for new records that were never saved and cannot be called repeatedly.

This method is called automatically and implicitly at the first set operation (also known as "the setter").

Return:

Type	Description
Void	This method does not return a value.

Example:

initialize

const taskRecord = new SimpleRecord('task');
ss.info(taskRecord.getAttributes().caller);
taskRecord.initialize();
ss.info(taskRecord.getAttributes().caller);
// Info: 
// Info: 155931135900000001

insert()

This method uses the field values of the current record to insert a new one.

If the record is not inserted then method returns '0' (zero) and adds an informative error message which can be obtained with getErrors() method.

Return:

Type	Description
String	If record was not inserted, then method returns '0' and you can get a message containing list of errors. As a normal case, a unique ID of the inserted record returns.

Example:

insert

const newTask = new SimpleRecord('task');
newTask.subject = 'Subtask';
const inserterTaskID = newTask.insert();
ss.info(`/record/task/${inserterTaskID}`);
// Info: /record/task/163675231910113745

isTableVcsEnabled()

This method checks whether the VCS enabled attribute is enabled against the specified table or not.

Return:

Type	Description
Boolean	This method returns the value of the is_vcs_enabled attribute of record table.

Example:

isTableVcsEnabled

const current = new SimpleRecord('user');
ss.info(current.isTableVcsEnabled());
// Info: false

matchesCondition(condition)

This method checks whether the current record meets the condition in the current state.

Name	Type	Mandatory	Default Value
condition	String	N	''

Return:

Type	Description
Boolean	This method returns 'true' if the record meets the condition specified; otherwise; it returns 'false'.

matchesCondition

const task = new SimpleRecord('task');
task.description = 'emaio';
ss.info(task.matchesCondition('descriptionLIKEemail')); // false
task.description = 'email';
ss.info(task.matchesCondition('descriptionLIKEemail')); // true

next()

This method returns the next record in the query. If this is the first call, this method returns the first record in query. If the query is empty, this method returns 'false'.

Return:

Type
Record or Boolean

Example:

next

const user = new SimpleRecord('user');
user.setLimit(1);
user.query();
user.next();
ss.info(user.sys_id);
// Info: 100000000000000000

Until the method is called, the values of a SimpleRecord object are not available, and the 'Current record is not set' message will occur. Consider the example:

const task = new SimpleRecord('task');
task.setLimit(1);
task.query();
// task.next();
ss.info(task.number);
// Error: Current record is not set.

orderBy(column)

This method sorts records in the ascending order.

Call this method several times to order by multiple columns.

Parameter(s):

Name	Type	Mandatory	Default Value
column	String	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

orderBy

const firstLog = new SimpleRecord('sys_log');
firstLog.orderBy('sys_created_at'); // oldest record first
firstLog.addQuery('message', 'like', 'Connection');
firstLog.setLimit(1);
firstLog.selectAttributes(['message', 'sys_created_at']);
firstLog.query();
firstLog.next();
ss.info(firstLog.sys_created_at + ' - ' + firstLog.message);
// Info: 2021-06-03 06:34:02 - IMAP IMAP (Default): Connection error: ...

orderByDesc(column)

This method sorts the records in the descending order.

Parameter(s):

Name	Type	Mandatory	Default Value
column	String	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

orderByDesc

const lastComment = new SimpleRecord('sys_activities_stream_field');
lastComment.orderByDesc('sys_created_at'); // newest record first
lastComment.setLimit(1);
lastComment.selectAttributes(['value', 'sys_created_by']);
lastComment.query();
lastComment.next();
ss.info(lastComment.sys_created_by.display_name + ': ' + lastComment.value);
// Info: John Doe: test

query()

This method applies query to the database selection. After this, it fills in the record set.

Return:

Type	Description
Void	This method does not return a value.

Example:

query

const tasks = new SimpleRecord('task');
tasks.addQuery('sys_created_at', '>', '2020-01-01');
tasks.orderBy('sys_created_at');
tasks.setLimit(2);
tasks.query();
while (tasks.next()) {
  ss.info('Task number: ' +  tasks.number);
}
// Info: Task number: TSK0000001
// Info: Task number: TSK0000003

selectAttributes(attributes)

This method is intended to optimize database queries. Sometimes, it is necessary to obtain only several object fields, not the whole object. Therefore, this method was added.

Do not use this method to select records that could be updated or deleted after selecting. Otherwise, some of the record field values may be lost when these records are updated or deleted. Or the action performed may throw an exception looking like this (the example text is given below):

You can`t save incomplete record.

Name	Type	Mandatory	Default Value
attributes	String or Array	Y	N

It makes sense to pass a single attribute name as a string. But if you need to pass more than one attribute names, please use Array type (as shown in code example below).

Return:

Type	Description
SimpleRecord object	This method returns a SimpleRecord object containing attributes and values. Regardless of the initial attribute set content, the returned object always contains the sys_id attribute. See code examples below for more clarity.

Example:

selectAttributes (String)

const record = new SimpleRecord('user');
record.selectAttributes('email');
record.query();
record.next();
ss.info(record.getAttributes());
// Info: {"email":"john.doe@email.com","sys_id":"162423321917274937"}

Example:

selectAttributes (Array)

const record = new SimpleRecord('user');
record.selectAttributes(['email', 'username']);
record.query();
record.next();
ss.info(record.getAttributes());
// Info: {"email":"john.doe@email.com","username":"john.doe","sys_id":"162423321917274937"}

setAbortAction(flag)

This method is used in business rules and sets a flag, indicating that the current operation (insert/update/delete) will be interrupted.

Please note that the code will not be executed if it is typed after calling this method in the script body.

It is not recommended to use this method with async business rules. It may cause unpredictable system behavior.

Parameter(s):

Name	Type	Mandatory	Default Value
flag	Boolean	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

setAbortAction

const current = new SimpleRecord('task');
current.get('163663310116371174');
const hasAttach = current.hasAttachment();
if (!hasAttach) {
    ss.addErrorMessage('File should be attached!');
    current.setAbortAction(true);
}
current.state = '2'; // Open
current.update();

setLimit(maxNumRecords)

This method limits the number of records selected by SimpleRecord query methods.

Parameter(s):

Name	Type	Mandatory	Default Value
maxNumRecords	Integer	Y	N

Return:

Type	Description
Void	This method does not return a value.

Example:

setLimit

const record = new SimpleRecord('user');
record.setLimit(3);
record.query();
ss.info(record.getRowCount());
// Info: 3

setMultipleValue(property,value)

This method sets the properties values for every entry in the current selection.

Parameter(s):

Name	Type	Mandatory	Default Value
property	String	Y	N
value	String	Y	N

Return:

Type	Description
Void	This method does not return a value.

setMultipleValue

const task = new SimpleRecord('task');
task.addQuery('state', '7'); // Draft
task.query();
ss.info(task.getRowCount());
task.setMultipleValue('state', '2'); // Open
// task.updateMultiple();

setReModelId(reModelId)

This method sets the ID of the defined RE model. To get the model ID, use the getReModelId method.

Parameter(s):

Name	Type	Mandatory	Default Value
reModelId	String	Y	N

If the reModelId parameter is equal to 'null', the REM, related to the record, will be detached.

Return:

Type	Description
Void	This method does not return a value.

Example:

getReModelId

const task = new SimpleRecord('task');
task.get('163352033916904699');
if (task.getValue('service') === '164069027812962298') { // Email Server Service
    task.setReModelId('158569205818704980'); // Email Server Access Request
} else {
    task.setReModelId(null);
}
task.update();

When calling the method on a SimpleRecord() instance, the values of its attributes bound to the previous model will be reset.

After calling the method and updating the сurrent record, the attribute values bound to the previous model will be lost.

setValue(property, value)

This method sets the value of the field in the current record.

Parameter(s):

Name	Type	Mandatory	Default Value
property	String	Y	N
value	String	Y	N

Return:

Type	Description
Void	This property does not return a value.

Example:

setValue

const task = new SimpleRecord('task');
task.setValue('subject', 'mail');
task.insert();

silentMode(enable)

This method is intended to update the record without executing any entities related to this record implementing the business logic, such as business rules, notifications, workflows, etc.

Name	Type	Mandatory	Default Value
enable	Boolean	N	true

Type	Description
Void	This property does not return a value.

silentMode

const task = new SimpleRecord('task');
task.addQuery('active', false);
task.addQuery('approval_state', 'isempty');
task.query();
ss.info(task.getRowCount());
task.silentMode();
task.setMultipleValue('approval_state', 'not_requested'); // set Default Value
//task.updateMultiple();

update()

This method updates a database record.

This method is used for existing records.

If the record existed before, the changes are applied.
If the record did not exist before, the getErrors() method will return this error: "Unable to update new record. Use `insert()` instead. (record id: )"

Return:

Type

Description

String

If record was not updated, then method returns '0' and you can get a message containing list of errors;

As a normal case, an ID of the updated record returns.

Example:

update

const current = new SimpleRecord('user');
current.get(ss.getUserId());
current.timezone_id = '156076775207670452'; // UTC
ss.info(current.update());
ss.info(current.getErrors());
// Info: 155931135900000001
// Info: []

updateMultiple()

This method updates all the selection entries.

Return:

Type	Description
Void or Integer	If validation errors occurred and record was not updated, then method returns '0' and you can get a message containing list of errors; Normally, this method does not return a value.

updateMultiple

const task = new SimpleRecord('task');
task.addQuery('state', '0'); // Open
task.query();
ss.info(task.getRowCount());
task.setMultipleValue('state', '10'); // Canceled
// task.updateMultiple();

Page tree

SimpleRecord Server-Side

SimpleRecord(tableName)

REM attribute object

addOrCondition(property, operator, value)

addQuery(property, operator, value)

addEncodedQuery(condition)

canCreate()

canDelete()

canRead()

canUpdate()

deleteMultiple()

deleteRecord()

get(propertyOrValue, value)

getAttributes()

getClassDisplayValue()

getConditionQuery()

getDisplayValue(property)

getErrors()

getLabel(property)

getReModelId()

getRowCount()

getTableName()

getTitle(attribute)

getValue(property)

hasAttachment()

initialize()

insert()

isTableVcsEnabled()

matchesCondition(condition)

next()

orderBy(column)

orderByDesc(column)

query()

selectAttributes(attributes)

setAbortAction(flag)

setLimit(maxNumRecords)

setMultipleValue(property,value)

setReModelId(reModelId)

setValue(property, value)

silentMode(enable)

update()

updateMultiple()