ImSmart Programmer's Guide
The programming language used in ImSmart is Javascript or more specifically the V8 open-source Javascript engine. You program modules, connectors and advanced triggers using Javascript. The variables you define on your Variables page are variables you can access and set in Javascript. When you set one of your variables value in Javascript, its value is immediately reflected on your Variables page. Triggers associated to the variable are not called when you set a value in Javascript.
All ImSmart scripts run in a self-contained environment where you cannot access any UI or DOM elements. Nevertheless it makes a very powerful and flexible tool. All scripts are time-restricted to 3 seconds. If the script runs longer than 3 seconds, it is aborted and a script timeout is recorded in the trigger activity logs.
All your variables are accessible from your trigger or module script. Technically, variables are also accessible from your connector script but you should avoid accessible specific variables since a connector should be made independant of user variables.
All variables defined in ImSmart, either in your Variables repository or in the definition of a connector must follow the ECMAScript 6 valid grammar. Avoid operator keywords as well as ImSmart and _ImSmart in your variable names. A connector can use variable _moduleKey which contains the connector key.
The object ImSmart is accessible and contains the following functions:
-
access(connName, paramName, N): Gets the value of an access parameter, given that
- connName is the connector name. connName can be a composite name that references a specific connector version from a specific user using the format username/connName/version. e.g. ImSmart/IFTTT/1, where ImSmart is the developer nickname, IFTTT is the connector name and 1 is the connector version. When you use the format username/connName, the latest version of the connector is used.
- paramName is the parameter name as defined in the Access Parameters section of the connector. Use the Name value and not Variable Name.
- N is the access number as indicated in your Access settings page.
For example, ImSmart.access('IFTTT', 'Key', 1) will return the access Key #1 which is needed in a WebHooks call.
-
http(url [, async]): This function calls a URL as defined by url. The content of the page is returned by the function. The async parameter determines if you simply wish to call the URL and forget it (async = true), in which case the URL is called in the background (and subject to a 30 seconds timeout) but no result is returned. When you need to get the value returned you need to use async = false. By default async is false. When called from the Simulator, the URL is not called but pushed into the virtual log on screen.
Example:
ImSmart.http('http://myweb.com/api/set?v=1');
For advanced HTTP calls, set the following http properties before calling the method http.send():
-
url: url to call. Use a complete URL with http:// or https://
-
async: asynchronous call. If asynchronous, no value is returned since the call does not wait for the response. Accepted value is true of false.
-
method: GET, POST, PUT or DELETE. By default GET is used.
-
args: arguments to add to the call. Each argument should be pushed in an array of 2 elements: one argument name and one argument value. See the example below.
-
headers: custom headers to add to the HTTP call. Each header value should be pushed in an array of 2 elements: one header name and one header value, just like args property.
Use the http object like this:
var myHttp = new ImSmart.http();
myHttp.url = 'http://myweb.com/api/set';
myHttp.method = 'POST';
myHttp.args.push(['arg1', 'value1']);
myHttp.args.push(['arg2', 'value2']);
myHttp.send();
When you call ImSmart.http with an url you don't have to call .send() as it is done implicitly using the GET method.
- import(name): equivalent to <script src=”module.js”></script> in Javascript and is used to load a module or connector. name can reference a module or connector name and it can be a composite name that references a specific module or connector version from a specific user using the format username/name/version. e.g. ImSmart/IFTTT/1, where ImSmart is the developer nickname, IFTTT is the connector name and 1 is the connector version. When you use the format username/name, the latest version of the module or connector is used.
-
localTime(): Returns a Javascript Date object of your user local date and time, according to your timezone settings. If you use new Date() you get the server local time, which probably does not fit your needs. You can then use the Javascript functions getFullYear, getMonth, getDay, getHours, getMinutes and getSeconds to accurately control your script.
Example:
if (ImSmart.localTime().getHours() >= 16)
maker.call('doSomething');
You cannot use localTime() to control when to execute a trigger but rather, when a trigger is executed, to control the flow based on time.
- log(message): Records a message into a trigger’s activity log. When called from the Simulator, the message is not logged in database but pushed into the virtual log on screen. When logging an access key, use format {{AccessKey:moduleKey:N}} where moduleKey is the Module Key that you can find in the module properties and N is the user's connector access number.
The object ImSmart also contains the following read-only values:
- fromSimulation: boolean value that indicates if the script has been called from the Simulator or not.
- fromEvent: boolean value that indicates if the script has been called from a scheduled event or not.
We have a good example in the following IFTTT script:
Maker = function Maker(keyN){
this.keyN = keyN;
this.call = MakerCall;
};
function MakerCall(MakerEvent, value1, value2, value3)
{
var key = ImSmart.access('IFTTT', 'Key', this.keyN);
var url = 'https://maker.ifttt.com/trigger/' + MakerEvent + '/with/key/' + key + '?';
var logUrl = 'https://maker.ifttt.com/trigger/' + MakerEvent + '/with/key/{{AccessKey:' + _moduleKey + '#' + this.keyN + '}}?';
if (value1 !== '' && value1 !== undefined)
{
url += 'value1=' + escape(value1) + '&';
logUrl += 'value1=' + escape(value1) + '&';
}
if (value2 !== '' && value2 !== undefined)
{
url += 'value2=' + escape(value2) + '&';
logUrl += 'value2=' + escape(value2) + '&';
}
if (value3 !== '' && value3 != undefined)
{
url += 'value3=' + escape(value3);
logUrl += 'value3=' + escape(value3);
}
ImSmart.http(url, true);
if (ImSmart.fromEvent)
ImSmart.log('Scheduled event executed. Called ' + logUrl);
else
ImSmart.log('Called ' + logUrl);
}
An object _ImSmart also exists for core functions but only acts as an interface to the ImSmart object. You should generally avoid using this object directly.