You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 178 Next »

This server class provides methods to operate database records.

SimpleRecord(tableName)


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


Parameter(s):

NameTypeMandatoryDefault Value
tableNameStringYN

Example:

SimpleRecord
const taskRecord = new SimpleRecord('task');


REM attribute object


The SimpleRecord class has a special object for Record Extended Modelsrem_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:

NameTypeMandatoryDefault Value
propertyStringYN

Return:

TypeDescription
SimpleRecord objectThis 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. Please notice that you need to use system name of the operator in your scripts.


Parameter(s):

NameTypeMandatoryDefault Value
propertyStringYN
operatorString (refer to the Condition Operators article for more information)NN
valueInteger or String or Boolean or ArrayYN


Return:

TypeDescription
SimpleRecordThe 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)

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. Please notice that you need to use system name of the operator in your scripts.


Parameter(s):

NameTypeMandatoryDefault Value
propertyStringYN
operatorString (refer to the Condition Operators article for more information)NN
valueInteger or String or Boolean or ArrayYN


Return:

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

addEncodedQuery(condition)


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

Decoded query is also applicable.


Parameter(s):

NameTypeMandatoryDefault Value
conditionString YN

Return:

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

TypeDescription
BooleanThe 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:

TypeDescription
BooleanThe 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:

TypeDescription
BooleanThe 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:

TypeDescription
BooleanThe 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:

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

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

NameTypeMandatoryDefault 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 will cause an exception looking alike:

"Argument 1 passed to "get()" must not be empty".

YN
valueStringNNULL


Return:

TypeDescription
SimpleRecord objectThis method returns the SimpleRecord object from the table specified in the query.


Example:

get
const current = new SimpleRecord('task');
current.get('163663310116371174');

if (current.sys_id) {
    const company = new SimpleRecord('org_company');
    company.get('c_website', current.c_customer_url);
    ss.eventQueue('notify.responsible', current, company.responsible.email);
}


getAttributes()


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

Return:

TypeDescription
ObjectThe 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:

TypeDescription
StringTitle 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:

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

NameTypeMandatoryDefault Value
PropertyStringNNULL


Return:

TypeDescription
StringA 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:

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

NameTypeMandatoryDefault Value
propertyStringYN


Return:

TypeDescription
StringThe 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:

TypeDescription

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:

TypeDescription
IntegerItems 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:

TypeDescription
StringThe 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:

NameTypeMandatoryDefault Value
columnStringYN

Return:

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

NameTypeMandatoryDefault Value
propertyStringYN


Return:

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

TypeDescription
BooleanMethod 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:

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

TypeDescription
Integer
  • 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:

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


NameTypeMandatoryDefault Value
conditionStringN''

Return:

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

NameTypeMandatoryDefault Value
columnStringYN


Return:

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

NameTypeMandatoryDefault Value
columnStringYN


Return:

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

TypeDescription
VoidThis 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('Tasks numbers: ' +  tasks.number);
}
// Info: Tasks numbers: INC0000001
// Info: Tasks numbers: INC0000002


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 cannot save an incomplete record.


NameTypeMandatoryDefault Value
attributesString or ArrayYN

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:

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

NameTypeMandatoryDefault Value
flagBooleanYN


Return:

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

NameTypeMandatoryDefault Value
maxNumRecordsIntegerYN


Return:

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

NameTypeMandatoryDefault Value
propertyStringYN
valueStringYN

Return:

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

NameTypeMandatoryDefault Value
reModelIdStringYN

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

Return:

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

NameTypeMandatoryDefault Value
propertyStringYN
valueStringYN


Return:

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


NameTypeMandatoryDefault Value
enableBooleanNtrue
TypeDescription
VoidThis 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:

TypeDescription
Integer
  • 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:

TypeDescription
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();

  • No labels