sys.utils

sys.utils.text #

This package contains methods to manipulate text.

findTokens(text) #

The findTokens function is used to locate and extract all tokens from a given string. Tokens in the string are identified as sequences that start with “#” and adhere to the following format:

#name:value
#name:value1,value2,value3
#name

This way you could have a text like this:

#project:test
#assignee:user1
#important

There is a bug with user profile popup!

This method enables you to effortlessly extract the tokens project, assignee, and important.

This method proves highly valuable for parsing commands within plain text messages, such as emails or instant messages.

Parameters #

Returns #

object - A key-value structure where the key represents the token name. The value could be an array if there is more than one value. For example, given the following text:

#project:test1
#assignee:admin
#watchers:user1,user2
#important

This is an important issue! Please fix.

Also related to #project:test2

Tokens will be:

{
  project: ['test1', 'test2'],
  assignee: 'admin',
  watchers: ['user1', 'user2'],
  important: true
}

Notice that when you don’t specify a value for the token, it will be set to true.

Samples #

// finds tokens in a string
var str = "this is a ticker #project:test1 #type:bug #hotfix";
var tokens = sys.utils.text.findTokens(str);
log('tokens: '+JSON.stringify(tokens));

processTemplate(template, options) #

This function enables you to process a Freemarker template. You can find more information about Freemarker here

Parameters #

Returns #

string - The processed template

Samples #

// process a template for an email for a contact
var record = sys.data.findOne('contacts', {email: 'gowensb1@google.ca'});
var recordStr = record.toJson({relationshipsToFetch: 'company', user: 'gowensb1@google.ca '});
var template = "Hi ${contact.firstName} ${contact.lastName}:\n\n We want to say hi!\n\nThanks!";
var emailContent = sys.utils.text.processTemplate(template, {
  model: {
    contact: recordStr
  }
});
log('email content: '+emailContent);

htmlToText(html) #

This function allows you to convert an HTML text into plain text by removing HTML tags.

Parameters #

Returns #

string - A plain text with HTML tags removed.

Samples #

// convert an html text into a plain text
var html = "<strong>This is sparta</strong>";
var text = sys.utils.text.htmlToText(html);
log('Text: ' + text);

textToHtml(text) #

This function allows you to convert a plain text into HTML text.

Parameters #

Returns #

string - An HTML with plain text tokens removed.

Samples #

// convert a plain text into an html text
var text = "This is sparta\n";
var html = sys.utils.text.textToHtml(text);
log('HTML: ' + html);

markdownToHtml(markdownText) #

This function allows you to convert an markdown text into HTML by transforming markdown tokens into html tags.

Parameters #

Returns #

string - An HTML text with markdown tokens transformed into html tags

Samples #

// convert a markdown text into an html text
var markdown = "**This is sparta**";
var html = sys.utils.text.markdownToHtml(markdown);
log('HTML: ' + html);

htmlToMarkdown(html) #

This function allows you to convert an HTML text into markdown text by transforming html tags into html markdown tokens.

Parameters #

Returns #

string - A markdown text with html tags transformed into markdown tokens

Samples #

// convert an html text into a markdown text
var html = "<strong>This is sparta</strong><br/>";
var markdown = sys.utils.text.htmlToMarkdown(html);
log('Markdown text: ' + markdown);

sys.utils.xml #

This package contains methods for manipulating XML format.

xmlToJson(xml) #

This function allows you to convert an XML text into a JSON object.

Parameters #

Returns #

object - the JSON representation of the given XML

Samples #

// convert an XML text into a JSON object
var xml = '<note><to>Tove</to><from>Jani</from></note>';
var json = sys.utils.xml.xmlToJson(xml);
log('Json: ' + JSON.stringify(json));
// this will print {"note":{"to":"Tove","from":"Jani"}}

jsonToXml(json) #

This function allows you to convert a JSON object into an XML text.

Parameters #

Returns #

string - A XML text

Samples #

// convert a JSON object into a XML text
var json = {"note":{"to":"Tove","from":"Jani"}};
var xml = sys.utils.xml.jsonToXml(json);
log('XML: ' + xml);

sys.utils.base64 #

This package contains utilities for Base64 encoding. Base64 encoding is used to represent binary data in an ASCII format.

encode(string) #

This function encodes binary data using the Base64 algorithm. It does not chunk the output.

Parameters #

Returns #

string - A string containing Base64 characters in their UTF-8 representation.

Samples #

// encode a string
var pass = 'This_is_a_pass';
var encodedPass = sys.utils.base64.encode(pass);
log('Encoded pass: ' + encodedPass);

decode(base64String) #

Decodes a Base64 string into octets.

Parameters #

Returns #

string - Decoded data

Samples #

// decode an encoded string
var pass = 'VGhpc19pc19hX3Bhc3M=';
var rawPass = sys.utils.base64.decode(pass);
log('Pass: ' + rawPass);

sys.utils.numbers #

This package contains methods to assist in managing numbers.

BigNumber() #

This is a library for arbitrary-precision decimal and non-decimal arithmetic. For more information, please visit: BigNumber.js

Samples #

// Returns a BigNumber whose value is the value of this BigNumber plus n
var n = 0.2;
var bigNumber = sys.utils.numbers.BigNumber(0.1);
return bigNumber.plus(n);

format(value, options) #

Returns a string of formatted number of the value or string without format.

Parameters #

Returns #

string - string of formatted value of number.

Samples #

// prints the formatted value of a decimal value
var options = {thousandsSeparator: true, limitNumberOfDecimals:true, numberOfDecimals: 3};
var formattedNumber = sys.utils.numbers.format(12345.12345, options);
log('Result: ' + formattedNumber);

getRandomValue() #

Using a random number algorithm generates a strong cryptographic decimal number between 0.0 and 1.0.

Samples #

// prints a random number.
var randomNumber = sys.utils.numbers.getRandomValue();
log('Result: ' + randomNumber);

sys.utils.crypto #

This package contains methods for performing basic cryptographic operations.

sha1(message) #

This function calculates the SHA-1 digest of a message and returns the result as a hexadecimal string.

Parameters #

Returns #

string - The result hash as String.

Samples #

// converts a company to the string representation
var convertedMessage = sys.utils.crypto.sha1('my custom message');
log('SHA-1 string: '+convertedMessage);

sha3(message, bits) #

This function calculates the SHA-3 digest of a message and returns the result as a hexadecimal string.

Parameters #

Returns #

string - The result hash as String.

Samples #

// converts a company to the string representation
var convertedMessage = sys.utils.crypto.sha3('my custom message');
log('SHA-3 string: '+convertedMessage);

keccak(message, bits) #

This function calculates the KECCAK digest of a message and returns the result as a hexadecimal string.

Parameters #

Returns #

string - The result hash as String.

Samples #

// converts a company to the string representation
var convertedMessage = sys.utils.crypto.keccak('my custom message');
log('Keccak string: '+convertedMessage);

jwt.generate(payload, privateKey, algorithm) #

Uses a secret key and a algorithm to generate a JWT token of a JSON object.

Parameters #

Returns #

string - The JWT token as String.

Samples #

// generates a JWT token
var convertedJWT = sys.utils.crypto.jwt.generate({iss: "123", sub: "456"}, "secret", "HS256");
log('JWT token: '+convertedJWT);

jwt.verify(token, privateKey) #

Uses a public key and a JWT token to verify if it is a valid JWT.

Parameters #

Returns #

boolean - True if the token is valid, false otherwise.

Samples #

// verifies a JWT token
var validJWT = sys.utils.crypto.jwt.verify("ey.js.wt", "public");
log('JWT token is valid? : ' + validJWT);

jwt.decodeToken(token) #

Uses a JWT token to decode the payload.

Parameters #

Returns #

string - The payload as String.

Samples #

// decodes a JWT token
var tokenJWT = sys.utils.crypto.jwt.decodeToken("ey.js.wt");
log('JWT token: ' + tokenJWT);

hashHmac(message, secret, algorithm, encoding) #

This function generates hash signature with Hmac technique. The hash is encoded to a Hexadecimal or a base64 string.

Parameters #

Returns #

string - The result hash as String.

Samples #

// hash a string
var convertedMessage = sys.utils.crypto.hashHmac('my custom message', "mySecretKey", "HmacSHA256");
log('Hmac hex String : '+convertedMessage);

convertedMessage = sys.utils.crypto.hashHmac('my custom message', "mySecretKey", "HmacSHA256","BASE64");
log('Hmac base64 String : '+convertedMessage);

hs256(message, secret) #

This function converts a string to HS-256 hash.

Parameters #

Returns #

string - The result hash as String.

Samples #

// converts a message to the hash
var convertedMessage = sys.utils.crypto.hs256('my custom message','mySecretKey');
log('HS-256 string: '+convertedMessage);

verifySignatureWithHmac(payload, signature, secret, algorithm) #

This function verifies a signature with Hmac technique.

Parameters #

Returns #

boolean - true If the signature is valid, false otherwise.

Samples #

// hash a string
var result = sys.utils.crypto.jwt.verifySignatureWithHmac('my custom message',"signature","mySecretKey","HmacSHA256");
log('The signature is valid: '+result);

sys.utils.time #

This package contains methods for working with time.

getTimeZoneOffset(timeZoneId, timestamp) #

This function retrieves the offset in milliseconds between the specified time zone and the standard time zone (GMT). If daylight saving time is in effect in the specified time zone at the given timestamp, the offset value is adjusted to account for daylight saving time.

Parameters #

Returns #

number - The timezone offset in milliseconds.

Samples #

// Logs the specific time zone in hours
var offset = sys.utils.time.getTimeZoneOffset('America/Buenos_Aires');
log('offset in hours: '+offset/1000/60/60);

setTimeZone(date, timeZoneId) #

Apply the offset between given time zone and standard time zone (GMT) to the passed date.

Parameters #

Returns #

object - The date with the time zone applied.

Samples #

// Apply the specified time zone to the given date
var dateWithOffset = sys.utils.time.setTimeZone(new Date(), 'America/Buenos_Aires');
log('date modified: ' + dateWithOffset);

format(date, pattern, timezone) #

Apply the pattern and the time zone to a date and return it as string.

Parameters #

Returns #

string - The date with the time zone applied.

Samples #

// Apply the specified format and time zone to the given date
var formattedDate = sys.utils.time.format(new Date(), 'yyyy-MM-dd HH:mm Z', 'America/Buenos_Aires');
log('date formatted is: ' + formattedDate);

parse(date, pattern, timezone) #

Parse a date string using pattern and time zone and return it as date object.

Parameters #

Returns #

object - The final parsed date object with the time zone applied.

Samples #

// Parse given date using a specific pattern and timezone
var parsedDate = sys.utils.time.parse('2020-07-17 13:30', 'yyyy-MM-dd HH:mm', 'America/Buenos_Aires');
log('date is: ' + parsedDate);

sys.utils.concurrency #

This package contains methods to assist in managing concurrency issues.

tryLock(key, timeout) #

This function attempts to acquire a lock for a specified key. It is typically used when multiple threads require synchronization.

Important: Developers must ensure that locks are released. We recommend using try/finally clauses to handle this. While the platform will automatically release locks after the script is fully executed, it is a best practice to do so explicitly.

Parameters #

Returns #

boolean - true if the lock was acquired, false otherwise.

Samples #

// locks the key 'lock1'
if (sys.utils.concurrency.tryLock('lock1')) {
  try {
    sys.logs.info('lock acquired!');
  } finally {
    sys.utils.concurrency.unlock('lock1');
  }
}

lock(key, timeoutOrSuccessCallback, successCallback) #

This function acquires a lock for a specified key. It is typically used when multiple threads require synchronization.

Important: Developers must ensure that locks are released. We recommend using try/finally clauses to handle this. While the platform will automatically release locks after the script is fully executed, it is a best practice to do so explicitly.

Parameters #

Exceptions #

tiemout

If lock could not have been acquired.

Samples #

// locks the key 'lock1'
try {
  sys.utils.concurrency.lock('lock1');
  sys.logs.info('lock acquired!');
  //do something
  sys.utils.concurrency.unlock('lock1');
} catch (e) {
  sys.logs.error('lock NOT acquired!')
}

// locks the key 'lock1' using a callback
sys.utils.concurrency.lock('lock1', function () {
    sys.logs.info('lock acquired!');
});
// lock will be released automatically

unlock(key) #

Releases a lock for a specified key.

Parameters #

Samples #

// acquires and release the lock over key 'lock1'
if (sys.utils.concurrency.lock('lock1')) {
  try {
    log('lock acquired!');
  } finally {
    sys.utils.concurrency.unlock('lock1');
  }
}

forceUnlock(key) #

Releases a lock for a specified key. This is useful for mantenaince purposes.

Parameters #

Samples #

// acquires and force to release the lock over key 'lock1'
if (sys.utils.concurrency.lock('lock1')) {
  try {
    log('lock acquired!');
  } finally {
    sys.utils.concurrency.forceUnlock('lock1');
  }
}

sys.utils.script #

This package contains misc methods useful when scripting.

wait(timeToWait) #

Waits blocking the execution of the script.

Parameters #

Samples #

// waits for 2 seconds
sys.utils.script.wait(2000);
// continue execution

eval(scriptToEval, context) #

Evaluates JavaScript code represented as a string as classic eval but storing code to be displayed in case of errors.

Parameters #

Returns #

object - result of eval

Samples #

// waits for 2 seconds
sys.utils.script.wait(2000);
// continue execution