Skip to main content
Documentation - Scripting API
Reference Information
Limelight XE Scripting Language Extension API

OVERVIEW

Limelight XE™ contains an embedded ECMAScript 6 (ES6) compatible JavaScript engine with various language extensions that tightly integrate it with all core modules and drivers.  The Application Programming Interface (API) for the extensions is below.

SUMMARY

Below is a summary of all supported language extensions.

Core Objects

Object Version Description
ace 2.2+ This is the base object that contains the language extensions
ace.this 2.2+ Container object for local server values (limited)
 ace.this.serverGUID 2.2+ Returns the GUID of the local server (provided by registering the server following install)
ace.alarm 2.2+ Container object for all alarm values
 ace.alarm.serverGUID 2.2+ Returns the GUID of the server that holds the object responsible for an alarm
 ace.alarm.objectGUID 2.2+ Returns the GUID of the object responsible for the alarm condition
 ace.alarm.operatorGUID 2.2+ Returns the GUID of the current alarm operator (the user that acknowledged the alarm) if available
 ace.alarm.accountGUID 2.2+ Returns the GUID of the account involved with the alarm if available
 ace.alarm.notificationCode 2.2+ Returns the log entry code for the alarm
 ace.alarm.notification 2.2+ Returns the text of the alarm notification
 ace.alarm.location 2.2+ Returns the location text of the alarm (the text describing where this occurred)
 ace.alarm.priority 2.2+ Returns a code (0 – 7) of the severity of the alarm (0 = lowest, 7 = highest)

Core Functions 

Function Version Description
ace.getObjects() 2.2+ Requests the node structure of an object
ace.getProperty() 2.2+ Requests the value of an object's specific property
ace.getProperties() 2.2+ Requests all the properties from a single object
ace.setProperty() 2.2+ Sets a property value of an object
ace.notifyPropertyChange() 2.2+ Creates a background task to monitor an object's property for changes
ace.wait() 2.2+ Pauses a script a fixed number of milliseconds
ace.waitForProperty() 2.2+ Waits a fixed number of milliseconds for a property value to change
ace.getAccount() 2.2+ Requests an account object
ace.getAccountVariables() 2.2+ Requests all the user account variables
ace.getToken() 2.2+ Requests a token object
ace.sendSMS() 2.2+ Sends a short message service (SMS) message to a cellular phone
ace.sendEmail() 2.2+ Sends an email
ace.logEntry() 2.2+ Adds an entry to the log database

Browser Emulation and Global Functions

Function Version Description
console.clear() 2.2+ Clears the user console
console.count() 2.2+ Adds a count entry that increments every time the function is called
console.log() 2.2+ Adds a text line to the console log
console.time() 2.2+ Adds a timestamp to the console log
     
setTimeout() 2.2+ Creates a timeout task with a callback function
setInterval() 2.2+ Creates a time interval with a callback function
clearTimeout() 2.2+ Clears a background timeout task
clearInterval() 2.2+ Clears a background time interval task
clearNotification() 2.2+ Clears a background notification task

CONSOLE SUPPORT (support for the standard language console object) 

console.log()
  • Description: Adds a text (or formatted text) line to the console log.  It supports most ECMA-48 Select Graphic Rendition escape codes.  See the sample code below for examples.  When using a formatting string, use %s to indicate where to replace the text... arguments go in order, so the first argument string following the format string will replace the first occurrence of %s... and so on.
  • Parameters: This function takes one or more parameters
    • Text or Formatting string - text string to display in the user console or a formatting string (see below).
    • Text to replace %s when used with formatting string (argument 1).  Note: the number of %s sequences in the formatting string must equal the number of replacement string arguments or an error will be thrown.
  • Supported Versions: 2.2+
// clear the console
console.clear();
// Simple example code to display a message in the debugger console log.
console.log('this is a message to display in the console log');
// using formatting strings
console.log('\x1b[92m%s \x1b[91m%s\x1b[0m %s', 'This is bright green','and this is bright red', 'and this should be normal text');
// formatting tests
console.log('\x1b[1mText is bold');
console.log('\x1b[3mText is italic');
console.log('\x1b[4mText is underlined');
console.log('\x1b[9mText is striked');
console.log('\x1b[1m\x1b[3mText is bold italic');
console.log('\x1b[3m\x1b[4mText is italic underlined');
console.log(' '); // line break
// foreground tests
console.log('\x1b[31mForeground is red');
console.log('\x1b[32mForeground is green');
console.log('\x1b[33mForeground is yellow');
console.log('\x1b[34mForeground is blue');
console.log('\x1b[35mForeground is magenta');
console.log('\x1b[36mForeground is cyan');
console.log('\x1b[37mForeground is silver');
console.log('\x1b[90mForeground is gray');
console.log('\x1b[91mForeground is bright red');
console.log('\x1b[92mForeground is bright green');
console.log('\x1b[93mForeground is bright yellow');
console.log('\x1b[94mForeground is bright blue');
console.log('\x1b[95mForeground is bright magenta');
console.log('\x1b[96mForeground is bright cyan');
console.log('\x1b[97mForeground is bright white');
console.log(' '); // line break
// background tests
console.log('\x1b[30m\x1b[41mBackground is red with black text');
console.log('\x1b[30m\x1b[42mBackground is green with black text');
console.log('\x1b[30m\x1b[43mBackground is yellow with black text');
console.log('\x1b[37m\x1b[44mBackground is blue with white text');
console.log('\x1b[37m\x1b[45mBackground is magenta with white text');
console.log('\x1b[30m\x1b[46mBackground is cyan with black text');
console.log('\x1b[30m\x1b[47mBackground is silver with black text');
console.log('\x1b[30m\x1b[100mBackground is gray with black text');
console.log('\x1b[30m\x1b[101mBackground is bright red with black text');
console.log('\x1b[30m\x1b[102mBackground is bright green with black text');
console.log('\x1b[30m\x1b[103mBackground is bright yellow with black text');
console.log('\x1b[37m\x1b[104mBackground is bright blue with white text');
console.log('\x1b[30m\x1b[105mBackground is bright magenta with black text');
console.log('\x1b[30m\x1b[106mBackground is bright cyan with black text');
console.log('\x1b[30m\x1b[107mBackground is bright white with black text');
// clear formatting
console.log('\x1b[mThis should be default text');
console.log('\x1b[0mThis should also be default text');
console.time()
  • Descrption: This adds a timestamp to the console log.
  • Supported Versions: 2.2+
console.count()
  • Description: This adds a count entry that increments every time the function is called. 
  • Supported Versions: 2.2+
console.clear()
  • Description: This function clears the user's console. 
  • Supported Versions: 2.2+

BROWSER EMULATION AND EXTENSIONS (support for the standard language browser functions)

setTimeout()
  • Description: The setTimeout() method calls a function or evaluates an expression after a specified number of milliseconds. Use the clearTimeout() or clearNotification() methods to stop the function from running.  Note the function will only be called once. The created task (if successful) will run when the main thread has completed (exited execution as in a browser script) or when either ace.wait() or ace.waitForProperty() are called.
  • Parameters: This function takes 2 parameters plus optional parameters passed to the function.
    • function - the callback function or expression. 
    • Timout - the desired timeout in milliseconds.
  • Returns: Task ID - a unique ID that is greater than zero (0) if successful, 0 if failure.  Use the task ID in the clearTimeout() or clearNotification() functions to stop the background task.
  • Supported Versions: 2.2+
// set a timeout that will call back a function in 1 second with 2 optional parameters (up to 9999 parameters)
var optionalParam1 = 'foo bar';
var optionalParam2 = 42;
setTimeout(MyFunction, 1000, optionalParam1, optionalParam2);

// do the same with an embedded expression
setTimeout(function(){console.log('it worked')}, 1000);

function MyFunction(param1, param2) {
 console.log('Optional parameter 1 = ' + param1);
 console.log('Optional parameter 2 = ' + param2);
}
setInterval()
  • Description: The setInterval() method calls a function or evaluates an expression at specified intervals (in milliseconds). use the clearInterval() or clearNotification() methods to stop the function from running. The created task (if successful) will run when the main thread has completed (exited execution as in a browser script) or when either ace.wait() or ace.waitForProperty() are called.
  • Parameters: This function takes 2 parameters plus optional parameters passed to the function.
    • function - the callback function or expression. 
    • interval - the desired time interval in milliseconds.
  • Returns: Task ID - a unique ID that is greater than zero (0) if successful, 0 if failure.  Use the task ID in the clearInterval() or clearNotification() functions to stop the background task.
  • Supported Versions: 2.2+
// set a time interval that will call back a function roughly every second with 2 optional parameters (up to 9999 parameters)
var optionalParam1 = 'foo bar';
var optionalParam2 = 42;
setTimeout(MyFunction, 1000, optionalParam1, optionalParam2);

// do the same with an embedded expression
setInterval(function(){console.log('it worked')}, 1000);

function MyFunction(param1, param2) {
 console.log('Optional parameter 1 = ' + param1);
 console.log('Optional parameter 2 = ' + param2);
}
clearTimeout()
  • Description: Clears the specified timeout task running in the background
  • Parameters: This function takes one parameter
    • TaskID - the ID returned by the setter calling function.
  • Returns: value = 0: success, value > 0: failure.
  • Supported Versions: 2.2+
// create a timeout and then immediately kill it before it runs.
var tid = setTimeout(MyFunction, 1000);
clearInterval(tid);

function MyFunction() {
 // note the task never completes to run the callback
}
clearInterval()
  • Description: Clears the specified time interval task running in the background
  • Parameters: This function takes one parameter
    • TaskID - the ID returned by the setter calling function.
  • Returns: value = 0: success, value > 0: failure.
  • Supported Versions: 2.2+
// create an interval and then immediately kill it before it runs.
var tid = setInterval(MyFunction, 1000);
clearInterval(tid);

function MyFunction() {
 // note the task never completes to run the callback
}
clearNotification()
  • Description: Clears the specified notification task running in the background
  • Parameters: This function takes one parameter
    • TaskID - the ID returned by the setter calling function.
  • Returns: value = 0: success, value > 0: failure.
  • Supported Versions: 2.2+
// Example code on using ace.clearNotification()
(()=>{  // main script begins...
 // create object GUID constants for properties (previously created global variable)
 const varTestGUID = '{759161EB-1005-0010-0000-000000000001}';

 // create the call back notifications when these property's values change
 var theTaskID = ace.notifyPropertyChange(PropChangeCallback, ace.this.serverGUID, varTestGUID, 'Value');
 // now pass control to the system to monitor these values (an infinite wait)
 ace.wait();
})(); // end of main script...

function PropChangeCallback(id, serverGUID, objGUID, Value) {
 // stop future call-backs when this property changes again
 var success = clearNotification(id);
 // do any processing of this property here... for now, simply log it
 console.log('Task ID = ' + id + ', Success Value = ' + success);
 console.log('Server GUID = ' + serverGUID + ', Object GUID = ' + ObjGUID + ', Value = ' + Value);
}
Note: Task IDs come from a common pool so to remove any task, the clearNotification() call can be used in place of clearTimeout() or clearInterval(). The clearTimout() and clearInterval() functions are provided for code clarity and backward compatibility.

 

ACE SUPPORT (language extensions) 

Objects

ace.this
  • Description: Holds system specific values – more will be added as required
    • ace.this.serverGUID - returns the GUID of the server running the script.
  • Supported Versions: 2.2+
// Example code on using ace.this.serverGUID
(()=>{  // main script begins...
 console.log('The server GUID is : ' + ace.this.serverGUID);
})(); // end of main script...
ace.alarm
  • Description: Holds alarm information if the script was triggered by an alarm procedure.  It provides access to the server and object that caused the alarm along with the operator (if available) that is currently servicing the alarm.
    • ace.alarm.serverGUID - returns the GUID of the server that holds the object responsible for the alarm.
    • ace.alarm.objectGUID - returns the GUID of the object responsible for the alarm condition.
    • ace.alarm.operatorGUID - returns the GUID of the current alarm operator (the user that acknowledged the alarm) if available.  Some procedures may run without being acknowledged or due to a timeout in responding to the alarm.
    • ace.alarm.accountGUID - returns the GUID of the account involved with the alarm if available.  It may be equal to the universal system account GUID if no user is known or the action was caused by the system.
    • ace.alarm.notificationCode - returns the log entry code for the alarm.  This value is the category number for the type of alarm (e.g. Security – Invalid Credentials).
    • ace.alarm.notification - returns the text of the alarm notification.
    • ace.alarm.location - returns the location text of the alarm (the text describing where this occurred).
    • ace.alarm.priority - returns a code (0 – 7) of the severity of the alarm (0 = lowest, 7 = highest).
  • Supported Versions: 2.2+

Functions 

ace.getObjects()
  • Description: This function requests the node structure of an object. This is the same data that is passed to clients and used to display the object tree view in the Components tab of the console. 
  • Parameters: This function takes one parameter
    • object GUID 
  • Returns: Node structure which also includes all child objects owned by the object (see Object Node Structures for details)
    • serverGUID : The GUID of the server
    • GUID : The current object GUID
    • parentGUID : The parent object GUID
    • editorGUID : The editor object GUID (used internally by clients)
    • iconGUID : The icon object's GUID associated with this object
    • dataGUID : The optional data object GUID associated with this object
    • title : The object node title
    • hint : The hint or description of this object
    • menuControl : The menu control values assigned to this object
    • menuItems : The menu item string for this object
    • state : the state number of this object
    • dragControl : Drag control bits
    • options : Node options for this object 
    • objects : An array of child objects that have this identical structure
  • Supported Versions: 2.2+
// Example code - this recursively dumps all node objects and properties for the user variables
(()=>{  // main script begins...
 // -- constants --
 // GUID of the User Variables object (root container)
 const objGUID = '{759161EB-1005-0000-0000-000000000000}';
 // -- operational code begins here --
 console.clear(); // clear the console log
 // request all of the objects owned the parent (objGUID)
 var objs = ace.getObjects(ace.this.serverGUID, objGUID);
 // if successful, dump all child objects
 if (typeof objs != 'undefined') {
  // dump all object properties and their child objects
  Dump(objs, 0);
 }
})(); // end of main script...

function Dump(object, position) {
 var currentPosition = position;
 var offset = '';
 // update the offset
 for (var x=0; x < currentPosition; x++) {
  offset = offset + '  ';
 }
 // log the object name
 console.log(offset + 'OBJECT: ' + object.title);
 // increase the offset
 currentPosition++;
 // update the offset
 for (var x=0; x < currentPosition; x++) {
  offset = offset + '  ';
 }
 // now dump all the properties of this object
 for (var property in object) {
  if (typeof object[property] !== 'object') {
   console.log(offset + property + '=' + object[property]);
  }
 }
 // dump any child objects (objects are an array of object)
 if (typeof object.objects != 'undefined') {
  for (var i=0; i<object.objects.length; i++) {
   var child = object.objects[i];
   Dump(child, currentPosition);
  }
 }
}
ace.getProperty()
  • Description: This function returns the value of an object's specific property
  • Parameters: Requires 3 arguments
    • Server GUID: the GUID of the target server (local or remote)
    • Object GUID: the object GUID that is the target
    • Property Name: the property name in that object.
  • Returns:  Value of the object as a string (for compatibility across property types) if found, otherwise it is null.
  • Supported Versions: 2.2+  
// Example code for getProperty()
(()=>{  // main script begins...
 const TestGUID = '{759161EB-1005-0010-0000-000000000001}';
 // clear the console log
 console.clear();
 // request the property value of the first global variable
 var x = ace.getProperty(ace.this.serverGUID, TestGUID, 'Value');
 // display the value returned
 console.log('Value of x = ' + x);
})(); // end of main script...
ace.getProperties()
  • Description: This function requests all the properties from a single object.
  • Parameters: Requires 2 arguments
    • Server GUID: the GUID of the target server (local or remote)
    • Object GUID: the object GUID that is the target 
  • Returns: an object containing all the property names and values
  • Supported Versions: 2.2+ 
// Example code for getProperties()
(()=>{  // main script begins...
 // -- constants --
 // GUID of the System Management object
 const objectGUID = '{759161EB-1000-0000-0000-000000000000}';
 // -- operational code begins here --
 console.clear(); // clear the console log
 // get all the properties of the System Management object
 var obj = ace.getProperties(ace.this.serverGUID, objectGUID);
 // if it exists, process the needed info
 if (typeof obj != 'undefined') {
  // simply dump everything for testing
  for (var property in obj) {
   // for now list the properties and their values
   console.log(property + '=' + obj[property]);
  }
 }
})(); // end of main script...
ace.setProperty()
  • Description: This function sets a property value of an object.
  • Parameters: Requires 4 arguments
    • Server GUID: the GUID of the target server (local or remote).
    • Object GUID: the object GUID that is the target. 
    • Property Name: the property name in that object.
    • Property Value: the new value to set (the engine will .
  • Returns: the value that was actually set.  This allows the engine to set limits on the property Value and returns what actually was set for the property.  If the object doesn't exist or there was an error the result is null
  • Supported Versions: 2.2+  
// Example code for setProperty()
(()=>{  // main script begins...
 // define a constant for the GUID of a global variable that holds an integer
 const TestGUID = '{759161EB-1005-0010-0000-000000000001}';
 // clear the console log
 console.clear();
 // request the property value of the first global variable
 var x = ace.getProperty(ace.this.serverGUID, TestGUID, 'Value');
 // increment the value
 var y = parseInt(x) + 1;
 // store it back (and double check it changed - returns the new value)
 x = ace.setProperty(ace.this.serverGUID, TestGUID, 'Value', y);
 // display the value returned
 console.log('Value of x = ' + x);
})(); // end of main script...
ace.notifyPropertyChange()
  • Description: This function creates a background task to monitor an object's property for changes. The created task (if successful) will run when the main thread has completed (exited execution as in a browser script) or when either ace.wait() or ace.waitForProperty() are called.
  • Parameters: Requires 4 arguments
    • Call back function: the name of the function to call when the property changes.
    • Server GUID: the GUID of the target server (local or remote).
    • Object GUID: the object GUID that is the target. 
    • Property Name: the property name in that object.
  • Returns: Task ID for the background task. 0=failure, >0 if successful.
  • Callback: Returns 5 parameters - task ID, Server GUID, Object GUID, Property Name and Value (see sample below)
  • Supported Versions: 2.2+  
// Example code for notifyPropertyChange()
(()=>{  // main script begins...
// 2 global variables have been created - Test and Test2
// objGUID points to the root of all global variables so they can be referenced by name (not GUID)
 var objGUID ='{759161EB-1005-0010-0000-000000000000}';
 // set  notifications to callback when a property changes...
 var id1 = ace.notifyPropertyChange(PropChangeCallback, ace.this.serverGUID, objGUID, 'Test');
 var id2 = ace.notifyPropertyChange(PropChangeCallback, ace.this.serverGUID, objGUID, 'Test2');
 // report the task ID (should be > 0)
 console.clear();
 console.log('Task ID 1 = ' + id1);
 console.log('Task ID 2 = ' + id2);
 // wait for changes for ever...
 ace.wait();
}
// end of main script
)(); // end of main script...

// callback function
function PropChangeCallback(id, serverGUID, objGUID, propName, Value){
 console.log('id = ' + id);
 console.log('serverGUID = ' + serverGUID);
 console.log('objGUID = ' + objGUID);
 console.log('propName = ' + propName);
 console.log('Value = ' + Value);
}
ace.wait()
  • Description: This function waits a fixed number of milliseconds before returning.  There is no performance penalty for using this function since the thread is performing background processing while waiting.  Scripts run in a single thread so to allow background processing to occur use this function or ace.waitForProperty() when using notifications to allow background processing to occur.
  • Parameters: 1 argument (optional)
    • Delay: number of milliseconds to wait. If omitted, this function will wait indefinitely.
  • Returns: null 
  • Supported Versions: 2.2+ 
// Example code for ace.wait()
(()=>{  // main script begins...
 // clear the console log
 console.clear();
 // create a loop and wait 1 second between each cycle
 for (var x = 0;  x < 10; x++) {
  // display the value of x
  console.log('Value of x = ' + x);
  // wait 1 second
  ace.wait(1000);
 }
})(); // end of main script...
ace.waitForProperty()
  • Description: This function will wait a fixed number of milliseconds for a property value to change. 
  • Parameters: Requires 3 or 4 arguments (overloaded).
    • Server GUID: the server GUID that holds the target object
    • Object GUID: the object GUID that is the target
    • Property Name: the property name in that object
    • Delay: the number of milliseconds to wait for a change in the value.  If the delay value is not specified the call will wait forever.
  • Returns: The new value of the property after it changes or if it times out (optional) it returns the current value.
  • Supported Versions: 2.2+ 
// Example code for ace.waitForProperty()
(()=>{  // main script begins...
 // set a constant for a user defined global variable
 const TestGUID = '{759161EB-1005-0010-0000-000000000001}';
 // clear the console log
 console.clear();
 // now wait 5 seconds for that variable to change value
 var x = ace.waitForProperty(ace.this.serverGUID, TestGUID, 'Value', 5000); 
 // display the new value
 console.log('Value of x = ' + x);
})(); // end of main script...
ace.getAccount()
  • Description: This function requests an account by it's GUID.
  • Parameters: Requires 1 arguments
    • Account GUID: the account GUID that is assigned to the account object.
  • Returns: account object with populated properties (see details below)
  • Supported Versions: 2.2+  
// Example code for ace.getAccount()
(()=>{  // main script begins...
 // -- constants --
 // GUID of some account - for testing, replace with one from the account manager
 const acctGUID = '{CC9355F3-CDD3-4757-9F96-5F6784648781}';
 // -- operational code begins here --
 console.clear(); // clear the console log
 // request the account object
 var acct = ace.getAccount(acctGUID);
 // if the account exists, dump all the properties and their values
 if (typeof acct != 'undefined') {
  // simply dump everything for testing
  for (var property in acct) {
   // for now list the properties and their values
   console.log(' - ' + property + '=' + acct[property]);
  }
 }
})(); // end of main script...

Object Properties (case sensitive in JavaScript): 

  • GUID : account GUID
  • ownerGUID : account owner GUID (GUID of the user that created this account)
  • supervisorGUID : account's supervisor GUID
  • userID : account's user ID
  • description : description of the account
  • email : user's email address
  • name : name object that holds the following name information
    • prefix : prefix for name (e.g. Mr.)
    • first : first name
    • middle : middle name
    • last : last name
    • suffix : name suffix
    • full : a pseudo property that concatenates the first and last name
  • otherId1 : the account "other ID 1" field
  • otherId2 : the account "other ID 2" field
  • otherId3 : the account "other ID 3" field
  • otherId4 : the account "other ID 4" field
  • PIN : user's Personal Id Number
  • addr1 : address line 1
  • addr2 : address line 2
  • city : user's city
  • state : user's state
  • country : user's country
  • postal : user's postal code
  • phones : phone object that holds the following
    • line1 : Line 1 phone object that holds the following
      • number : the phone number
      • type : the phone type (e.g. home, fax, etc.)
    • line2 : Line 2 phone object that holds the following
      • number : the phone number
      • type : the phone type (e.g. home, fax, etc.) 
    • cell : cellular phone object that holds the following
      • number : cell number
      • type : (fixed as "Cellular")
      • carrierIndex : a number that identifies the cellular provider 
    • emergency : object that holds the following emergency phone info
      • number : emergency contact number (copied from contacts)
      • type : (fixed as "Emergency") 
  • contact : object holding contact information
    • name : contact name
    • type : contact type (e.g. spouse, mother, etc.)
    • phone : contact phone number (replicated above in phones.emergency.number) 
  • other : other information field
  • latitude : latitude of user (if known, else 0)
  • longitude : longitude of user (if known, else 0)
  • altitude : altitude of user (units: feet, if known, else 0 - sea level)
  • heading : current user heading (units degrees, if known, else 0°)
  • speed : current user speed (units MPH, if known, else 0 MPH) 
  • flags : account flags info (more detail on this later) 
  • CIR : Credentials Information Record value 
  • auditGUID : the GUID of the last person that changed the account 

 

ace.getAccountVariables()
  • Description: This function requests all the user account (local) variables from a specific account.  This is useful when data is tied to the currently logged-in user for settings and other information unique to a user.
  • Parameters: Requires 1 parameter
    • Account GUID: the GUID of the account object.
  • Returns: any variable objects assigned to the account.
  • Supported Versions: 2.2+
// Example code for getAccountVariables()
(()=>{  // main script begins...
 // -- constants --
 // GUID of some account - for testing, replace with one from the account manager
 const acctGUID = '{8595B705-2648-41FA-8908-2E92DCB951BC}';
 // -- operational code begins here --
 console.clear(); // clear the console log
 // request the account object variables (all of them)
 var acctVars = ace.getAccountVariables(acctGUID);
 // if the account exists, dump all the variable names and their values
 if (typeof acctVars != 'undefined') {
  // simply dump everything for testing
  for (var property in acctVars) {
   // for now display the variable name and value
   console.log(property + '=' + acctVars[property]);
  }
 }
})(); // end of main script...
ace.getToken()
  • Desciption: This function requests a token from the system.
  • Parameters: Requires 1 parameter:
    • Token GUID - the GUID of the token.
  • Returns:  Token object with the properties of that token if valid, else it returns null.
  • Supported Versions: 2.2+
// Example code for getToken()
(()=>{  // main script begins...
 // -- constants --
 // GUID of a token (replace with one from the token manager)
 const tokenGUID = '{A5EE9389-2A90-45C0-80E6-1E09EC48703F}';
 // -- operational code begins here --
 console.clear(); // clear the console log
 // get all the properties of the token object
 var token = ace.getToken(tokenGUID);
 // if it exists, process the needed info
 if (typeof token != 'undefined') {
  // simply dump everything for testing
  for (var property in token) {
   // for now list the properties and their values
   console.log(property + '=' + token[property]);
  }
 }
})(); // end of main script...

Token Properties (case sensitive in JavaScript)

  • tokenGUID : the GUID of the token (for completeness)
  • tokenID : the token ID (64 bit integer) - this is often used as the access code
  • acctGUID : account GUID of the owner of this token
  • facilityCode : a facility code (if used)
  • userCode : a user code (if used)
  • userData : user data (string - 255 bytes max - if used)
  • tokenType : token type identifier
  • tokenProtocol : token protocol identifier
  • currentZone : last zone accessed by this token
  • status : token status 
  • auditAcctGUID : the GUID of the account that last changed any settings
 
ace.sendSMS()
  • Description: This function sends a Short Message Service (SMS) message to a cellular phone based on the phone number and carrier. It utilizes email gateways by each cellular provider to access their network - the carrier index points to a table that contains the gateway information.  This information resides in the \ProgramData directory (under Strasis Systems) in the file carriers.csv and can be modified to add specific carriers that may be missing.  If this file is modified, the ACE service needs to be restarted in order to load this file.  When adding a new carrier, select an unused index number or there will be conflicts.
  • Parameters: Requires 4 arguments
    • Phone Number: the number to use for the SMS message
    • Carrier Index: the index of the carrier (used to structure the message)
    • Title: the title of the message (appears in the notification section of most phones)
    • Body: the message text
  • Returns: integer error code (0 = fail, 1=success)
  • Supported Versions: 2.2+ 
// Example code on using ace.sendSMS()
(()=>{  // main script begins...
 // -- constants --
 const number = '321-555-1212';
 const carrier = 960; // Verizon
 const title = 'A Test Message';
 const body = 'This is a test of the Limelight XE SMS handler';
 // send an SMS message to a cell phone
 if (ace.sendSMS(number, carrier, title, body)) {
  console.log('Message sent to ' + number);
 }
 else {
  console.log('Message failed to send');
 }
})(); // end of main script...

Carrier Index Table

Cellular Carrier Index Value (hex) Index Value (decimal) Comments
3 River Wireless 0x0010 16  
ACS Wireless 0x0020 32  
Alltel 0x0030 48  
AT&T 0x0040 64  
Bell Canada (1) 0x0050 80  
Bell Canada (2) 0x0060 96  
Bell Mobility 0x0070 112  
Bell Mobility (Canada) 0x0080 128  
Blue Sky Frog 0x0090 144  
Bluegrass Cellular 0x00A0 160  
Boost Mobile 0x00B0 176  
BPL Mobile 0x00C0 192  
Carolina West 0x00D0 208  
Cellular One 0x00E0 224  
Cellular South 0x00F0 240  
Centennial Wireless 0x0100 256  
CenturyTel 0x0110 272  
Cingular 0x0120 288  
Clearnet 0x0130 304  
Comcast 0x0140 320  
Corr Wireless Communications 0x0150 336  
Dobson 0x0160 352  
Edge Wireless 0x0170 368  
Fido 0x0180 384  
Golden Telecom 0x0190 400  
Helio 0x01A0 416  
Houston Cellular 0x01B0 432  
Idea Cellular 0x01C0 448  
Illinois Valley Cellular 0x01D0 464  
Inland Cellular Telephone 0x01E0 480  
MCI 0x01F0 496  
Metro PCS 0x0200 512  
Metrocall 0x0210 528  
Metrocall 2-way 0x0220 544  
Microcell 0x0230 560  
Midwest Wireless 0x0240 576  
Mobilcomm 0x0250 592  
MTS 0x0260 608  
Nextel 0x0270 624  
OnlineBeep 0x0280 640  
PCS 0x0290 656  
President's Choice 0x02A0 672  
Public Service Cellular 0x02B0 688  
Qwest 0x02C0 704  
Rogers AT&T Wireless 0x02D0 720  
Rogers Canada 0x02E0 736  
Solo Mobile 0x0300 768  
Southwestern Bell 0x0310 784  
Spectrum 0x0318 792 Uses Verizon gateway
Sprint 0x0320 800  
Sumcom 0x0330 816  
Surewest Communicaitons 0x0340 832  
Telus 0x0350 848  
T-Mobile 0x0360 864  
Tracfone 0x0370 880  
Triton 0x0380 896  
Unicel 0x0390 912  
US Cellular 0x03A0 928  
US West 0x03B0 944  
Verizon 0x03C0 960  
Virgin Mobile 0x03D0 976  
Virgin Mobile Canada 0x03E0 992  
West Central Wireless 0x03F0 1008  
Western Wireless 0x0400 1024  

 

ace.sendEmail()
  • Description: This function programmatically sends an email.
  • Parameters: Requires 3 arguments (1 optional argument)
    • Email: email recipient in the form someone@somedomain (e.g. abcuser1234@gmail.com)
    • Subject: the subject of the email
    • body: the body text
    • Content Type (optional): Message content-type (e.g. text/html, text/xml)
  • Returns: integer error code (0 = fail,1 = success)
  • Supported Versions: 2.2+
// Example code on using ace.sendEmail()
(()=>{  // main script begins...
 // -- constants --
 const email = 'myuser@mydomain.com';
 const subject = 'A Test Email';
 const body = 'This is a test of the Limelight XE email handler';
 // send an email to the recipient
 if (ace.sendEmail(email, subject, body)) {
  console.log('Email sent to ' + email);
 }
 else {
  console.log('Email failed to send');
 }
})(); // end of main script...

 

ace.logEntry()
  • Description: This function adds an entry to the log database.
  • Parameters: Requires 6 arguments plus 2 optional
    • LogEntryType: 0=Information, 1=Warning, 2=Error, 3=Alarm
    • LogEntryCode: a 32 bit unsigned integer representing the Log Entry Code
    • AccountGUID: The GUID of the account responsible for the entry
    • ObjectGUID: The GUID of the object referenced in the entry
    • Description: Primary description text of the entry
    • AdditionalInformation: Additional information (topics delimited by a semicolon ";")
    • LogGUID (optional): The GUID of the log to place the entry
    • ServerGUID (optional): The GUID of the server referenced in the entry
  • Returns: integer error code (0 = fail,1 = success)
  • Supported Versions: 2.2+
// Example code on using ace.logEntry()
(()=>{  // main script begins...

 // log to the main system log (code 0x00000001)
 ace.logEntry(
  0, // information
  1, // code 0x00000001 (user created code)
  '{759161EB-1000-0000-0000-000000000000}', // system account
  '{00000000-0000-0000-0000-000000000000}', // no object
  'Test Entry',
  'This is a test of the script logging ability'
  );

})(); // end of main script...

 

Related Topics

About

Strasis Systems, LLC is a provider of software for command and control centers, data visualization, security and systems integration.