Skip to content
CIMON-Canvas v4.2.1

Script Functions List

Script Functions Table

Script Functions

All functions must be used with parenthesis
Function Description
alarm.createAllCsv(enum storageType) Saves all the messages at the assigned Storage type as a CSV.
Enter the number or string below as the user’s declared Storage type:
1: Storage.Local
2: Storage.Usb
3: Storage.SdCard
4: Storage.Ftp
5: Storage.Project
The return value is undefined.
Example: 
alarm.createAllCsv(1);
alarm.createCsv(String label, enum storageType) Saves all the alarm messages associated with the String label at the assigned Storage type as a CSV.
String label refers to one of the labels within the Alarm Settings. Users can create their own labels or use a preset label.
Enter the number or string below as the user’s declared Storage type:
1: Storage.Local
2: Storage.Usb
3: Storage.SdCard
4: Storage.Ftp
5: Storage.Project
The return value is undefined.
Example: 
alarm.createCsv("A", 1);
datalog.addRow(String modelName) Causes the Data Log Model specified to have a single row added to it.
String modelName refers to the name of the data log model to be targeted.
The return value is undefined.
Example: 
datalog.addRow("LoggingModel");
datalog.createCsv(String modelName, enum storageType) Creates a CSV file of the Data Log Model specified at the designated location.
String modelName refers to the name of the data log model to be targeted.
Enter the number or string below as the user’s declared Storage type:
1: Storage.Local
2: Storage.Usb
3: Storage.SdCard
4: Storage.Ftp
5: Storage.Project
The return value is undefined.
Example: 
datalog.createCsv("LoggingModel", 1);
datalog.createCsvForRange(String modelName, Date start, Date end, enum storageType) Creates a CSV file of the Data Log Model specified at the designated location with a set time boundary.
String modelName refers to the name of the data log model to be targeted.
Enter the number or string below as the user’s declared Storage type:
1: Storage.Local
2: Storage.Usb
3: Storage.SdCard
4: Storage.Ftp
5: Storage.Project
Date start refers to the first day that it will collect data from.
Date end refers to the last day that it will collect data from.
The return value is undefined.
Example: 
datalog.createCsvForRange("LoggingModel", 1, 31, 1);
datalog.start(String modelName) Causes the Data Log Model specified to begin logging data.
String modelName refers to the name of the data log model to be targeted.
The return value is undefined.
Example: 
datalog.start("LoggingModel");
datalog.stop(String modelName) Causes the Data Log Model specified to stop logging data.
String modelName refers to the name of the data log model to be targeted.
The return value is undefined.
Example: 
datalog.stop("LoggingModel");
driver.enable(Device Name) Enables the specified device.
Device Name refers to the name of the device to enable.
Example: 
driver.enable("PLC");
driver.disable(Device Name) Disables the specified device.
Device Name refers to the name of the device to disable.
Example: 
driver.disable("PLC");
keyboard.launchKeyboard(tagname, properties) Creates a popup keyboard to set a tag to the user input value.
tagname refers to the name of the tag to be set.
properties refer to optional specifying parameters that can change components of the keyboard. The following options are:
  • header: Sets the text at the top of the keyboard.
  • subheader: Sets the text below the header.
  • x: Sets the X position for the keyboard.
  • y: Sets the Y position for the keyboard.
The return value is undefined.
Example: 
keyboard.launchKeyboard("number", { header: "Header", subheader: "Subheader", x: 50, y: 50 });
keyboard.launchKeypad(tagname, properties) Creates a numeric keypad popup to set a tag to the user input value.
tagname refers to the name of the tag to be set.
properties refer to optional specifying parameters that can change components of the keypad. The following options are:
  • header: Sets the text at the top of the keypad.
  • subheader: Sets the text below the header.
  • x: Sets the X position for the keypad.
  • y: Sets the Y position for the keypad.
  • format: Can be set to either Decimal or Hexadecimal.
  • rawMin: Set the minimum value accepted for the keypad.
  • rawMax: Set the maximum value accepted for the keypad.
  • scaledMin: Sets the minimum scale value for the keypad.
  • scaledMax: Sets the maximum scaled value for the keypad.
The return value is undefined.
Example: 
keyboard.launchKeypad("Number", { header: "Header", subheader: "Subheader", x: 50, y: 50, format: "HH", rawMin: 5, rawMax: 20 });
keyboard.sendKeyEvent(keycode) Simulates a keystroke for an integer keycode.
keycode is a code that indicates which key to simulate, either in hexadecimal or decimal.
Example: 
keyboard.sendKeyEvent(0x20);
notification.send(string msg, int dismissInterval = -1) Sends a popup notification to the screen runtime displaying the specified message.
string msg refers to the string to be displayed in the notification.
int dismissInterval refers to an optional number of seconds before the notification is automatically dismissed.
If dismissInterval is less than 0, the message will stay until manually dismissed.
The return value is 0.
Example: 
notification.send("This is a notification");
page.close(string name) Closes the page with the specified name.
string name refers to the name of the page to be closed.
The return value is undefined.
Example: 
page.close("Page 1");
page.closeIndex(number index) Closes the base page with the specified index.
number index refers to the index of the base page to be closed.
The return value is undefined.
Example: 
page.closeIndex(1);
page.open(string name) Opens the page with the specified name.
string name refers to the name of the page to be opened.
The return value is undefined.
Example: 
page.open("Page 2");
page.openIndex(number index) Opens the base page with the specified index.
number index refers to the index of the base page to be opened.
The return value is undefined.
Example: 
page.openIndex(1);
recipe.createRecord(string recipe, int id, string name, List<Value> values) Creates a new record with the given parameters and adds it to the local recipe database.
string recipe refers to the recipe database to add the new record to.
int id refers to the Record ID of the new record.
string name refers to the name of the record.
List<Value> values refers to a list of parameter values to store in the record.
The return value is undefined.
Example: 
recipe.createRecord("RecipeName", tag.read("MaxRecordId") + 1, "Orange", ["#FFA500"] );
recipe.deleteRecord(string recipe, int id) Deletes the given record from the recipe database.
string recipe refers to the recipe database to delete the record from.
int id refers to the ID of the record to be deleted.
The return value is undefined.
Example: 
recipe.deleteRecord("RecipeName", tag.read("Switch"));
recipe.exportCsv(string recipe, Storage type, string path) Saves recipe data in a CSV at the specified path.
string recipe refers to the recipe database.
Enter the number or string below as the user’s declared Storage type:
1: Storage.Local
2: Storage.Usb
3: Storage.SdCard
4: Storage.Ftp
5: Storage.Project
string path refers to where to find the CSV file, relative to the storage location.
The return value is undefined.
Example: 
recipe.exportCsv("RecipeName", 1, "RecipeScript.csv");
recipe.getAllParameters(string recipe) Returns a list of the current parameter values from the device (the current tag values).
string recipe refers to the recipe database.
The return value is a list of the current tag values.
Example: 
recipe.getAllParameters("RecipeName");
recipe.getParameter(string recipe, int id, int index) Returns a single parameter value from a given record from the recipe database.
string recipe refers to the recipe database.
int id refers to the Record ID of the record.
int index refers to the position within the recipe.
The return value is the value of the specified cell.
Example: 
recipe.getParameter("RecipeName", tag.read("Switch"), 0);
recipe.getParameterByName(string recipe, int id, string name) Returns a single value from the given record from the named column.
string recipe refers to the recipe database.
int id refers to the Record ID of the record.
string name refers to the parameter the user wants to grab data from.
The return value is the value of the specified cell.
Example: 
recipe.getParameterByName("RecipeName", tag.read("Switch"), "color");
recipe.getRecordName(string recipe, int id) Returns the name of the given record from the selected recipe database.
string recipe refers to the recipe database.
int id refers to the Record ID of the record.
The return value is the name of the record.
Example: 
recipe.getRecordName("RecipeName", tag.read("Switch"));
recipe.getRecordValues(string recipe, int id) Returns the values stored in a record from the local recipe model.
string recipe refers to the recipe database.
int id refers to the Record ID of the record.
The return value is a list of values stored in the record.
Example: 
recipe.getRecordValues("RecipeName", tag.read("Switch"));
recipe.importCsv(string recipe, Storage type, string path) Replaces recipe data with the data found in a CSV at the path.
string recipe refers to the recipe database.
Enter the number or string below as the user’s declared Storage type:
1: Storage.Local
2: Storage.Usb
3: Storage.SdCard
4: Storage.Ftp
5: Storage.Project
string path refers to where to find the CSV file, relative to the storage location.
The return value is undefined.
Example: 
recipe.importCsv("RecipeName", 1, "RecipeScript.csv");
recipe.setParameter(string recipe, int id, int index, Value value) Sets a single value (cell) in the given recipe database for a given record and parameter.
string recipe refers to the recipe database.
int id refers to the Record ID of the record.
int index refers to the position (column number) of the parameter within the recipe.
Value value refers to the new value that will be set.
The return value is undefined.
Example: 
recipe.setParameter("RecipeName", tag.read("Switch"), 0, "#FFA500");
recipe.setParameterByName(string recipe, int id, string name, Value value) Sets a single value (cell) in the given recipe database for the given record and column name.
string recipe refers to the recipe database.
int id refers to the Record ID of the record.
string name refers to the parameter the user wants to set data to.
Value value refers to the new value that will be set.
The return value is undefined.
Example: 
recipe.setParameterByName("RecipeName", tag.read("Switch"), "color", "#FFA500");
recipe.setRecord(string recipe, int id, List<Value> values) Updates the values of a record from the local recipe database.
string recipe refers to the recipe database.
int id refers to the Record ID of the record.
List<Value> values refers to a list of values to store in the record. The list should contain one value for each parameter in the recipe.
The return value is undefined.
Example: 
recipe.setRecord("RecipeName", tag.read("Switch"), ["#FFA500"])
recipe.setRecordId(string recipe, int oldId, int newId) Updates the record ID for a record in the specified recipe database.
string recipe refers to the recipe database.
int oldId refers to the old Record ID of the record.
int newId refers to the new Record ID of the record.
The return value is undefined.
Example: 
recipe.setRecordId("RecipeName", tag.read("Switch"), tag.read("Switch") + 1);
recipe.setRecordName(string recipe, int id, string name) Updates the name of a record from the specified recipe database.
string recipe refers to the recipe database.
int id refers to the Record ID of the record.
string name refers to the new name that will be assigned to the record.
The return value is undefined.
Example: 
recipe.setRecordName("RecipeName", tag.read("Switch"), "New Name");
schedule.isEnabled(string title) Returns a Boolean indicating whether the schedule is enabled or not.
string title refers to the name of the schedule that is being checked.
Example: 
schedule.isEnabled("Schedule");
schedule.setEnable(string title, bool enable) Turns the named schedule on or off based on what bool enable is set to.
string title refers to the name of the schedule that is being enabled/disabled.
bool enable can only be set to true to enable the schedule or false to turn off the schedule.
The return value is undefined.
Example: 
schedule.setEnable("Schedule", 1);
system.audio.playFile(Storage type, string relativePath, bool async = true) Plays an audio file at the designated location.
Enter the number or string below as the user’s declared Storage type.
1: Storage.Local
2: Storage.Usb
3: Storage.SdCard
4: Storage.Ftp
5: Storage.Project
string relativePath refers to the path to the audio file.
If async is true, it will return immediately; otherwise, it will finish when the audio file is complete.
The return value is the audio file.
Example: 
system.audio.playFile(1, "Path");
Previously sold CM-eXT07 and CM-nXT07 devices produced before November of 2024 do not support this feature.
system.audio.stopFile(Storage type, string relativePath) Stops all audio files at the specific location.
Enter the number or string below as the user’s declared Storage type.
1: Storage.Local
2: Storage.Usb
3: Storage.SdCard
4: Storage.Ftp
5: Storage.Project
string relativePath refers to the path to the audio file.
The return value is the audio file.
Example: 
system.audio.stopFile(1, "Path");
Previously sold CM-eXT07 and CM-nXT07 devices produced before November of 2024 do not support this feature.
system.audit.log(description) Logs the entered description in the audit database.
description refers to the text to be added to the database.
The return value is undefined.
Example: 
system.audit.log("Text");
system.currentUsername() Returns the current Username of the current logged-in User.
Example: 
notification.send(system.currentUsername());
system.display.enableBacklight(Boolean) Turns the backlight of the Xpanel on or off.
0: Backlight off
1: Backlight on
Warning: Do not use this script with the auto-dimming or auto-sleep features. It may cause unintended behavior.
Example: 
system.display.enableBacklight(0);
system.email.send(properties) Sends an email using the SMTP settings.
properties refer to specific email properties including:
  • to
  • cc
  • subject
  • body
The return value is undefined.
Note: This function will not work in the offline simulator.
Example: 
var properties = { to: "test@gmail.com", cc: "test2@gmail.com", subject: "Script Email Send", body: "This email is an example of how the system.email.send function works." };
system.email.send(properties);
system.exit() Closes the current project and runtime application.
The return value is undefined.
Example: 
system.exit();
system.file.exists(Storage type, String path = string()) Determines whether a file exists at the given path.
Enter the number or string below as the user’s declared Storage type.
1: Storage.Local
2: Storage.Usb
3: Storage.SdCard
4: Storage.Ftp
5: Storage.Project
String path refers to the path to the file.
The return value is true or false.
Example: 
system.file.exists(1, "Test.txt");
system.file.isDirectory(Storage type, String path) Determines whether the path is a directory or not.
Enter the number or string below as the user’s declared Storage type.
1: Storage.Local
2: Storage.Usb
3: Storage.SdCard
4: Storage.Ftp
5: Storage.Project
String path refers to the path to the directory.
The return value is true or false.
Example: 
system.file.isDirectory(1, "Documents");
system.file.openDialog(Storage type, String path = string()) Opens a dialog to select a file at the given path.
Enter the number or string below as the user’s declared Storage type.
1: Storage.Local
2: Storage.Usb
3: Storage.SdCard
4: Storage.Ftp
5: Storage.Project
String path refers to the path for selecting a file.
The return value is undefined.
Example: 
system.file.openDialog(1, "Documents");
system.file.openPdf(Storage type, String path) Opens the PDF viewer with the specified file.
Storage type:
1: Storage.Local
2: Storage.Usb
3: Storage.SdCard
4: Storage.Ftp
5: Storage.Project
String path refers to the path to the file.
The return value is true if the PDF opened, or false if it did not.
Note: This function will not work in the simulator.
Example: 
system.file.openPdf(Storage.Project, "my_folder/my_file.pdf");
system.file.saveDialog(Storage type, String path = string()) Opens a dialog to save a file at the given path.
Enter the number or string below as the user’s declared Storage type.
1: Storage.Local
2: Storage.Usb
3: Storage.SdCard
4: Storage.Ftp
5: Storage.Project
String path refers to the path for saving a file.
The return value is undefined.
Example: 
system.file.saveDialog(1, "Documents");
system.ftp.startServer() Starts a local FTP server.
The return value is undefined.
Note: This function will not work in the simulator.
Example: 
system.ftp.startServer();
system.ftp.stopServer() Stops a local FTP server.
The return value is undefined.
Note: This function will not work in the simulator.
Example: 
system.ftp.stopServer();
system.hasPermission(string permission) Check to see if the currently logged-in user has the specified permission.
string permission refers to the name of the permission being checked.
The return value is true if the user has permission and false if the user does not.
Example: 
system.hasPermission("Permission 1");
system.importScript(string scriptName) Executes a specified script in the current project on the current thread.
string scriptName refers to the target script that will run within the current script.
The return value would be whatever the result of the called script is.
Example: 
system.importScript("Script");
system.login(string username, string password) Immediately logs in the user for the Identity and Access Management feature.
string username refers to the name of the user to log in to.
string password refers to the password for the specific user. This argument can be omitted without a password or an empty string.
The return value is true if the user is successfully logged in; false if unsuccessful.
Example: 
system.login("Username", "Password");
system.logout() Logs out of the current user from the Identity and Access Management system.
The return value is undefined.
Example: 
system.logout();
system.openAuthWindow(properties) Opens the built-in dialog for authenticating a user. Users will have to re-enter username and password.
properties refer to optional parameters that can change components of the function. The options are:
Username: Sets the user to be authenticated. If no user is provided, it will authenticate any user that enters their username and password. If no user is logged in, it will return false.
Permissions: Only allows users with the listed permissions to log in. If they do not have permission, login will not complete.
The return value is true if logged in, otherwise false.
Example: 
var properties = { permissions: "Permission 1" };
system.openAuthWindow(properties);
system.openConfig() Opens the runtime config (3 corner method) menu.
The return value is undefined.
Example: 
system.openConfig();
system.openFrameMonitor() Opens the Frame Monitor.
The return value is undefined.
Note: This function will not work in the simulator.
Example: 
system.openFrameMonitor();
system.openLoginWindow(properties) Opens the login window from the Identity and Access Management system.
properties refer to optional specifying parameters that can change components of the function.
The only option is:
listUsers: A toggle to show the list of all available users, or to have the user type in the username.
The return value is undefined.
Example: 
var properties = { listUsers: 1 };
system.openLoginWindow(properties);
system.runScript(string scriptName) Executes a specified script in the current project on a separate thread.
string scriptName refers to the target script that will run within the current script.
The return value is undefined.
Example: 
system.runScript("Script");
system.screenshot(Storage type) Takes a screenshot of the screen during runtime.
Storage type:
2: Storage.Usb
3: Storage.SdCard
Example: 
system.screenshot(Storage.Usb);
system.setLanguage(string language) Sets the language to be used by the Translation Editor.
string language refers to the name of the language to be used. This should be one of the columns in the Translation Editor.
The return value is undefined.
Example: 
system.setLanguage("English");
system.video.playFile(Storage type, String path) Opens a video for playback from the specified location.
Storage type:
1: Storage.Local
2: Storage.Usb
3: Storage.SdCard
4: Storage.Ftp
5: Storage.Project
String path refers to the path to the file.
The return value is true if the video played, or false if it did not.
Note: This function will not work in the simulator.
Example: 
system.video.playFile(Storage.Project, "my_folder/my_video.mp4");
This will only work on the eXT2 series.
system.video.stop() Stops the current video playback on the runtime.
Note: This function will not work in the simulator.
Example: 
system.video.stop();
This will only work on the eXT2 series.
tag.read(string name) Gets the current value of the specified tag.
string name refers to the name of the tag.
The return value depends on the type of the tag; a BOOL will return a BOOL, a String will return a String, etc.
Example: 
tag.read("TagName");
tag.write(string name, value) Sets the value of the specified tag.
string name refers to the name of the tag.
Value refers to what the tag will be set to.
The return value is undefined.
Example: 
tag.write("TagName", tag.read("TagName") + 1);
thread.msleep(number msecs) Suspends the current thread for the specified amount of milliseconds.
number msecs refers to the number of milliseconds the program will wait before continuing execution.
The return value is undefined.
Example: 
thread.msleep(100);
thread.sleep(number secs) Suspends the current thread for the specified amount of seconds.
number secs refers to the number of seconds the program will wait before continuing execution.
The return value is undefined.
Example: 
thread.sleep(100);