Basic Concepts

What is Scriptr.io?

Scriptr.io is a very powerful cloud service to run your server-side code. With scriptr.io, you use scripts to create the custom back-end APIs needed to power your Internet of Things (IoT) and other projects. Scriptr.io allows you to get productive quickly by providing an integrated web-based environment for developing, running and debugging your code. 

What are Scripts?

Scripts are units of execution, after you create a script, it immediately becomes a web service with a unique secure HTTP end-point and ready to run as soon as it is invoked. Scripts can be created to be used as web services or as modules for other scripts. You can invoke directly your new scriptr.io APIs from an IoT, mobile or web project or from other web services.

What is the Difference between Using scriptr.io and Running Your Own Servers?

With scriptr.io, you don't need to handle hosting, deployment, management and upgrade of servers such as application containers, database servers or libraries to integrate with social networks and other web services. When your product goes to production and you need quick reliable scaling, you don't have to figure-out server architecture, scalability strategies, fault-tolerance, etc... You only concentrate on improving the business logic needed to power your project while we make sure that everything else is running smoothly for you.

Supported Languages

For now our script containers support JavaScript. We will be adding other languages in the future.

What about Authentication and Security?

Invoking scriptr.io URLs

Scriptr.io scripts are invokable based on the following patterns for the POST and GET methods respectively:

curl -X POST -F <requestParameter> -d <postBody> -H "Authorization: bearer <authorizationToken>" "https://api.scriptrapps.io/<scriptName>"

curl -X GET -H "Authorization: bearer <authorizationToken>" "https://api.scriptrapps.io/<scriptName>?<requestParameter>"

"value1":"some value", "value2":"some value", "value3":"some value".

What are Experimental Features? 

At scriptr.io, we keep improving our product to bring you the best. You might encounter several features that our team is still developing - they are labelled with the Experimental tag. You may tinker with them as much as you want, but beware that these experimental features might change, break, or disappear at any time.

Getting Started

Open an Account

You can create a new scriptr.io account from this page by providing your email and a password, or signing in with your GitHub, Twitter or Facebook account. 

Write Your First Script and Run It

Once you log in to scriptr.io, you land on your workspace. There are plenty of very useful features in it. For now, we will just go ahead and create our first script by clicking New Script at the lower left corner of the screen.

In the scriptr.io editor, simply add a line to return the traditional "Hello world":

return "Hello world";

Now run your script by clicking Run on the top-right part of the editor. Notice the console in the lower half of the screen where you can see the result of the execution. The first line of the console is the curl instruction to issue from an HTTP client to trigger the execution of your script.

What Can a Script Do? 

Well, actually, a lot. When using scripts, you have access to a very rich set of features and modules that are provided to you by scriptr.io, such as storage, gateways to IoT platforms, gateways to external web services, social networks, etc... Scripts allow you to implement all the business logic for your IoT solution.

// import the scriptr.io http module to issue calls to remote APIs
var http = require("http");

// retrieve the station parameter from the request
var station = request.parameters.station; // use location = 260

var weatherStationAPI = "http://fawn.ifas.ufl.edu/controller.php/today/obs/" + station + ";json";
// invoke the weatherStationAPI third party API
var callResult = http.request({
		"url" : weatherStationAPI
	});
// parse the result of the call using regular JSON object
var weatherInfo = JSON.parse(callResult.body); // returns an array of today's observations
var latestInfo = weatherInfo[0]; // get latest observation, first one on the list
var temperature2m = latestInfo.t2m;
var windSpeed = latestInfo.ws;
// return the result of the function call
return getAmbianceConfiguration(temperature2m, windSpeed);

// define a bespoke function
function getAmbianceConfiguration(temp, wind) {
	var tempCategory = (temp < 18) ? "Cold" : (temp >= 18 && temp <= 25) ? "Cool" : "Hot";
	var windCategory = wind < 20 ? "No Wind" : (wind > 20 && wind < 50) ? "Windy" : "Strong Wind";
	return {
		"temp" : tempCategory,
		"wind" : windCategory
	};
}

Authentication and Security

What are Tokens?

Tokens are credentials that you send with your requests to authenticate yourself and gain access to your protected resources in your scriptr.io account.

Upon registration, scriptr.io provides you with the "scriptr" device and its token which are used within the IDE to execute your scripts. You can also send this token along with your requests in order to authenticate yourself as the owner of the application. Note that you should keep this token secret and not distribute it.

However, you can always create more devices and tokens to control who has access to your application. Managing your devices and tokens can be achieved using the Device Directory in your scriptr.io account or programmatically by calling the APIs of the device module.

What is an Anonymous Token?

Sometimes you will want to allow end users / devices to invoke your scripts without any authentication. Yet you still want to control who / what is able to do so. For that purpose, scriptr.io provides you with an Anonymous Token (similar to API keys) that you can distribute to those users.

How to Get Your Tokens?

Two tokens have automatically been generated for you when you first registered to scriptr.io. You can find them in your account's Info tab by clicking your username at the top-left corner of your workspace, then selecting Account. Moreover, you can create more tokens from the Device Directory section.

How to (Re)Generate Your Tokens?

Under the Device Directory, in the Device tab, click the regenerate icon in order to create a new token.

How to Use Your Tokens?

When invoking scriptr.io, you can pass a token to the request in one of the following ways:

• In the request's Authorization header, such as "Auhtorization: bearer yourToken".
• In the request's auth_token parameter.

Scriptr.io IDE

IDE Overview 

Scriptr.io provides an efficient web based IDE that gets you productive as soon as you sign up. 

i

Create a new script by clicking on "New Script".

i

Create different script or file types by clicking the arrow icon next to the New Script button, then selecting desired type such as Blockly Script, Google Charts or HTML file.

i

All the scripts you created are listed under "My Scripts". If you grouped your scripts into folders, click on the arrow next to the folder name to expand its content.

i

A merged list of your scriptr.io scripts and the scripts that you have under your GitHub repository will be displayed under "Synchronize". A contextual menu will give you the option of committing and updating the selected files.

i

When creating a new script, you need to give it a name. You can specify here the path (folders) to your script. For modifying the name of an existing script, click on the pencil icon.

i

Edit your script code in this section.

i

Navigate through the scripts that you already opened in the IDE by clicking on their respective tab.

i

You can run a script by clicking Run. If you want to pass request parameters to the script, click the drop-down arrow then click Run....

i

Open the Schedule overlay so you can schedule your scripts. You have the option to pick either a one-time schedule or a recurrent schedule.

i

Subscribe the active script to a channel so that it can read and execute business logic on all the messages published to that channel.

i

This is where you access all the tools you need to manage and configure your application.

i

Show the cheat sheet to view the list of the IDE shortcuts.

i

The Access Control List button displayed at the top right corner of the editor allows you to specify who can access the resource.

i

The console is where the outcome of your script is displayed. It also contains the curl instruction that was used to invoke your script.

i

The Notifications is where the outcome of your GitHub commit or update is displayed.

i

Hide/show/minimize/maximize the console.

1. Create a new script by clicking New Script.
2. Create different script or file types by clicking the arrow icon next to the New Script button, then selecting desired type such as Blockly Script, Google Charts or HTML file.
3. All the scripts you created are listed under My Scripts. If you grouped your scripts into folders, click the arrow next to the folder name to expand its content.
4. A view that allows you to synchronize your scriptr.io resources with a remote GitHub repository. It provides you with the tools to resolve conflicts, update/commit changes from/to the repository.
5. When creating a new script, you need to give it a name. You can specify here the path (folders) to your script. For modifying the name of an existing script, click the pencil icon.
6. Edit your script code in this section.
7. Navigate through the scripts that you already opened in the IDE by clicking their respective tab.
8. You can run a script by clicking Run. If you want to pass request parameters to the script, click the drop-down arrow then click Run....
9. Open the Schedule dialog so you can schedule your scripts. You have the option to pick either a one-time schedule or a recurrent schedule.
10. Subscribe the active script to a channel so that it can read and execute business logic on all the messages published to that channel.
11. This is where you access all the tools you need to manage and configure your application.
12. Show the cheat sheet to view the list of the IDE shortcuts.
13. The Access Control List button displayed at the top right corner of the editor allows you to specify who can access the resource.
14. The Console is where the outcome of your script is displayed. It also contains the curl instruction that was used to invoke your script.
15. The Notifications is where the outcome of your GitHub commit or update is displayed.
16. Hide/show/minimize/maximize the console.

Generating Code Using Blockly

Blockly is a library for building visual programming editors. The below example illustrates a Blockly block.

Under the Scriptr menu you will find scriptr.io's specific blocks such as reading parameters, emailing and storage.

Creating Charts

The scriptr.io Chart Editor allows you to graph your data online, manage the graph and embed the visualization.

To create a new chart script, use the New Script drop-down list and select Google Chart. The editor opens in the workspace showing a customized version of the google chart editor. By default, a sample column chart is displayed on the right with pre-defined data.

The input data for the Google chart is returned by another script, called a data source script. You can select an existing script in your scriptr.io library from the drop-down list, or create a new script by clicking the New Script icon "+" next to the "select script" drop-down list. As soon as you select the data source script, the script gets executed and its result gets displayed in the chart. However, if the data returned by that script does not fit the format required by the selected chart, or the script encounters an error during its execution, an error message gets displayed.

Once the data source is selected, you can start customizing your chart on the fly. The Google chart Editor recommends charts based on the data you have selected to display, in the Recommended charts section.  

While working with a chart, there is context checking to ensure your data matches the selected chart type. If you select a chart type and afterwards select a data source with an incompatible data format, you get a message stating they do not match. All available chart types can be viewed by selecting More next to the Recommended charts section.

The tabs on the editor's right side contain additional information. The Data tab shows information about the script along with the successful execution data output. You can click Edit Script to open the script and perform updates to the data source script.

The Embed URL tab contains the information you need to serve your chart link, or embed it in your website inside an iframe. Clicking the link will serve your chart in a new browser tab. You may need to select Allow Anonymous Requests to allow the script to be run. 

From the HTML tab, you can copy the HTML source code of your chart and paste it anywhere in order to serve it. In this HTML code, you have the customization of the chart type you have selected and an AJAX call to scriptr.io to fetch your data source in order to populate your chart.

The Samples tab contains a list of data samples for testing.

Once the data source and the chart type are selected and customized, you can provide a name for your chart and save it like any other scriptr.io script. Once saved it will appear under My Scripts.

Creating Web Pages and Text Files

Our IDE simplifies the creation of multiple file types including text, HTML, JS and CSS giving you the power to visualize the data collected from your IoT devices.

In order to create files, go to New Script drop down list, then click File and select the type. The file will open with the selected type, however the extension is not added to the file name automatically upon selection; you need to add it manually e.g., homepage.html.

You can serve the created files by clicking Run. This will open a new tab that will display the file content.

Creating a Finite State Machine

To create a Finite State Machine click the New Script drop-down list then select State Machine.

From the FSM editor, you can use the controls on the left side to add states and connect them with transitions. The transitions by default return true; you can edit the script to add the conditions for the transition.

In order to view the source code of the FSM, click the Editor View icon displayed on the FSM menu on the left side of the editor.

Once you save the FSM, you can run it and view the results in the Console tab. Moreover, you can schedule the FSM to run on a specific date or recurrent. You can also subscribe it to the channels you create.

Settings

You can manage your account's settings by clicking your username (top-left corner of the workspace) then selecting Settings.

Configuration

CORS

CORS is a mechanism that allows cross-domain communication from HTTP clients by allowing resources on a web page in a given domain to be requested from another domain.

You can edit the field by clicking the pen icon, adding a comma separated list of domains and submitting.

Custom 403 Error File

When serving files, users might try to access a page to which they don't have access. Scriptr.io allows you to handle this scenario by specifying a custom 403 (HTTP Forbidden) error file, which can be either an HTML file to serve or a script that gets executed allowing you to perform some custom logic before serving the response to the user. For instance, as you can see in the sample script below, you might want to redirect the user to a different page displaying different information based on whether he does not have enough permissions to access the page, or he is not authenticated:

var htmlPage;

if (request.user.id == null) {
	// 403 because of anonymous request
	htmlPage = "./index.html";
} else {
	// 403 because of insufficient permissions
	htmlPage = "./permission_denied.html";
}

response.setStatus("403");
response.setHeader("location", htmlPage);
response.close();

Custom 404 Error File

Similar to the concept of the custom 403 error file, scriptr.io also allows you to specify a custom 404 (HTTP Not Found) error file which can either be an HTML page to serve to your users when they try to access a non-existing resource, or a script that gets executed to perform some custom logic.

Notification

Scriptr.io provides you with a mean to push notifications to any iOS and Android devices.

From the Configuration section, you can start by creating the appropriate certificates and/or FCM key and save them.

From the Groups section, you can manage groups of iOS and Android device tokens.

Configuration Sub-tab

Currently, scriptr.io provides you with three built-in configurations as listed below:

1. Development Certificate for iOS
2. Production Certificate for iOS
3. FCM API key for Android

iOS Configuration

To attach a production or development iOS certificate, under the iOS Credentials section of the Notification tab, click Add certificate link to upload the certificate and add the relevant password before clicking the Save button.

Note that in order to use your iOS certificate with scriptr.io, make sure to export it to a Personal Information Exchange format (.p12).

Android Configuration

To save an FCM key in your scriptr.io account, go to the Android Credentials section of the Notification tab, fill in the FCM API Key and click Save. You also have the option to save a notification icon path which will be used when the message pushed does not have a payload, in which case, our push API will wrap the message with the icon path inside a notification payload as the title and icon keys respectively.

Once set up, refer to the push function in the Built-in Objects & Functions section above to learn how to send push notifications from your scripts.

Note that you can remove the certificates and FCM key at anytime, however, you will no longer be able to push notifications.

Groups Sub-tab

Scriptr.io gives you the ability to send real-time messages to your mobile device applications. With our group management module, you are able to add iOS and Android device tokens to a group and push notifications in batches by sending to any group.

In order to create a group of mobile device tokens, go to Settings | Notification tab then go to the Groups sub-tab.

Once you click Add Group, a row appears where you can add a unique group ID and select a configuration ID from the drop-down list. Adding and removing mobile device tokens to groups can only be done through the addToGroup and removeFromGroup APIs.

GitHub

Under this tab you can connect a GitHub repository to your scriptr.io account in order to benefit from the features described in section GitHub Integration.

Facebook

In order to call the Facebook APIs through scriptr.io, you need to specify the API Key, API Secret and the Access Token of your Facebook app.

To manage the Facebook settings, open the Settings dialog, go to the Facebook tab, fill in the desired fields then click Save.

You can delete the settings at anytime by clicking Clear.

Twitter

In order to call the Twitter APIs through scriptr.io, you need to specify the Consumer Key, Consumer Secret, Access Token and Access Token Secret of your Twitter app.

To manage the Twitter settings, open the Settings dialog, go to the Twitter tab, fill in the desired fields then click Save.

You can delete the settings at anytime by clicking Clear.

Channels

A channel is a component over which messages are exchanged. It can serve as a topic for the publish-subscribe programming pattern or as a queue for queuing scripts to be served sequentially.

This tab allows you to:

• Manage channels and their ACLs.
• Manage bridges to connect/disconnect channels to/from external endpoints.
  
• Subscribe/unsubscribe scripts to channels.

External Endpoints

An external endpoint in scriptr.io is a configuration entry that defines how to connect to a remote resource. This includes setting the endpoint type (WebSocket, MQTT, AWS IoT, Azure IoT, etc.) in addition to the endpoint name and other endpoint-specific information such as authentication settings.

To create a new external endpoint, click on the "+" sign near "Add External Endpoint Configuration". Select an endpoint type from the first field, then specify a name, URL and port to connect to. Depending on the type you have chosen, you will need to fill different additional configuration fields, mostly related to authentication (e.g. username, password, access key, etc.).

To edit an existing external endpoint, just click on the pencil icon near the endpoint's definition. To remove an existing external endpoint, click on the trash can icon near the endpoint's definition. Note that you cannot delete external endpoints that are used by active bridges.

Device Directory

Controlling access to your scriptr.io application can be achieved by using the Device Directory which provides token and device management capabilities. To do that, click on your username (top-left corner of the workspace) then on Device Directory. A dialog opens showing two tabs - Devices and Groups - that are described below.

Devices

This tab lists all the devices available in your account, such as scriptr.io which is your first device created at registration time.

The token of the scriptr device identifies you as the owner of the application and is used by the system when running and serving scripts and files through the IDE.

The Devices tab allows you to:

• Add more devices and tokens — to control who has access to your application.
• Delete devices — to permanently prevent access to your application using their tokens.
• Edit the description of your devices.
• Assign or remove devices to/from groups.
• Suspend or activate devices — upon creation devices are active. Suspending devices will temporarily prevent access to your application using their tokens until you re-activate them.
• Regenerate devices tokens — regenerating a token will overwrite and invalidate the current one.
  

Groups

A group is a collection of devices, to whom you might want to grant the same permissions. While access to your application can be granted on a per device basis, the purpose of a group is to make management more convenient when working with a large number of devices.

The Groups tab lists all your groups and allows you to:

• Add groups — the groups that you create here will appear in the Access Control List dialog.
• Delete groups — deleting a group will not delete its devices, it will remove them from it and they will lose any permissions that were granted to the group.
• Edit groups — to update their names. Any devices that were members of the group and any permissions that were granted to it before editing will remain.
• Manage the members of groups — by assigning or removing devices. The members of a group are granted the group's permissions. When you remove a device from a group it will automatically lose any permissions that were given to that group.

Access Control List

Scriptr.io gives you full control on who can use your application by allowing you to configure an access control list for all your API endpoints.

You can open the Access Control List dialog by clicking the icon  on the top right of any of your editors. It allows you to configure which tokens can be used to run a script or serve a file depending on the type of the API endpoint.

Although you can grant permissions on a per device and per group basis, scriptr.io provides three additional predefined groups:

The Access Control List icon will change according to whether or not access is restricted:

	Access to the specified resource is restricted to a list of devices.
	Anyone can run or serve the resource.

By default, the ACLs of any new endpoints are configured to be the scriptr device, except for Google Charts and files that are granted anonymous access upon creation.

Installing Modules

The Install Modules tool allows you to extend your scriptr.io modules by adding your own. You can either pick from the wide array of modules distributed by scriptr.io or you can easily import your own from GitHub. In the list of modules provided by scriptr.io you will find:

• Connectors allowing you to integrate and orchestrate different APIs offered by a large range of IoT providers. See the full scriptr.io connector list here.
• Open source JavaScript libraries modified to work with scriptr.io.

To manage your modules, use the New Script menu, choose Install Module, and you will see the list of available modules.

To install a module from the list, simply click Install and it will be automatically installed in your scripts library under the modules folder.

To import a module that is not in the list, you can import it from GitHub by clicking Add Custom Module from GitHub, fill in the repository details along with the destination folder under which the repository scripts will be installed, and click Install. It will be imported under the destination folder that you specify.

Once installed, you will be able to locate the new modules in the My Scripts tree under the modules folder in case it is provided by scriptr.io, or the user specified folder in case it is custom. It can be used the same as other scriptr.io scripts, i.e. using the require("module_name") built-in function where module_name is the module's folder name including its path.

Terminal

The terminal is a scriptr.io debugging tool that provides a rich set of commands for invoking endpoints using different protocols and options. It can be used to invoke endpoints on different scriptr.io accounts by simply changing the token using the set command. By default, it is set to the hosting account's token.

HelloDevice -d {"myName" : "John"}

For help on using each of the above listed commands, just type "help <command>" in the terminal and it will display its description, list of supported arguments along with an example on how to use it.

To configure your terminal, create a text file on your root folder and call it Autoexec.terminal. Any commands it contains will get automatically executed upon loading the terminal. You can use this feature, for instance, to set your favorite theme, use a specific token or map command arguments.

Organizing Your Code

Scriptr.io allows you to store an arbitrary number of scripts and organize them into folders and folders hierarchy.

• When naming your script, add the path of the folders before its name and the folder hierarchy will be created if it doesn't exist (e.g., folder1/folder2/scriptname). Note that a script can be created inside a hierarchy of maximum 5 folders.
• You can put an existing script into a folder or move it from one folder to another by simply renaming it using the above notation.
• As soon as you save the script, your list of scripts (left side of the screen) gets updated with the corresponding folder structure.

Running Your Script and Viewing the Result

Once you are done implementing your code and have saved it, just click Run button on the top of the code editor to run the script. The result is displayed in the console underneath the code editor.

From the console you can see:

• The curl instruction that can be used to trigger your script from a remote HTTP client.
• The messages logged in your script.
• The response returned by your script.
• The history of all the preceding executions of this script.

Passing Request Parameters from the IDE

Another cool feature of the scriptr.io IDE is that you can dynamically pass request parameters to your script before running it.

• Click the drop-down arrow at the right of the Run button, then click Run...
• Enter the expected parameter names and values. You can add more parameters by clicking the plus icon "+"
• Once done, click Run to execute your script

Script Scheduling

The Script Scheduler enables you to automatically perform routine tasks by running a chosen script. It can be used to execute scripts at specific times or on a recurrent schedule.

To schedule a script, click Schedule and then click Add Trigger from the dialog. Once you start adding a new trigger you will get the following two options:

1. Run On: this defines a one-time schedule. A calendar opens allowing you to pick a specific date and time for this trigger.
2. Run Every: this defines a recurring schedule. You have two modes for entering the recurrent schedule information as described below:
   1. Basic: it is selected by default. In this mode you can visually select the recurrence period such as every hour, day, etc... You can choose multiple dates and times for a recurrent cron job.
   2. Advanced: you can switch to this mode by clicking the Advanced link displayed on the right side. In the advanced mode you can enter a cron expression to create a schedule which is a string made up of 5 or 6 space separated fields. The cron expression determines at what time intervals the script will run; its specs as well as some examples are described in the following sections.

When a script is scheduled, a clock icon appears next to its name in the My Scripts tab tree.

Cron Expression Specs

The cron expression fields' definitions are as follows:

The definitions of the special characters are as follows:

Cron Expression Examples

GitHub Integration

You can connect your account to GitHub to benefit from its source control capabilities and enable team collaboration on your scriptr.io account.

To configure the GitHub integration refer to the GitHub section below.

Synchronize View

You can use the Synchronize view to track the state of your shared resources in the context of a GitHub repository, and manage your changes. This view offers the following benefits:

• The modification state of the resources on scriptr.io is always up to date. In other words, any modification made to the resources from within the Workspace, will be reflected in the Synchronize view automatically.
• The states of the resources on the remote GitHub repository can be reflected in this view by clicking the Refresh button in the toolbar.

Each item in the view will have an icon explaining its state as described below:

The Synchronize view supports the following 4 modes:

Automatic Deployment

When you connect to your GitHub account from Settings | GitHub tab, you can enable automatic deployment. Once enabled, a full deployment of your entire GitHub repository will be triggered to your scriptr.io account in the following two scenarios:

1. When committing a change to GitHub while having the @AUTO-DEPLOY keyword anywhere in the the comment field.
2. When triggering a GitHub deployment event.

To disable it, go to Settings | GitHub tab and click Disable Automatic Deployment.

Compare Editor

The compare editor allows you to compare and merge differences between the resource version that you have locally on scriptr.io with the one that you have on your GitHub repository. In the Synchronize view, you can double-click a file to open it in the Compare Editor where you will see the following:

• The working copy on the left side, and the GitHub copy on the right side.
• A metadata section that contains scriptr.io specific information about the resource, such as ACLs and content type.
• Changes in the file are highlighted as follows:
  • Green highlights outgoing changes.
  • Orange highlights incoming changes.
  • Red highlights conflicting changes.

Subscribing Scripts to Channels

The publish-subscribe feature in scriptr.io allows a script to subscribe to a channel. Whenever a message gets published to this channel, the subscribed scripts will get triggered, and the message will be available in the request.rawBody property.

There are two ways of subscribing a script to a channel:

1. Through the Channel tab by clicking the script icon .
2. Through the subscription dialog by clicking Subscribe which can be accessed from the script editor. The subscription dialog will list all the available channels allowing you to switch the ON/OFF button in order to subscribe/unsubscribe your script.

Note that you can subscribe/unsubscribe scripts via the scripting pubsub module.

Custom Sub-Domain

Scriptr.io provides you with the ability to access your APIs using your own custom sub-domains (e.g., mydomain.scriptrapps.io). This will allow you to call public APIs without passing the anonymous token. For instance you can serve files such as http://mydomain.scriptrapps.io/dashboard.

To add a sub-domain:

1. Open the Account dialog then switch to the Sub-Domain tab.
2. Add your custom sub-domain then save.

To delete the sub-domain, you can clear the field then click the save icon.

Connecting to Remote Endpoints Using Bridges

A scriptr.io bridge is a connector that receives data from a remote endpoint (previously configured in the External Endpoint tab) and publishes it to a scriptr.io channel. Once published, the data can be consumed by any subscribers on that channel.

To create a bridge, all you need to do is go to the Channels tab then click on the Manage Bridges icon next to any channel as shown in the screenshot below. You will be requested to select an external endpoint from the list of configurations you provided in the External Endpoints tab and to specify the scriptr.io token that will be used to publish the received data to your channel.

Built-in Objects & Functions

Below are all the built-in objects and functions that are directly available in your scripts without having to require them.

console

The console logger is a scriptr.io built-in object used to debug your scripts allowing you to output your logs directly to the console.

The available logging functions are error(), warn(), info(), log() and debug() (note that the info and log functions have the same log level). You will also need the setLevel() function that allows you to control the minimum level that will be output to the console. By default, the level is set to DEBUG.

console.setLevel("INFO"); //levels are ERROR | WARN | INFO | DEBUG | OFF
 
console.error("This is the error message of the script");
console.warn("This is the warning message of the script");
console.info("This is the info message of the script");
console.debug("This is the debug message of the script");

isGroupInAcl

This built-in function checks if a group is granted permission by a specific ACL.

Returned result: a boolean value specifying whether or not the group is granted permission.

return isGroupInAcl("subscribers", require("pubsub").getChannel("myChannel").result.subscribeACL);

isIdInAcl

This function checks if a device or user is granted permission by a specific ACL.

Returned result: a boolean value specifying whether or not the resource is granted permission.

var pubsub = require("pubsub");
// Check if the current user has permission to publish messages to the channel called "myChannel"
if (isIdInAcl(request.user.id, pubsub.getChannel("myChannel").result.publishACL)) {
    // publish message to "myChannel"
    pubsub.publish("myChannel", "Hello Device!");
}

jsonToXml

This function converts a JSON object or string to an XML string.

Return value: an XML string.

publish

Publishes a message to a specified channel that will be sent to its subscribers.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

return publish("myChannel", "Hello Device!");

push

The built-in push function empowers your scripts to push notifications to iOS and Android devices.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

Start by setting up your account and then simply follow these examples:

var message = '{"aps": { "alert" : "The notification you want to send", "badge" : 5, "sound" : "default"}}';
var arrayDevices = ["45866802973125d73b144b6c5d9c17b24fb4b09cf4d7bff855e2dd8e852a49c6","4565656d3423e455b45355c34243f3553f3255b235352c55454dd3255e324b24"];
var deviceType = "ios";

//this is a push to iOS using the development certificate.
var isProduction = "false";
return push(arrayDevices, message, deviceType, isProduction);

//this is a push to iOS using the production certificate.
isProduction = "true";
return push(arrayDevices, message, deviceType, isProduction);

var message = '{"Content":"The notification you want to send"}';  
var arrayDevices = ["APA91bHBCTUA8vITavb-yaB2xZlB93xQB1WcquAyzYBjSAJpiEWslvjl-er-1kdvO2VVu52CpgI-ATcMrMs7rKnjInKO2di7pR9njJLJQxd4AK4vpZvGgkxQB2G5fVurKJgiwFKi7Zyyatd0lVy_8GnhieEHUMUbhagURgSTJ7l-dBES00H2eVI"];
var deviceType = "android";
return push(arrayDevices, message, deviceType);

pushToGroup

The built-in pushToGroup function allows you to push notifications directly from within a script to iOS and Android devices, by passing the following parameters:

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

request

You can use the request built-in object to retrieve the HTTP request parameters as well as other useful information. 

require

The built-in require function allows you to include a module inside your script in order to be able to use its functions and objects. Refer to the modules section for more details.

// require the "http" module
var http = require("http");
// After requiring the module "http" you can use its function "request"
var response = http.request({"url": "http://api.openweathermap.org/data/2.5/weather","params": {"q":"london,uk"}});
return response;

response

You can use the response built-in object to intercept the HTTP response stream and manipulate it before it gets sent to the client. However, make sure to set the response CORS headers whenever you call any of the response object's methods.

response.write("hello");
// whenever you manipulate the response object make sure to add your CORS settings to the header
response.addHeaders(configuration.crossDomainHeaders);
response.close();

The response object supports the following methods:

addHeaders

This method allows adding a set of headers to the response. 

close

This method flushes the data to the stream then closes it. No data can be written to the response after this operation.

flush

This method flushes the output stream and forces any buffered output bytes to be written out.

setHeader

This method allows setting the value of a specified response header. 

setStatus

This method allows setting the status code of the response. 

write

This method allows writing a string to the body of the response.

runAs

By default, everything you do within a script runs with owner privileges. However, if you wish to execute APIs using limited privileges, you can wrap your code inside a function, pass it to runAs() and specify the ID of the device that will be used to invoke that code.

Return value: null.

/* In the following example, executing this script as the scriptr device will succeed. 
 * However, if you use a different device that doesn't have the permission to save a document in the DefaultStore, 
 * the documents.create() function will fail with a PERMISSION_DENIED exception.
 */

var documents = require("document");
var stores = require("store");

// Retrieve the id of the device issuing the request
var userId = request.user.id;

// Update the ACL on the DefaultStore to allow the scriptr device to create documents
stores.update("DefaultStore", {"saveDocumentACL":"scriptr"});

// The code wrapped in the following function will be executed using the privileges of the device issuing the request (userId)
runAs(function(){

// Create a document with the privileges of the device issuing the request
 documents.create({"myfieldName":"value"});

}, userId);

schedule

The built-in function schedule allows you to schedule a script to be executed at a specific date or periodically at fixed dates or intervals. Scheduling a script creates a document in the "DefaultStore" store representing the trigger for the script.

Return value: handle to the trigger which can be used later to cancel it. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

schedule("myScript", "2016-09-08T14:28:41.093Z"); // "myScript" will run on the 8th of September 2016 at 14:28 UTC
schedule("myScript", "30 7 ? * MON-FRI"); // "myScript" will run every weekday at 7:30 AM

sendMail

The built-in sendMail function allows you to easily send emails from your scripts by directly calling it using the following parameters:

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var time = new Date();
var mailBody = "Hello,<br>An intrusion was detected at " + time + "<br>";
mailBody += "<a href='https://api.scriptrapps.io/discard?id=" + request.id + "'>Click here to discard the alert</a>";
var emailConfig = {
  "to": "joe.developer@scriptr.io",
  "fromName": "Joe",
  "subject": "Intrusion alert",
  "body": mailBody
};
return sendMail(emailConfig.to, emailConfig.fromName, emailConfig.subject, emailConfig.body);

storage

script.io provides developers with means to persist data from their scripts using the built-in storage object that exposes two levels of persistence: local and global.

Local Storage

The local storage is accessible through "storage.local". To manipulate data contained in the local store of a script use the following notations:

// we persist (create/update) the "vehicleCount" field
// in the local storage
storage.local.vehicleCount = 100;
// we read the persisted "vehicleCount" field
// from the local storage
var vehicles = storage.local.vehicleCount;
// we delete the "vehicleCount" field
// from the local storage
delete storage.local.vehicleCount;

var vehiclesPerSecond = request.parameters.vehiclesPerSecond;
var lastCount = storage.local.lastCount;
if (lastCount && lastCount < vehiclesPerSecond) {
	storage.local.lightDuration = storage.local.lightDuration - 10;
}
if (lastCount && lastCount > vehiclesPerSecond) {
	storage.local.lightDuration = storage.local.lightDuration + 10;
}
broadcast(storage.local.lightDuration);
storage.local.lastCount = vehiclesPerSecond;
return storage.local.lastCount;

function broadcast(value) {
	// broadcast this value to all traffic lights
}

Global Storage

The global storage is accessible through storage.global. To manipulate global fields within your scripts use the following notations:

// we persist (create/update) the "traffic" field
// in the global storage
storage.global.traffic = new Array();
// we read the persisted "traffic" field
// from the global storage
var traffic = storage.global.traffic;
// we delete the "traffic" field
// from the global storage
delete storage.global.traffic;

var vehiclesPerSecond = request.parameters.vehiclesPerSecond;
var lastCount = storage.local.lastCount;
if (lastCount && lastCount < countOfVehiclesPerSecond) {
  	storage.local.lightDuration = storage.local.lightDuration - 10;
}
if (lastCount && lastCount > countOfVehiclesPerSecond) {
	storage.local.lightDuration = storage.local.lightDuration + 10;
}
broadcast(storage.local.lightDuration);
storage.local.lastCount = vehiclesPerSecond;
// We need to persist the evolution of the traffic as a global field, i.e. shared by all scripts
if (!storage.global.traffic) {
  storage.global.traffic = new Array();
}
var data = {
  "time": new Date().getHours(),
  "vehicles": storage.local.lastCount
}
var traffic = [data].concat(storage.global.traffic);
storage.global.traffic = traffic;
return storage.local.lastCount;

function broadcast(value) {
	// broadcast this value to all traffic lights
}

tweet

The built-in tweet function allows you to tweet directly from within a script by passing the following parameter:

Return value: JSON object containing the result of the tweet. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

unschedule

The built-in function unschedule deletes the script's trigger corresponding to the unique handle passed as a parameter. A handle to a script's trigger is returned by the schedule function upon scheduling this script. Deleting a script's trigger removes its associated document from the "DefaultStore" store.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

unschedule("5B1EB7D483D3CEE3B443AA841607C132");

xmlToJson

This function converts an XML string to a JSON object.

Return value: JSON object.

Modules

script.io is built with modular design in mind. A module is a reusable piece of software that defines variables, functions and/or objects that you can require and use in your own scripts. While some of the modules you will be using are provided by scriptr.io or other third parties, called the core modules, you also have the possibility to create your own modules which are regular scriptr.io scripts. The difference with other scripts is that it should not be directly invoked through HTTP requests and hence, they usually expose fields, functions or classes only.

In order to add a module to your script, i.e., be able to use the functions and/or objects it defines, just use the require("module") instruction.

function HomeAutomationManager() {
  this.rooms = [
    {"master": {"temperature": 22, "light": false}}, 
    {"kids": {"temperature": 22, "light": false}}, 
    {"living": {"temperature": 22, "light": false}}
  ];
  this.doors = [{"font":false}, {"garage":false}];
}
HomeAutomationManager.prototype.getReport = function() {
  return "Rooms: " + "\n" +  JSON.stringify(this.rooms) + "\nDoors:\n" + JSON.stringify(this.doors);
}   	

var homeAutomation = require("./homeAutomation");
var homeAutomationMgr = new homeAutomation.HomeAutomationManager();
return homeAutomationMgr.getReport();

Note that most scriptr.io functions return a JSON object with the following two properties:

1. result: containing the actual return result of the function.
2. metadata: containing the status of the operation and any error details in case of failure.

{
	"result" : {
		"device" : {
			"id" : "AB825CE1520F"
		}
	},
	"metadata" : {
		"status" : "success"
	}
}

{
	"metadata" : {
		"status" : "failure",
		"statusCode" : 400,
		"errorCode" : "INVALID_PARAMETER_VALUE",
		"errorDetail" : "Invalid value for fieldName [acl]."
	}
}

channel Module

As an alternative to managing channels visually from the Workspace (under the Settings | Channels tab), scriptr.io offers the channel module which allows you to programmatically manage your channels from within your scripts. These channels are used by the pubsub and queue modules as topics and queues respectively to exchange messages or invoke scripts.

create

Creates a new channel; throws the "DUPLICATE_CHANNEL" exception if a channel with the same name already exists.

Return value: JSON object containing the channel name. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

The acls object properties are as follows:

var channels = require("channel");
var options = {
  "subscribeACL": "anonymous",
  "publishACL": "authenticated"
}
return channels.create("myChannel", options);

delete

Deletes a specified channel by name.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

get

Retrieves a specified channel by name.

Return value: JSON object containing the channel. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

{
	"result" : {
		"name" : "MyChannel",
		"subscribeACL" : "authenticated",
		"publishACL" : "authenticated",
		"creationTime" : "2015-08-17T18:17:49.530Z",
		"lastModifiedTime" : "2015-08-17T18:17:49.530Z"
	},
	"metadata" : {
		"status" : "success"
	}
}

list

Retrieves the list of all existing channels.

Return value: JSON object containing an array that contains all the existing channels along with their details. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

{
	"result" : {
		"count" : "2",
		"channels" : [{
				"name" : "channelX",
				"subscribeACL" : "anonymous",
				"publishACL" : "authenticated",
				"creationTime" : "2015-06-30T07:54:18.416Z",
				"lastModifiedTime" : "2015-06-30T07:55:30.063Z"
			}, {
				"name" : "channelY",
				"subscribeACL" : "anonymous",
				"publishACL" : "authenticated",
				"creationTime" : "2015-06-30T07:54:18.416Z",
				"lastModifiedTime" : "2015-06-30T07:55:30.063Z"
			}
		]
	},
	"metadata" : {
		"status" : "success"
	}
}

update

Updates a channel's ACLs.

Return value: JSON object containing the channel name. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

The acls object properties are as follows:

var channels = require("channel");
var options = {
  "subscribeACL": "anonymous",
  "publishACL": "authenticated"
}
 
return channels.update("myChannel", options);

device Module

The device module allows you to create and manage devices. Each device is associated to the below schema that provides the basic device fields and ACLs. You can modify the schema to meet your needs by updating the apsdb_device system schema.

<!-- 
This is the default device schema. Feel free to modify it to your liking.
This schema follows all rules and restrictions as all other schemas, as do, the documents (devices) created out of it.
However, it imposes the following restrictions of its own:
1. The seven default fields (groups, name, id,token, password, locale and isSuspended) are required.
2. This schema cannot be deleted.

Additionally, since this schema is used for device management, the following ACLs are set by default upon creation of each new device document:
- document.readACL = id, creator
- document.writeACL = id, creator
- required.readACL = nobody
- required.writeACL = nobody
- requiredVisibles.readACL = creator
- requiredVisibles.writeACL = nobody
- requiredEditables.readACL = creator
- requiredEditables.writeACL = creator

You can specify your own ACLs upon device creation by passing them as parameters to the save function of the device module as described in the documentation.
-->
<schema>
  <aclGroups>
    <aclGroup name="required">
      <read>nobody</read>
      <write>nobody</write>
      <fields>
        <field>isSuspended</field>
      </fields>
    </aclGroup>
    <aclGroup name="requiredVisibles">
      <read>creator</read>
      <write>nobody</write>
      <fields>
        <field>id</field>
        <field>groups</field>
        <field>token</field>
      </fields>
    </aclGroup>
    <aclGroup name="requiredEditables">
      <read>creator</read>
      <write>creator</write>
      <fields>
        <field>name</field>
        <field>password</field>
        <field>locale</field>
      </fields>
    </aclGroup>
    <defaultAcl>
      <read>creator</read>
      <write>creator</write>
    </defaultAcl>
    <schemaAcl>
      <read>creator</read>
      <write>creator</write>
      <delete>nobody</delete>
    </schemaAcl>
  </aclGroups>
  <fields>
    <field name="id" type="string" />
    <field name="name" type="string"/>
    <field name="groups" type="string" />
    <field name="password" type="string" />
    <field name="locale" type="string" />
    <field name="isSuspended" type="string" />
    <field name="token" type="string" />
  </fields>
</schema>

save

Saves a device with the provided fields. If the device already exists, it gets updated; otherwise, it gets created.

Return value: JSON object containing the "id" of the device that was successfully created/updated. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

The device object properties are as follows:

// We need to edit the device schema to allow adding a field called reports for saving files
var newSchemaDefinition = '<schema><aclGroups><aclGroup name="required"><read>nobody</read><write>nobody</write><fields><field>isSuspended</field></fields></aclGroup><aclGroup name="requiredVisibles"><read>creator</read><write>nobody</write><fields><field>id</field><field>groups</field><field>token</field></fields></aclGroup><aclGroup name="requiredEditables"><read>creator</read><write>creator</write><fields><field>name</field><field>password</field><field>locale</field><field>reports</field></fields></aclGroup><defaultAcl><read>creator</read><write>creator</write></defaultAcl><schemaAcl><read>creator</read><write>creator</write><delete>nobody</delete></schemaAcl></aclGroups><fields><field name="id" type="string" /><field name="name" type="string" /><field name="groups" type="string" /><field name="password" type="string" /><field name="locale" type="string" /><field name="isSuspended" type="string" /><field name="token" type="string" /><field name="reports" type="file" /></fields></schema>';

var schema = require("schema");
return schema.update("apsdb_device", newSchemaDefinition);

var devices = require("device");

var reportA = request.files["reportA"][0];
var reportB = request.files["reportB"][0];

var lastOnline = new Date();

var params = {
	"id" : "AB825CE1520F",
	"password" : "1a2afef9b19c975b429a92ec22e873c8",
	"name" : "deviceA",
	"level" : 9.8,
	"description" : "IoT door monitoring sensor.",
	"firmwareVersion" : "v1.0.972",
	"lastOnline" : lastOnline,
	"location" : "48.8580,2.2951",
	"reports" : [reportA, reportB],
	"meta.types" : {
		"description" : "text",
		"level" : "numeric",
		"lastOnline" : "date",
		"firmwareVersion" : "string",
		"location" : "geospatial"
	}
};

return devices.save(params);

{   
   "result":{   
      "device":{   
         "id":"AB825CE1520F"
      }
   },
   "metadata":{   
      "status":"success"
   }
}

create

Creates a new device; throws the "DUPLICATE_DEVICE" exception if a device with the same ID already exists, or a "DUPLICATE_USER" exception if a user with the same ID already exists. The create function takes the same parameter as the save function.

update

Updates a device; throws the "INVALID_DEVICE" exception if the device does not exist. The update function takes the same parameter as the save function.

delete

Deletes a device based on the specified ID.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

get

Retrieves a device by ID.

Return value: JSON object containing all the fields of the requested device. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

query

The query function takes the same parameter "filter" as the user module's query function.

getAttachment

Retrieves an attachment from a specific device.

Return value: JSON object containing the properties and content of the file attachment. In case of a failure the appropriate error code and details will be returned in a metadata property.

generateToken

Generates a token for the specified device. You can only generate one token per device.

The generated token does not expire, therefore, it is called eternal token.

Return value: JSON object containing the generated token. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var devices = require("device");

// Generate the eternal token for device "myDevice"
return devices.generateToken("myDevice");

{
    "result": {
        "token": "TjA2QjI2MTc0MTpnZ25EMMMyOjhDNjdENTFFRUVDOTEwBjkxMUE0NEZENDlPRkQ4Q0Iw"
    },
    "metadata": {
        "status": "success"
    }
}

regenerateToken

Regenerates a token for the specified device.

Return value: JSON object containing the newly generated token. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var devices = require("device");

// Regenerate the eternal token for device "myDevice"
return devices.regenerateToken("myDevice");

revokeToken

Deletes the token of the specified device.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var devices = require("device");

// Revoke the eternal token for device "myDevice"
return devices.revokeToken("myDevice");

document Module

In scriptr.io, data is represented as document entities where each document has a unique key and a collection of fields. Each field consists of a name, multiple values and a type.

As documents are saved in a store in scriptr.io, every instance of the document module is associated with a specific store allowing you to perform actions against that store. When you require the document module inside your script, it will always return the instance associated with the "DefaultStore"; therefore, all calls you make using that instance will be executed on the default store. If you want to manipulate documents on a different store, you can use the getInstance(storeName) method to retrieve an instance of the document module associated with a specific one, and then perform your actions using that instance.

All documents are secured individually with ACLs, allowing developers to specify the Devices and/or Groups that can view, update or delete a document, or more granularly individual fields within that document.

getInstance

Returns an instance of the document module associated with a specific store. All actions performed against this instance, such as saving or deleting documents, will be executed against its associated store.

Return value:  object representing the instance of the document module associated with the specified store.

// Get an instance of the DefaultStore using the require() function
var defaultStoreDocuments = require("document");
// Get an instance of your custom store called "myStore"
var myStoreDocuments = defaultStoreDocuments.getInstance("myStore");

// Retrieve the document "myDocument" that is saved in "myStore"
return myStoreDocuments.get("myDocument");

save

Saves a document along with its content. If the document already exists, it gets updated; otherwise, it gets created.

Return value: JSON object containing the key and the version number of the document. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

The document object properties are as follows:

var documents = require("document");

// Retrieve the country flag image file from the request
var countryFlag = request.files["flag"];

// Define the document content
var fields = {
	// set the document key
	"key": "myCountryDocumentKey",
	// add a field containing a string value called name
	"name": "USA",
	// add a field containing a numeric value called totalLandArea
	"totalLandArea": 9147593,
	// add a field containing a date value called independenceDay
	"independenceDay": "1776-07-04",
  	// add a field representing the ID of the device that gathers data related to this document
  	"deviceId": "31afe00925b6a",
  	// add a field representing the device geo-location
  	"deviceLocation": "48.8580,2.2951",
	// add a field containing an array of string value called states
	"states": [
		"New York",
		"California",
		"Chicago",
		"Utah"
	],
	// add a field containing a text value called history
	"history": "The U.S. is a country of 50 states covering a vast swath of North America, with Alaska in the extreme Northwest and Hawaii extending the nation’s presence into the Pacific Ocean. Major cities include New York, a global finance and culture center, and Washington, DC, the capital, both on the Atlantic Coast; Los Angeles, famed for filmmaking, on the Pacific Coast; and the Midwestern metropolis Chicago.",
	// add the country flag image that got retrieved from the request as an attachment to the document
	"attachments": countryFlag,
  	// enable full text-search on the history field
  	"meta.ftsFields":"history",
	// define the types of the fields added above to match their content types
	"meta.types": {
		"name": "string",
		"totalLandArea": "numeric",
		"independenceDay": "date",
		"states": "string",
      	"deviceId": "string",
      	"deviceLocation": "geospatial",
		"history": "text"
	}
};

// Persist the document myCountryDocumentKey
return documents.save(fields);

var documents = require("document");

// Define the document content to be updated
var fields = {
	// specify the document key
	"key": "myCountryDocumentKey",
	// Update the states field by appending and deleting some values
	"states": {"append":["New Mexico", "Washington"], "delete":["Utah"]},
	// delete the history field by setting it to an empty string
	"history": "",
	// add a new field to the document called connected of type string
	"connected": "true",
    // specify the type of the newly added field
    "meta.types": {
        "connected": "string"
    }
};

return documents.save(fields);

{  
    "result":{  
        "document":{  
            "key":"myCountryDocumentKey",
            "versionNumber":"1.0"
        }
    },
    "metadata":{  
        "status":"success"
    }
}

create

Creates a new document; throws the "DUPLICATE_DOCUMENT_KEY" exception if a document with the same key already exists. The create function takes the same parameter as the save function.

update

Updates a document; throws the "DOCUMENT_NOT_FOUND" exception if the document does not exist. The update function takes the same parameter as the save function.

delete

Deletes a document based on the specified key.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var documents = require("document");
 
// Delete the document with key "myCountryDocumentKey"
return documents.delete("myCountryDocumentKey");

query

Queries document data from the current store according to the conditions passed in the provided filter.

Return value: JSON object containing the array of documents matching the query filter. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

The filter object properties are as follows:

var documents = require("document");

var results;
/* Search for the documents where the states field contains "Chicago" and "California",
 * sort by creationDate (ASC) and totalLandArea (DESC),
 * return the states, totalLandArea and creationDate fields.
 */
results = documents.query({"query":'states in ["Chicago", "California"]', "sort":"creationDate<date:ASC>, totalLandArea<numeric:DESC>", "fields":"states, totalLandArea, creationDate"});

// Search for documents having the words "Washington" and "DC" in any of their full-text indexed fields
results = documents.query({"fields":"*", "ftsQuery":"Washington DC"});

{
		"result": {
			"documents": [
				{
					"key": "myCountryDocumentKey",
					"versionNumber": "1.0",
					"states": [
						"New York",
						"Chicago",
						"California",
						"New Mexico",
						"Washington"
					],
					"totalLandArea": "9147593.0",
					"creationDate": "2016-11-15T15:59:29+0000"
				}
			]
		},
		"metadata": {
			"status": "success"
		}
}

var documents = require("document");

var results;
// Get the average temperature of all sensors
results = documents.query({"query":'deviceType = "sensor"', "aggregateExpression":"avg($temperature)"}, "fields": "temperature");

// Get the average temperature grouped by device type and category number for the first page and for all pages (global)
results = documents.query({"aggregateExpression":"avg($temperature)", "aggregateGroupBy":"deviceType<String>, category<numeric>", "aggregatePage":true, "aggregateGlobal":true});

// You can similarly use other aggregates such as MIN, MAX, SUM, AVG, or COUNT, in a similar fashion. Another example:
results = documents.query({"aggregateExpression":"max($totalLandArea)", "aggregatePage":true, "aggregateGlobal":true, "fields": "totalLandArea"});

return results;

{
	"result" : {
		"aggregate" : {
			"pageScope" : {
				"value" : "9147593.0"
			},
			"globalScope" : {
				"value" : "9147593.0"
			}
		},
		"documents" : [{
				"key" : "myCountryDocumentKey",
				"versionNumber" : "1.0",
				"totalLandArea" : "9147593.0"
			}, {
				"key" : "anotherCountryDocumentKey",
				"versionNumber" : "1.0",
				"totalLandArea" : "10542.0"
			}
		]
	},
	"metadata" : {
		"status" : "success"
	}
}

var documents = require("document");

// Search for documents which devices are located within 200 meters of the reference point '48.8588, 2.2965' and return the distance between these devices and the reference point.
return documents.query({
	"query" : 'name<string>="USA" and deviceLocation<geospatial> within (48.8588, 2.2965, 0.200)',
	"includeFieldType" : "true",
	"fields" : "key, deviceLocation, distance(deviceLocation,'48.8588', '2.2965')",
	"sort" : "distance(deviceLocation,48.8588,2.2965)<ASC>"
});

{
	"result" : {
		"documents" : [{
				"key" : "myCountryDocumentKey",
				"versionNumber" : "1.0",
				"deviceLocation" : "48.858,2.2951",
				"_derivedFields" : {
					"distance(deviceLocation,'48.8588', '2.2965')" : "0.1357"
				},
				"meta.types" : {
					"deviceLocation" : "geospatial"
				}
			}
		]
	},
	"metadata" : {
		"status" : "success"
	}
}

get

Retrieves a document by key.

Return value: JSON object containing all the fields of the requested document. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var documents = require("document");
 
// Return the second version of document with key "myCountryDocumentKey"
return documents.get("myCountryDocumentKey", 2);

{  
    "result":{  
        "key":"myCountryDocumentKey",
        "versionNumber":"2.0",
        "independenceDay":"1776-07-04T00:00:00+0000",
        "attachments":"flag.gif",
        "history":"The U.S. is a country of 50 states covering a vast swath of North America, with Alaska in the extreme Northwest and Hawaii extending the nation’s presence into the Pacific Ocean. Major cities include New York, a global finance and culture center, and Washington, DC, the capital, both on the Atlantic Coast; Los Angeles, famed for filmmaking, on the Pacific Coast; and the Midwestern metropolis Chicago.",
        "states":[  
            "New York",
            "Chicago",
            "California",
            "Utah"
        ],
        "name":"USA",
        "totalLandArea":"9147593.0",
        "creator":"scriptr",
        "lastModifiedDate":"2016-08-12T14:29:29+0000",
        "lastModifiedBy":"scriptr",
        "creationDate":"2016-08-12T14:29:29+0000",
        "latest":"1.0",
        "meta.types":{  
            "independenceDay":"date",
            "attachments":"file",
            "history":"text",
            "states":"string",
            "name":"string",
            "totalLandArea":"numeric",
            "creator":"string",
            "lastModifiedDate":"date",
            "lastModifiedBy":"string",
            "creationDate":"date",
            "versionNumber":"numeric",
            "key":"string",
            "latest":"numeric"
        }
    },
    "metadata":{  
        "status":"success"
    }
}

getAttachment

Retrieves an attachment from a specific document.

Return value: JSON object containing the properties and content of the file attachment. In case of a failure the appropriate error code and details will be returned in a metadata property.

The options object properties are as follows:

var documents = require("document");

var getDocument = documents.get("myCountryDocumentKey");

if(getDocument.metadata.status == "success"){
	// Get the name of the file to be retrieved
	var filename = getDocument.result.attachments;

    // Retrieve the attachment
	var result = documents.getAttachment("myCountryDocumentKey", filename, {"fieldName": "attachments", "versionNumber": "1"});

	// As a best practice, always check the status of the previous call 
	if (result.metadata && result.metadata.status == "failure") {
		return result.metadata.errorDetail;
	} else { // write the file to the response
    	
		// you can also choose to trigger the browser's save as/download feature by uncommenting the following line:
		//response.setHeader("content-disposition", "attachment;filename=" + filename);
 
		response.setHeader("content-type","image/png");
		response.setStatus(200);

		// Add the CORS headers
		response.addHeaders(configuration.crossDomainHeaders);

		response.write(result);
	}
}

facebook Module

Scriptr.io provides the facebook module that allows you to interact with Facebook. This module's APIs will use by default the configuration that you have saved in your Settings. However, if you need to use the credentials of a different Facebook app, you can pass them as a parameter to any of the APIs as described below.

callApi

Calls any node and edge in the Facebook Graph API and returns the result in a JSON string. 

Return value: JSON object containing the response from the Facebook API call in JSON format. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

getApiCall

Calls any node and edge in the Facebook Graph API and returns a URL that will retrieve the result when called. 

Return value: JSON object containing the url/formEncodedParams that needs to be called to get the network's response for the requested API. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

getAuthorizationUrl

Requests a link to the login screen URL from Facebook. The login screen will ask the user to authorize the app to perform certain actions as specified in the scope parameter.

Return value: JSON object containing the authorization URL. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

getAccessToken

Retrieves the user access token from Facebook that will be sent with all future requests for authentication. 

Return value: JSON object containing the access token. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

group Module

Scriptr.io allows you to manage the access permissions by organizing users and devices by groups and assigning ACLs to these groups. The users and devices under a specific group will automatically be assigned the ACLs of that group.

create

Creates a new group.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

rename

Renames an existing group.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

delete

Deletes an existing group. The devices or users belonging to that group will lose the permissions that were assigned to that group.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

list

Retrieves the list of all existing groups.

Return value: JSON object containing the array of the group names. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

http Module

Scriptr.io provides the http module that allows you to easily issue any HTTP request from within a script. All you need to do is to require it and invoke its request(options) function.

request

Issues an HTTP request.

Return value: JSON object containing the HTTP request status, header, body and timeout.

The options object properties are as follows:

// require the "http" module
var http = require("http");
// build a request. You should at least provide the "url" field
var requestObject = {
	"url" : "http://api.openweathermap.org/data/2.5/weather",
	"params" : {
		"q" : "london,uk"
	},
	"method" : "GET" // optional if GET
}
// send the request by invoking the request function
// of the http module and store the returned response object
var response = http.request(requestObject);
// get the body of the response as a string
var responseBodyStr = response.body;
// check the status of the response
if (response.status == "200") {
	// manipulate the response headers
	if (response.headers["Content-Type"].indexOf("application/json") > -1) {
		return JSON.parse(responseBodyStr);
	}
	return responseBodyStr;
} else {
	return "Remote API returned an error " + response.status;
}

{
"result": {
	"status": "200",
	"headers": {
		"X-Source": "the x-source",
		"Access-Control-Allow-Origin": "the CORS configuration, if any",
		"Transfer-Encoding": "type of transfer encoding",
		"Date": "the response date",
		"Access-Control-Allow-Methods": "allowed HTTP methods",
		"Access-Control-Allow-Credentials": "true/false",
		"Connection": "keep-alive",
		"Content-Type": "the HTTP response content type and allowed charset",
		"Server": "the HTTP server"
	},
	"body": "the response body, as a string. Note that this could be a stringified JSON or could contain an error message sent by the remote service."
	"timeout": true/false
}

{
	"metadata": {
		"status": "failure",
		"errorCode": "HTTP error code",
		"errorDetail": "HTTP error details"
	}
}

log Module

To facilitate debugging remote calls from hardware, scriptr.io provides an automatic log of all requests, showing how the request got received (parameters, headers, etc.) and the returned response.

In addition, you can generate custom logs which will appear under logs, grouped by request and only logged based on a user-specified log level. Furthermore, this log view page provides the ability to download the logs, filter them by script name and scheduled scripts.

var log = require("log");
log.setLevel("DEBUG"); //levels are ERROR | WARN | INFO | DEBUG | OFF
log.error("This is the error message of the script");
log.warn("This is the warning message of the script");
log.info("This is the info message of the script");
log.debug("This is the debug message of the script");

mobile-push Module

The mobile-push module offers a mechanism for users to manage their mobile devices' tokens by organizing them into groups.

getGroup

Return value: JSON object containing the group properties. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

{
	"result" : {
		"group" : {
			"id" : "xxxxx",
			"platform" : "iOS",
			"configurationId" : "xxxxxxx",
			"pushTokens" : [
				"003DAB991FF6C1EFA5854B504D1B7AFAB8F11187BD37B9EA2D82152884B97B91",
				"933C14E952BD20F68AC2F213BDA266CC5F56F10CA795F8139D5AA3965B9AD717"
			],
			"invalidPushTokens" : [
			]
		}
	},
	"metadata" : {
		"status" : "success"
	}
}

listGroups

Retrieves the list of all existing groups. This operation takes no parameters.

Return value: JSON object containing an array that contains all the existing groups along with their details. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

{
	"result" : {
		"count" : "2",
		"groups" : [{
				"id" : "xxxxx",
				"platform" : "iOS",
				"configurationId" : "xxxxxxx",
				"pushTokens" : [
					"003DAB991FF6C1EFA5854B504D1B7AFAB8F11187BD37B9EA2D82152884B97B91",
					"933C14E952BD20F68AC2F213BDA266CC5F56F10CA795F8139D5AA3965B9AD717"
				],
				"invalidPushTokens" : [
				],
				"creationTime" : "2015-06-30T07:54:18.416Z",
				"lastModifiedTime" : "2015-06-30T07:55:30.063Z"
			}, {
				"id" : "yyyyy",
				"platform" : "iOS",
				"configurationId" : "xxxxxxx",
				"pushTokens" : [
					"003DAB991FF6C1EFA5854B504D1B7AFAB8F11187BD37B9EA2D82152884B97A91",
					"933C14E952BD20F68AC2F213BDA266CC5F56F10CA795F8139D5AA3965B9AC717"
				],
				"invalidPushTokens" : [
				],
				"creationTime" : "2015-06-30T07:54:18.416Z",
				"lastModifiedTime" : "2015-06-30T07:55:30.063Z"
			}
		]
	},
	"metadata" : {
		"status" : "success"
	}
}

deleteGroup

Deletes a specified mobile push notifications group by ID.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

addToGroup

Adds push tokens to a group.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

push

The push function empowers your scripts to push notifications to iOS and Android devices.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var mobpush = require("mobile-push");
 
var message = '{"aps": { "alert" : "The notification you want to send", "badge" : 5, "sound" : "default"}}';
var arrayDevices = ["45866802973125d73b144b6c5d9c17b24fb4b09cf4d7bff855e2dd8e852a49c6","4565656d3423e455b45355c34243f3553f3255b235352c55454dd3255e324b24"];
var deviceType = "ios";

//this is a push to iOS using the development certificate.
var isProduction = "false";
return mobpush.push(arrayDevices, message, deviceType, isProduction);

//this is a push to iOS using the production certificate.
isProduction = "true";
return mobpush.push(arrayDevices, message, deviceType, isProduction);

var mobpush = require("mobile-push");
 
var message = "The notification you want to send";  
var arrayDevices = ["APA91bHBCTUA8vITavb-yaB2xZlB93xQB1WcquAyzYBjSAJpiEWslvjl-er-1kdvO2VVu52CpgI-ATcMrMs7rKnjInKO2di7pR9njJLJQxd4AK4vpZvGgkxQB2G5fVurKJgiwFKi7Zyyatd0lVy_8GnhieEHUMUbhagURgSTJ7l-dBES00H2eVI"];
var deviceType = "android";
return mobpush.push(arrayDevices, message, deviceType, false);

pushToGroup

The pushToGroup function allows you to push notifications directly from within a script to iOS and Android devices.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

removeFromGroup

Removes push tokens from a group.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

mqtt Module

The mqtt module allows users to create an instance of an MQTT client from either:

1. A previously saved external endpoint configuration that can be called by name, or
2. Connection parameters for a new MQTT endpoint.

This instance offers users the ability to publish messages to a topic.

getInstance

Returns an instance of the mqtt module connected to the broker configured in the specified endpoint. All actions performed against this instance, such as publishing messages or closing the connection, will be executed against its associated broker.

Return value: object representing the instance of the mqtt module associated with the specified MQTT broker against which the publish and close APIs can be executed. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

getInstance

Returns an instance of the mqtt module connected to the broker specified in the parameters. All actions performed against this instance, such as publishing messages or closing the connection, will be executed against its associated broker.

Return value: object representing the instance of the mqtt module associated with the specified MQTT broker against which the publish and close APIs can be executed. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

The options object properties are as follows:

//This is an example using rootCa, key and certificate
var options = 
{
	"rootCa":request.files.rootCa[0],
	"certificate": request.files.certificate[0],
	"key": request.files.key[0],
	"password":"pass123",
	"qos":"1",
	"clientId":"someString"
};
mqtt.getInstance("<protocol>://<broker-url>:<port>", options);

//This is an example using username and password
mqtt.getInstance("<protocol>://<broker-url>:<port>", {"username": "<username-value>", "password": "<password-value>"});

publish

Publishes a message to a topic on the MQTT broker associated to the instance.This method can only be used against an instance of the mqtt module obtained using the getInstance() method.

Return value: no value is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var mqtt = require("mqtt");

var options = {};
var myMqtt = mqtt.getInstance("<protocol>://<broker-url>:<port>", options);
myMqtt.publish("topic", "Some Message");
myMqtt.close();

close

Closes the MQTT connection to the broker. This method can only be used against an instance of the mqtt module obtained using the getInstance() method. Note that the MQTT connection gets closed automatically at the end of the script execution, however, you can choose to close it at any time by calling this method.

Return value: no value is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

pubsub Module

Through its publish-subscribe model, scriptr.io provides the two-way communication that allows devices, scripts and other "things" to relay messages among each other. The pubsub module uses channels as an abstract representation of topics over which messages are exchanged. Therefore, in this section, the terms channel and topic are used interchangeably.

getInstance

Returns an instance of the pubsub module associated with the specified channel. All actions performed against this instance will be executed against its associated channel/topic.

Return value: object representing the instance of the pubsub module associated with a specific topic.

getStatistics

Retrieves statistics about a topic. This method can only be used against an instance of the pubsub module in order to be executed against the topic that this instance is bound to. If the Message Broadcasting and Queuing feature is not enabled on the account, it returns the error-code "QUEUING_DISABLED".

Return value: JSON object containing the topic statistics. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var pubsub = require("pubsub");
var topic = pubsub.getInstance("myChannel");
return topic.getStatistics();

{
	"metadata": {
		"requestId": "d9b8e304-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
		"status": "success",
		"statusCode": "200"
	},
	"result": {
		"metadata": {
			"status": "failure",
			"statusCode": 400,
			"errorCode": "QUEUING_DISABLED",
			"errorDetail": "Upgrade to a premium plan to get access to the queuing feature by contacting support."
		}
	}
}

{
	"metadata": {
		"requestId": "d04b9842-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
		"status": "success",
		"statusCode": "200"
	},
	"result": {
		"metadata": {
			"status": "success"
		},
		"result": {
			"head_message_timestamp": 1511431786,
			"size":{
				"total":134,
				"unacknowledged":3,
				"ready":131
			},
			"rates":{
				"total":5,
				"unacknowledged":0,
				"ready":5
			},
			"stats":{
				"deliverGet":{
					"count":4709,
					"rate":15.8
				},
				"ack":{
					"count":4706,
					"rate":15.8
				},
				"redeliver":{
					"count":0,
					"rate":0
				},
				"deliverNoAck":{
					"count":0,
					"rate":0
				},
				"deliver":{
					"count":4709,
					"rate":15.8
				},
				"getNoAck":{
					"count":0,
					"rate":0
				},
				"get":{
					"count":0,
					"rate":0
				},
				"publish":{
					"count":4866,
					"rate":19.8
				}
			},
			"subscriberCount":2,
			"subscribers":[
				{
					"peerHost": "x.x.x.x",
					"deviceId": "scriptr",
					"peerPort": "53944"
				},
	            {
					"peerHost": "y.y.y.y",
					"deviceId": "scriptr",
					"peerPort": "9212"
				}
			]
		}
	}
}

publish

Publishes a message to a topic. This method can only be used against an instance of the pubsub module in order to be executed against the topic that this instance is bound to.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var pubsub = require("pubsub");
var topic = pubsub.getInstance("myChannel");
return topic.publish("This is a message", false);

subscribe

Subscribes a script to a topic in order for it to read all the messages published to that topic. When a message is published to a topic, the subscribed script will get executed and will be able to access the message from the request.rawBody property. This method can only be used against an instance of the pubsub module in order to be executed against the topic that this instance is bound to.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var pubsub = require("pubsub");
var topic = pubsub.getInstance("myChannel");
return topic.subscribe("myFolder/myScript", "script");

unsubscribe

Unsubscribes a script from a topic in order to stop receiving future messages. This method can only be used against an instance of the pubsub module in order to be executed against the topic that this instance is bound to.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var pubsub = require("pubsub");
var topic = pubsub.getInstance("myChannel");
return topic.unsubscribe("myFolder/myScript", "script");

queue Module

The queue module allows you to use scriptr.io's queuing system to queue scripts to be executed in a sequential manner, monitor and control your queues. The queue module uses channels as an abstract representation of queues. Therefore, in this section, the terms channel and queue are used interchangeably.

getInstance

Retrieves an instance of the queue module associated with the specified channel. All actions performed against this instance will be executed against its associated channel/queue.

Return value: object containing a queue instance associated with a specific queue. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

clear

Clears all items in the queue. This method can only be used against an instance of the queue module in order to be executed against the queue that this instance is bound to. If Message Broadcasting and Queuing feature is not enabled on the account, the error "QUEUING_DISABLED" is returned.

Return value: JSON object containing the status of the operation, success or failure, in a metadata section. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var queue = require("queue").getInstance("myChannel");
return queue.clear();

{
	"metadata": {
		"requestId": "d9b8e304-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
		"status": "success",
		"statusCode": "200"
	},
	"result": {
		"metadata": {
			"status": "failure",
			"statusCode": 400,
			"errorCode": "QUEUING_DISABLED",
			"errorDetail": "Upgrade to a premium plan to get access to the queuing feature by contacting support."
		}
	}
}

getStatistics

Retrieves statistics about the bound queue. This method can only be used against an instance of the queue module in order to be executed against the queue that this instance is bound to. If Message Broadcasting and Queuing feature is not enabled on the account, the error "QUEUING_DISABLED" is returned.

Return value: JSON object containing the queue statistics. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var pubsub = require("pubsub");
var queue = pubsub.getInstance("testQueue");
return queue.getStatistics();

{
	"metadata": {
		"requestId": "d9b8e304-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
		"status": "success",
		"statusCode": "200"
	},
	"result": {
		"metadata": {
			"status": "failure",
			"statusCode": 400,
			"errorCode": "QUEUING_DISABLED",
			"errorDetail": "Upgrade to a premium plan to get access to the queuing feature by contacting support."
		}
	}
}

{
	"metadata": {
		"requestId": "d04b9842-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
		"status": "success",
		"statusCode": "200"
	},
	"result": {
		"metadata": {
			"status": "success"
		},
		"result": {
			"head_message_timestamp": 1511431786,
			"size":{
				"total":134,
				"unacknowledged":3,
				"ready":131
			},
			"rates":{
				"total":5,
				"unacknowledged":0,
				"ready":5
			},
			"stats":{
				"deliverGet":{
					"count":4709,
					"rate":15.8
				},
				"ack":{
					"count":4706,
					"rate":15.8
				},
				"redeliver":{
					"count":0,
					"rate":0
				},
				"deliverNoAck":{
					"count":0,
					"rate":0
				},
				"deliver":{
					"count":4709,
					"rate":15.8
				},
				"getNoAck":{
					"count":0,
					"rate":0
				},
				"get":{
					"count":0,
					"rate":0
				},
				"publish":{
					"count":4866,
					"rate":19.8
				}
			}
		}
	}
}

peek

Peeks through the queue by returning the specified number of elements from the head of the queue, without removing them. This method can only be used against an instance of the queue module in order to be executed against the queue that this instance is bound to. If Message Broadcasting and Queuing feature is not enabled on the account, the error "QUEUING_DISABLED" is returned.

Return value: JSON object containing queue elements. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var pubsub = require("pubsub");
var queue = pubsub.getInstance("testChannel");
return queue.peek({"itemCount": 3});

{
	"metadata": {
		"requestId": "d9b8e304-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
		"status": "success",
		"statusCode": "200"
	},
	"result": {
		"metadata": {
			"status": "failure",
			"statusCode": 400,
			"errorCode": "QUEUING_DISABLED",
			"errorDetail": "Upgrade to a premium plan to get access to the queuing feature by contacting support."
		}
	}
}

{
	"metadata": {
		"requestId": "96e1ce8d-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
		"status": "success",
		"statusCode": "200"
	},
	"result": {
		"metadata": {
			"status": "success"
		},
		"result": [
			{
				"payload_bytes": 34,
				"redelivered": false,
				"routing_key": "SjM2PRJCMDREMQ==.testChannel.invoke",
				"message_count": 10846,
				"properties": {
					"user_id": "SjM2PRJCMDREMTpzY3JpcHRyQG5hc3J5",
					"timestamp": 1511532551,
					"correlation_id": "b0bbb781-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
				},
				"payload": "{'method':'scriptName','params':{}}",
				"payload_encoding": "string"
			},
			{
				"payload_bytes": 34,
				"redelivered": false,
				"routing_key": "SjM2PRJCMDREMQ==.testChannel.invoke",
				"message_count": 10845,
				"properties": {
					"user_id": "SjM2PRJCMDREMTpzY3JpcHRyQG5hc3J5",
					"timestamp": 1511532551,
					"correlation_id": "b0bbb781-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
				},
				"payload": "{'method':'myScript','params':{}}",
				"payload_encoding": "string"
			},
			{
				"payload_bytes": 34,
				"redelivered": false,
				"routing_key": "SjM2PRJCMDREMQ==.testChannel.invoke",
				"message_count": 10844,
				"properties": {
					"user_id": "SjM2PRJCMDREMTpzY3JpcHRyQG5hc3J5",
					"timestamp": 1511532551,
					"correlation_id": "b0bbb781-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
				},
				"payload": "{'method':'testScript','params':{}}",
				"payload_encoding": "string"
			}
		]
	}
}

queue

Adds the specified script to the head of the queue, optionally passing the specified parameters to be available for the script during execution. This method can only be used against an instance of the queue module in order to be executed against the queue that this instance is bound to. If Message Broadcasting and Queuing feature is not enabled on the account, the error "QUEUING_DISABLED" is returned.

Return value: JSON object containing the status of the operation, success or failure, in a metadata section. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var pubsub = require("pubsub");
var queue = pubsub.getInstance("testQueue");
return queue.queue("testScript");

{
	"metadata": {
		"requestId": "d9b8e304-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
		"status": "success",
		"statusCode": "200"
	},
	"result": {
		"metadata": {
			"status": "failure",
			"statusCode": 400,
			"errorCode": "QUEUING_DISABLED",
			"errorDetail": "Upgrade to a premium plan to get access to the queuing feature by contacting support."
		}
	}
}

schema Module

Schemas are used when saving a document to define the kind of data you expect to store for a certain business entity, along with the validation and security rules. For example, you might want to have a vehicle entity in your fleet management application. You can define a schema for that entity, specifying that vehicleId, carType, registrationCertificate, lastServiceDate, fuelPercentage and currentLocation represent the data to be collected for each vehicle. For each of these vehicle attributes, you can associate validation and security rules. Hence, a schema provides a uniform way of dealing with your vehicles. Note that vehicle attributes that are not defined in the schema can still be persisted as part of the vehicle document; however, no specific validation nor security rules can be applied to them.

Scriptr.io does not enforce the use of schemas. Alternatively, you can always persist data without specifying a schema, however, no field-level security nor validation rules can be applied. This "schema-less" mode is meant for prototyping and experimenting purposes. We recommend that business applications be built in a "schema-full" mode.

Please refer to Document Schema Definitions to view the schema syntax (XSD) that you should use to create your schemas. An example of a schema is as follows:

<schema versioning="enabled">
	<aclGroups>
		<aclGroup name="admin">
			<read>userA;group:admin</read>
			<write>group:admin</write>
			<fields>
				<field>vehicleId</field>
				<field>carType</field>
				<field>registrationCertificate</field>				
				<field>lastServiceDate</field>
			</fields>
		</aclGroup>
		<aclGroup name="devices">
			<read>authenticated</read>
			<write>authenticated</write>
			<fields>
				<field>fuelPercentage</field>
				<field>currentLocation</field>
			</fields>
		</aclGroup>
		<defaultAcl>
			<read>authenticated</read>
			<write>authenticated</write>
			<delete>group:admin</delete>
		</defaultAcl>
		<schemaAcl>
			<read>nobody</read>
			<write>nobody</write>
			<delete>nobody</delete>
		</schemaAcl>
	</aclGroups>
	<fields>
		<field searchable="false" name="vehicleId" type="numeric" >
			<validation>
				<cardinality min="1" max="1" />
			</validation>
		</field>
		<field searchable="true" name="carType" type="string" >
			<validation>
				<cardinality min="1" max="1" />
			</validation>
		</field>
		<field searchable="false" name="fuelPercentage" type="numeric">
			<validation>				
				<cardinality min="1" max="1" />
				<range min="0" max="100" />
			</validation>
		</field>		
		<field name="currentLocation" type="geospatial" />
		<field searchable="true" name="registrationCertificate" type="file" />		
		<field name="lastServiceDate" type="date" />
	</fields>
</schema>

create

Creates a schema.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var schema = require("schema");
return schema.create("vehicleSchema", '<schema versioning="enabled"><aclGroups><aclGroup name="admin"><read>userA;group:admin</read><write>group:admin</write><fields><field>vehicleId</field><field>carType</field><field>registrationCertificate</field><field>lastServiceDate</field></fields></aclGroup><aclGroup name="devices"><read>authenticated</read><write>authenticated</write><fields><field>fuelPercentage</field><field>currentLocation</field></fields></aclGroup><defaultAcl><read>authenticated</read><write>authenticated</write><delete>group:admin</delete></defaultAcl><schemaAcl><read>nobody</read><write>nobody</write><delete>nobody</delete></schemaAcl></aclGroups><fields><field searchable="false" name="vehicleId" type="numeric" ><validation><cardinality min="1" max="1" /></validation></field><field searchable="true" name="carType" type="string" ><validation><cardinality min="1" max="1" /></validation></field><field searchable="false" name="fuelPercentage" type="numeric"><validation><cardinality min="1" max="1" /><range min="0" max="100" /></validation></field><field name="currentLocation" type="geospatial" /><field searchable="true" name="registrationCertificate" type="file" /><field name="lastServiceDate" type="date" /></fields></schema>');

update

Updates the content of a schema.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

delete

Deletes an existing schema.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

rename

Renames a schema. All existing documents with the old schema name will be updated to have the new schema name.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

list

Retrieves the list of all existing schemas.

Return value: JSON object containing an array of the schema names. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

{		
	"metadata": {
			"status": "success"
		},
	"result": {
		"schemas": [
			{
				"name": "vehicleSchema"
			}
		]
	}
}

get

Retrieves a specific schema by name.

Return value: JSON object containing the content of the schema. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var schema = require("schema");
return schema.get("vehicleSchema");

store Module

In scriptr.io, data and digital assets are persisted in a database container called a store. Individual data items persisted in a store are called documents.

All documents saved in a store are secured with store level ACLs, allowing developers to decide which devices, users and/or groups are permitted to save, query, delete documents or retrieve attachments from documents in that store.

The store module allows you to manage stores by offering the below functions. Note that free accounts can only have two stores.

create

Creates a new store along with its ACL. Throws the "DUPLICATE_STORE_NAME" exception if the store already exists.

Return value: A JSON object containing the store name and its properties. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

The options object properties are as follows:

The acl object properties are as follows:

For each acl property above the value could be any of the following:

• A single value of type string if the ACL consists only of one device, user or group.
• An array of strings representing all the devices, users and groups in this ACL.
• A JSON object representing which values should be appended or deleted upon update (e.g. "saveDocumentACL": {"append":["admins", "editors"], "delete":["nobody"]}). This JSON object can have the following two properties:
  
  • "append": the value of the "append" key should be a string or an array containing the values to be added to the existing ACL.
  • "delete": the value of the "delete" key should be a string or an array containing the values to be deleted from the existing ACL.

var stores = require("store");

// Create the "myStore" store with the following ACLs
stores.create("myStore", {
	"acl" : {
		"saveDocumentACL" : "deviceA",
		"deleteDocumentACL" : ["deviceA", "group:firstFloor"],
		"queryACL" : "deviceB",
		"getAttachmentACL" : "deviceB"
	},
	"isStoreSearchable" : "true"
});

update

Updates a store; throws the "STORE_NOT_FOUND" exception if the store does not exist. The update function has the same signature as the create function; however, it does not accept the option's isStoreSearchable parameter.

var stores = require("store");

// Updates the deleteDocumentACL of the store "myStore". Note that the other ACLs will remain untouched if you don't pass them during an update.
return stores.update("myStore", {
	"deleteDocumentACL" : {
		"append" : "deviceB",
		"delete" : ["deviceA", "group:firstFloor"]
	}
});

delete

Deletes a store by name. Deleting a store is a background job and might require some time, the store would be disabled meanwhile. Once done, all the data and digital assets persisted in that store will be deleted.

Return value: no specific result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var stores = require("store");
 
// Delete the store with name "myStore"
return stores.delete("myStore");

get

Retrieves a specific store by name.

Return value: JSON object containing the store name and its properties. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

{
	"metadata" : {
		"status" : "success"
	},
	"result" : {
 		"isStoreSearchable": true,
		"saveDocumentACL" : [
			"deviceA"
		],
		"store" : "myStore",
		"deleteDocumentACL" : [
			"deviceA",
			"group:firstFloor"
		],
		"getAttachmentACL" : [
			"deviceB"
		],
		"queryACL" : [
			"deviceB"
		]
	}
}

list

Retrieves all available stores.

Return value: JSON object containing the array of the store names. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

{
	"result" : {
		"stores" : [{
				"name" : "DefaultStore"
			}, {
				"name" : "myStore"
			}
		]
	},
	"metadata" : {
		"status" : "success"
	}
}

twitter Module

Scriptr.io provides the twitter module that allows you to interact with Twitter. This module's APIs will use by default the configuration that you saved in your Settings. However, if you need to use the credentials of a different Twitter app, you can pass them as a parameter to any of the APIs as described below.

tweet

Updates the user's status (i.e., tweets on behalf of the user).

Return value: JSON object containing the result of the tweet. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

// Require the twitter module in order to be able to call the APIs
var tw = require("twitter");

// In this example, we are tweeting to Twitter using the configuration saved in Settings.
tw.tweet("Hello from scriptr.io!");

// In this example, we are tweeting to Twitter using a different set of configuration than the one saved in Settings.
var credentials= {
   "consumerKey": "yourConsumerKey",
   "consumerSecret": "yourConsumerSecret",
   "accessToken": "yourAccessToken",
   "accessTokenSecret": "yourAccessTokenSecret"
 };
return tw.tweet("Hello from scriptr.io!", credentials);

getHomeTimeLine

Retrieves the most recent tweets/retweets existing on the user's timeline. It uses the default options of Twitter's home_timeline API.

Return value: JSON object containing the home timeline of the user. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

getHomeTimeLineUrl

Retrieves a URL that when called, returns the most recent tweets/retweets existing on the user's timeline.

Return value: JSON object containing the URL to call in order to obtain the home time line of the user. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

callApi

Calls any API in the Twitter REST APIs and returns the result in a JSON string.

Return value: JSON object containing the response from the Twitter API call in JSON format. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

getApiCall

Calls any API in the Twitter REST APIs and returns a URL which, when called, retrieves the result in a JSON string. 

Return value: JSON object containing the url/formEncodedParams that needs to be called to get the network's response for the requested API. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

getRequestToken

Requests a link to the login screen URL from Twitter.

Return value: JSON object containing the authorization URL and a pair of request token/secret. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

getAccessToken

Retrieves the user access token from Twitter that will be sent with all future requests for authentication purpose. 

Return value: JSON object containing a pair of access token/access token secret. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

user Module

The user module allows you to create and manage users. Each user is associated to the below schema that provides the basic user fields and ACLs. You can modify the schema to meet your needs by updating the apsdb_user system schema.

<!--
This is the default user schema. Feel free to modify it to your liking.
This schema follows all rules and restrictions as all other schemas, as do the documents (users) created out of it.
However, it imposes the following restrictions of its own:
1. The six default fields (groups, name, login, password, locale and isSuspended) are required.
2. This schema cannot be deleted.
Additionally, since this schema is used for user management, the following ACLs are set by default upon creation of each new user document:
- document.readACL = login, creator
- document.writeACL = login, creator
- required.readACL = nobody
- required.writeACL = nobody
- requiredVisibles.readACL = creator
- requiredVisibles.writeACL = nobody
- requiredEditables.readACL = creator
- requiredEditables.writeACL = creator
You can specify your own ACLs upon user creation by passing them as parameters to the save() function of the user module as described in the documentation.
-->
<schema>
  <aclGroups>
    <aclGroup name="required">
      <read>nobody</read>
      <write>nobody</write>
      <fields>
        <field>isSuspended</field>
      </fields>
    </aclGroup>
    <aclGroup name="requiredVisibles">
      <read>creator</read>
      <write>nobody</write>
      <fields>
        <field>login</field>
        <field>groups</field>
      </fields>
    </aclGroup>
    <aclGroup name="requiredEditables">
      <read>creator</read>
      <write>creator</write>
      <fields>
        <field>name</field>
        <field>password</field>
        <field>locale</field>
      </fields>
    </aclGroup>
    <defaultAcl>
      <read>creator</read>
      <write>creator</write>
    </defaultAcl>
    <schemaAcl>
      <read>creator</read>
      <write>creator</write>
      <delete>nobody</delete>
    </schemaAcl>
  </aclGroups>
  <fields>
    <field name="login" type="string"/>
    <field name="name" type="string"/>
    <field name="groups" type="string"/>
    <field name="password" type="string" />
    <field name="locale" type="string" />
    <field name="isSuspended" type="string" />
  </fields>
</schema>

save

Saves a user with the provided parameters. If the user already exists, it gets updated; otherwise, it gets created.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

The user object properties are as follows:

var users = require("user");

var params = {
	"id" : "john.doe@example.com",
	"password" : "1a2afef9b19c975b429a92ec22e873c8",
	"name" : "John Doe",
	"description" : "Security services employee",
	"lastOnline" : new Date(),
	"groups" : ["groupA", "groupB"],
	"meta.types" : {
		"description" : "text",
		"lastOnline" : "date"
	}
};

return users.save(params);

create

Creates a new user; throws the "DUPLICATE_USER" exception if a user with the same ID already exists, or a "DUPLICATE_DEVICE" exception if a device with the same ID already exists. The create function takes the same parameter as the save function.

update

Updates a user; throws the "INVALID_USER" exception if the user does not exist. The update function takes the same parameter as the save function.

delete

Deletes a user based on the specified ID.

Return value: no result is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

get

Retrieves a user by ID.

Return value: JSON object containing all the fields of the requested user. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

query

Queries user data according to the conditions passed in the provided filter.

Return value: JSON object containing array of users matching the query filter. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

The filter object properties are as follows:

var users = require("user");

// Look for users in "groupA"
return users.query({"query":'groups in ["groupA"]', "fields":"*", "sort":"name<string:ASC>, lastOnline<date:DESC>"});
// OR
return users.query({"query":'groups = "groupA"', "fields":"*", "sort":"name<string:ASC>, lastOnline<date:DESC>"});

{
	"result" : {
		"users" : [{
				"description" : "Security services employee",
				"groups" : [
					"groupA",
					"groupB"
				],
				"login" : "john.doe@example.com",
				"name" : "John Doe",
				"id" : "john.doe@example.com",
				"creator" : "scriptr@L22826DC91",
				"versionNumber" : "1.0",
				"latest" : "1.0",
				"lastModifiedBy" : "scriptr",
				"creationDate" : "2017-01-10T15:00:20+0000",
				"lastModifiedDate" : "2017-01-10T15:12:59+0000"
			}
		]
	},
	"metadata" : {
		"status" : "success"
	}
}

getAttachment

Retrieves an attachment from a specific user.

Return value: JSON object containing the properties and content of the file attachment. In case of a failure the appropriate error code and details will be returned in a metadata property.

generateToken

Generates a token for the specified user. You can generate 20 tokens per user.

The generated token expires based on the values that you set.

Return value: JSON object containing the generated token and its properties. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

The options object properties are as follows:

var users = require("user");

// Generate a token for user "myUser"
return users.generateToken("myUser", {"password": "password", "expiry": 1800, "lifeTime": 7200, "bindToReferrer": "false"});  

{
    "result": {
        "token": "TjA2QjI2MTc0MTpnZ25EMMMyOjhDNjdENTFFRUVDOTEwBjkxMUE0NEZENDlPRkQ4Q0Iw"
    },
    "metadata": {
        "status": "success"
    }
}

renewToken

Renews a token for the specified user.

Return value: JSON object containing the newly generated token and its properties. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var users = require("user");

// Renew the provided token for user "myUser"
return users.renewToken("myUser", "TjA2QjI2MTc0MTpnZ25EMMMyOjhDNjdENTFFRUVDOTEwBjkxMUE0NEZENDlPRkQ4Q0Iw");

revokeToken

Deletes the token of the specified user.

Return value: no value is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

revokeTokens

Revokes all the tokens of the specified users.

Return value: no value is returned. In case of a failure the appropriate error code and details will be returned in the metadata property (refer to common function response).

var users = require("user");

users.revokeTokens(["id1","id2"]);
return users.revokeTokens("id3");

Real-time Communication

Scriptr.io supports WebSocket connections to enable asynchronous 2-way communication allowing devices, scripts, and other "things" to communicate in a real-time fashion.

To create a WebSocket connection to scriptr.io, establish a connection to the following endpoint using any of your scriptr.io tokens including your anonymous token:
wss://api.scriptrapps.io/<YOUR TOKEN>

Executing a Script over WebSocket

You can call scriptr.io scripts through WebSocket by sending a JSON message with the following keys:

The call will return a JSON object with the following keys:

wscat -c wss://api.scriptrapps.io/<YOUR TOKEN> 
connected (press CTRL+C to quit)
< {"id":"7fea5a34","status":"success","result":"connected."}
> {"method":"MySriptName","params":{"param1":"value1","param2":["value2","value3"]}}
< { "id": "7fea5a34-be7f-ab40-08f9-713fb3a79b4e", "status": "success", "statusCode": "200", "result": "The output of your script."}

Publish-Subscribe over WebSocket

Scriptr.io offers the Publish, Subscribe and Unsubscribe APIs over WebSocket. They all return a JSON object with the following keys:

Publish

To publish a message to a specified channel that will be distributed to its subscribers, send a JSON message with the method set to "Publish" along with the following parameters:

wscat -c wss://api.scriptrapps.io/<YOUR TOKEN>
connected (press CTRL+C to quit)
< {"id":"7fea5a83","status":"success","result":"connected."}
> {"method":"Publish","params":{"channel":"myChannel","message":"Hello World!"}}
< { "id": "7fea5a83-be7f-ab40-08f9-713fb3a79b4e", "status": "success", "statusCode": "200"}

Subscribe

To subscribe the WebSocket connection to a channel in order for it to read all the messages published to that channel, send a JSON message with the method set to "Subscribe" along with the following parameter:

wscat -c wss://api.scriptrapps.io/<YOUR TOKEN>
connected (press CTRL+C to quit)
< {"id":"7fea5a82","status":"success","result":"connected."}
> {"method":"Subscribe","params":{"channel":"myChannel"}}
< { "id": "7fea5a82-be7f-ab40-08f9-713fb3a79b4e", "status": "success", "statusCode": "200"}

Unsubscribe 

To unsubscribe the WebSocket connection from a channel in order to stop receiving future messages, send a JSON message with the method set to "Unsubscribe" along with the following parameter:

wscat -c wss://api.scriptrapps.io/<YOUR TOKEN>
connected (press CTRL+C to quit)
< {"id":"7fea5a84","status":"success","result":"connected."}
> {"method":"Unsubscribe","params":{"channel":"channelName"}}
< { "id": "7fea5a84-be7f-ab40-08f9-713fb3a79b4e", "status": "success", "statusCode": "200"}

Message Queuing and Broadcasting

Scriptr.io MQTT Broker

MQTT is a light-weight messaging protocol that is widely used in the Internet of Things to broacast messages to multiple recipients. Messages are usually published to a topic and are consumed by recipients that are subscribed to the latter. The middleware service that manages topics, messages and subscriptions is called an MQTT broker. Scriptr.io supports the MQTT protocol, effortlessly turning your scriptr.io account into an MQTT broker.

To allow client applications and/or devices to send/receive messages to/from your scriptr.io account via MQTT, you need to (1) create devices in your scriptr.io account then, (2) retrieve the MQTT configuration and finally, (3) establish an MQTT connection.

1) Creating devices

If you already have created devices in your account, you can skip this step. The devices' credentials will be used by client applications or physical devices to authenticate when publishing messages towards your scripts. You can create devices using the device directory or programmatically using the device module.

2) Retrieving your MQTT configuration

Next step is to get the MQTT configuration of your account. Click on the arrow near your username in the top-right corner of the IDE and select the "Messaging Protocols" option. In the resulting configuration form, do the following:

1. Select MQTT from the Protocol drop-down.
2. Select a device from the Device drop-down in the Credentials section. A username and a password are automatically generated for that device. Your client application or physical device will use these when sending messages to your scriptr.io account.
3. Select a channel used by publishers to send messages and by subscribers to consume them. Selecting a channel displays two topics:
   1. The message topic to be used when broadcasting a message (<ANONYMOUS TOKEN>/<CHANNEL NAME>/message).
   2. The invoke topic to be used when invoking a script (<ANONYMOUS TOKEN>/<CHANNEL NAME>/invoke).

3) Establishing an MQTT connection

When establishing the MQTT connection, your client application and/or physical devices should specify the username and password of one of your devices, as obtained from the "Messaging Protocols" dialog:

// this is an example written in Node.js. Note that the below is given for illustration purposes as the logic might vary depending on the library you're using.
var client = mqtt.connect("mqtts://mqtt.scriptr.io:8883", {
	clientId : "some_client_id",
	username : "username_retrieved_from_the_messaging_protocols_dialog",
	password : "password_retrieved_from_the_messaging_protocols_dialog"
});

Invoking a Script over MQTT

When publishing messages to your scriptr.io account via MQTT, your client applications/physical devices can target a specific script that will get executed upon reception of the message, by sending a JSON message with the following keys:

When publishing the message, client applications and/or physical devices need to specify the invoke topic:

// this is an example written in Node.js. Note that the below is given for illustration purposes as the logic might vary depending on the library you're using.
var msg = {
	method : "full_script_name", // i.e  myroot/myscript
	params : {
		data : some_data
	}
};

client.publish("<ANONYMOUS TOKEN>/<CHANNEL NAME>/invoke", JSON.stringify(msg)); // e.g. client.publish("UzIyGHDem2Nl==/pubsub/invoke", JSON.stringify(msg));

Upon reception of the message, the specified scriptr.io script will get executed and can access the parameters sent in the message from the request object (e. g. request.parameters).

Publish-Subscribe over MQTT

Publishing messages to scriptr.io

When publishing messages to your scriptr.io account via MQTT, your client applications/physical devices can use the message topic to broadcast messages to subscribers.

// this is an example written in Node.js. Note that the below is given for illustration purposes as the logic might vary depending on the library you're using.
client.publish("<ANONYMOUS TOKEN>/<CHANNEL NAME>/message", "message to publish"); // e.g. client.publish("UzIyGHDem2Nl==/pubsub/message", "message to publish");

Consuming messages from scriptr.io

There are two types of message consumers: (a) client applications/ physical devices and (b) scriptr.io scripts. To receive the messages that are published to a given message topic, client applications/ physical devices need to subscribe to that same topic. As for scripts, they only need to subscribe to the associated channel.

a) Subscribing client applications/ physical devices to a topic

Client applications/ physical devices first need to establish a connection.

To consume messages, client applications/ physical devices have to subscribe to the message topic:

// this is an example written in Node.js. Note that the below is given for illustration purposes as the logic might vary depending on the library you're using.
client.subscribe("<ANONYMOUS TOKEN>/<CHANNEL NAME>/message"); 

b) Subscribing scriptr.io scripts to a channel

You need to subscribe the scripts to the channel associated with the message topic, as described in section Subscribing Scripts to Channels.

Scriptr.io AMQP Broker

AMQP is a robust messaging protocol largely used in enterprise systems and IoT applications. In the AMQP terminology, messages are sent to exchanges by producers, then routed to queues from which they are retrieved by consumers. Exchanges and queues are usually hosted by a virtual host. The middleware service that manages exchanges, queues, messages and virtual hosts is called an AMQP broker. Scriptr.io supports the AMQP protocol, turning effortlessly your scriptr.io account into an AMQP broker.

To allow client applications and/or devices to send/receive messages to/from your scriptr.io account via AMQP, you need to (1) create devices in your scriptr.io account then, (2) retrieve the AMQP configuration and finally, (3) establish an AMQP connection.

1) Creating devices

If you already have created devices in your account, you can skip this step. The devices' credentials will be used by client applications or physical devices to authenticate when publishing messages towards your scripts. You can create devices using the device directory or programmatically using the device module.

2) Retrieving your AMQP configuration

Next step is to get the AMQP configuration of your account. Click on the arrow near your username in the top-right corner of the IDE and select the "Messaging Protocols" option. In the resulting condfiguration form, do the following:

1. Select AMQP from the Protocol drop-down.
2. Select a device from the Device drop-down under the Credentials section. A username and a password are automatically generated for that device. Your client application or physical device will use these when connecting to your scriptr.io account and sending messages to it.
3. Select a channel used by producers to send messages and by consumers to consume them. Selecting a channel displays the exchange (<ANONYMOUS TOKEN>-<CHANNEL NAME>) and two routing keys:
   1. The message routing key to be used when broadcasting a message (<ANONYMOUS TOKEN>.<CHANNEL NAME>.message).
   2. The invoke routing key to be used when invoking a script (<ANONYMOUS TOKEN>.<CHANNEL NAME>.invoke).

3) Establishing an AMQP connection

When establishing the AMQP connection, your client application and/or physical devices should specify the username and  password of one of your devices and the virtual host, as obtained from the "Messaging Protocols" dialog:

// this is an example written in Node.js. Note that the below is given for illustration purposes as the logic might vary depending on the library you're using.
var connection = amqp.createConnection({ 
		host: "amqp.scriptr.io",
		vhost: "virtual_host_retrieved_from_the_messaging_protocols_dialog",
		login: "username_retrieved_from_the_messaging_protocols_dialog",
		password: "password_retrieved_from_the_messaging_protocols_dialog"
	}	
);

Invoking a Script over AMQP

When publishing messages to your scriptr.io account via AMQP, your client applications/ physical devices can target a specific script that will get executed upon reception of the message by sending a JSON message with the following keys:

When publishing the message, client applications and/or physical devices need to specify the invoke routing key:

// this is an example written in Node.js. Note that the below is given for illustration purposes as the logic might vary depending on the library you're using.
var msg = {
	method : "full_script_name", // i.e  myroot/myscript
	params : {
		data : some_data
	}
};

connection.publish("<ANONYMOUS TOKEN>.<CHANNEL NAME>.invoke", msg); // e.g. connection.publish(UzIyGHDem2Nl==.pubsub.invoke", msg)

Upon reception of the message, the specified scriptr.io script will get executed and can access the parameters sent in the message from the request object (e. g. request.parameters).

Publish-Subscribe over AMQP

Publishing messages to scriptr.io

When publishing messages to your scriptr.io account via AMQP, your client applications/physical devices can use the message routing key to broadcast messages to subscribers.

// this is an example written in Node.js. Note that the below is given for illustration purposes as the logic might vary depending on the library you're using.
connection.publish("<ANONYMOUS TOKEN>.<CHANNEL NAME>.message", msg}); // e.g. connection.publish(UzIyGHDem2Nl==.pubsub.message", msg)

Consuming messages from scriptr.io

There are two types of message consumers: (a) client applications/ physical devices and (b) scriptr.io scripts. To receive the messages that are published using a given message routing key, client applications/ physical devices need to consume using that same routing key. As for scripts, they only need to subscribe to the associated channel.

a) Subscribing client applications/ physical devices to a topic

Client applications/ physical devices first need to establish a connection.

To consume messages, client applications/ physical devices have to subscribe using the message routing key:

// this is an example written in Node.js. Note that the below is given for illustration purposes as the logic might vary depending on the library you're using.
connection.consume("<ANONYMOUS TOKEN>.<CHANNEL NAME>.message", callback_function); 

b) Subscribing scriptr.io scripts to a channel

You need to subscribe the scripts to the channel associated with the message routing key, as described in section Subscribing Scripts to Channels.

Creating RESTful APIs

Every script in scriptr.io can be used as an API that is reachable through an endpoint of the form https://api.scriptrapps.io/[scriptName]/. When calling a script, to be REST-compliant, scriptr.io allows you to pass parameters in the URI in the form https://api.scriptrapps.io/[scriptName]/[parameter], and read them from the pathInfo property of the request object (refer to the request object documentation). For instance, if you want to create a REST API for managing vehicles, you would want to create a script called vehicle and allow users to retrieve a certain vehicle by ID by issuing a GET request to the following endpoint:

https://api.scriptrapps.io/vehicle/<vehicleId>

To access the vehicleId parameter from within your script, use the pathInfo parameter of the request built-in object. Below is an example of a script that manages vehicles:

var documents = require("document");
var vehicle;

switch(request.method) {
    case "GET":
        vehicle = documents.get(request.pathInfo);
        break;
    case "PUT":
        vehicle = documents.save(JSON.parse(request.rawBody));
        break;
    case "POST":
        vehicle = documents.create(JSON.parse(request.rawBody));
        break;
    case "DELETE":
        vehicle = documents.delete(request.pathInfo);
        break;
    default:
        response.setStatus(501);	// Not Implemented
        var responseMetadata = {
            "response": {
                "metadata": {
                    "requestId": request.id,
                    "status": "failure",
                    "statusCode": "501"
                },
                "result": "HTTP method not implemented."
            }
        }
        response.write(JSON.stringify(responseMetadata));
        response.addHeaders(configuration.crossDomainHeaders);
		response.close();
		return;
}

return vehicle;

Handling Files

Sending a File to Your Scripts

Scriptr.io handles multi-part requests with binary data and thus, you can easily upload files to your scripts.

The below is the curl instruction to send to your script in order to upload a file. Notice that you need to give a name to your file field (myFile in the example).

curl -X POST -F myFile=@account.png -H 'Authorization: bearer RzM1RkYwQzc4MjpzY3JpcHRyOjQxODBFRDREQTAxQzc2REU4QjcxNTdEMjE4NUZENEUy' 'https://api.scriptrapps.io/multipart'

Retrieving a File from the Request in a Script

All files sent to a script can be retrieved from the files property of the built-in request object. Check the below code to see how easy it is to manipulate files in scriptr.io.

// Retrieve content of the "files" field from the built-in "request" object.
// The "request" object wraps the HTTP request that triggered our script and has a property called "files".
// The "files" property of the "request" object is a map where each file sent to the request is mapped to a field with the same name
var filesInRequest = request.files;
if (request.files) {
   // When we uploaded the file, we associated it to a field called "myFile"
   // this field should end up as a field of the "files" property of the "request" object
   // in the below, we check if "files" contains the "myFile" field and if the latter is not empty
   if (filesInRequest.myFile && filesInRequest.myFile.length > 0) {
     // Do something with the file
   }
}
return "no file";

Send the File to a Remote API using the http Module

In the following, we alter the preceding example by adding a call to a remote API and pass the file that was received in the request.

// Require the http module
var http = require("http");
// Retrieve content of the "files" field from the built-in "request" object
var filesInRequest = request.files;
if (filesInRequest) {
  // When we uploaded the file, we associated it to a field called "myFile"
  // this field should end up as a field of the "files" object
  // in the below, we check if "files" contains the "myFile" field and if the latter is not empty
  if (filesInRequest.myFile && filesInRequest.myFile.length > 0) {
   
    var requestObject = {
  		"url": "https://www.googleapis.com/drive/v1/files",
 		"params": {
  			"kind": "drive#file",
  			"id": "myFile",
  			"title": "someTitle"
        },
      	"files": {"myFile": filesInRequest.myFile},
  		"method": "POST"
	}
	// send the request by invoking the request function of the http module and store the returned response object
	var response = http.request(requestObject);
    return "got a file";
  }
}
return "no file";

Rate Limiting

To ensure a smooth experience and fair usage of scriptr.io's services, all incoming requests and system APIs are subject to rate limiting. There are mainly two types of rate limits, the requests rate limits and the scripting APIs rate limits as described in the following sections.

Note that rate limiting is on a per-account basis. It includes an average rate and caters for peaks.

Requests Rate Limits

Incoming requests are any calls made to your scriptr.io account.

Peak Rates

Rates are calculated over a 1 second window and are configured with a 10 requests/second limit. This limit applies to both authenticated and anonymous requests.

Average Rates

Average rate limits are calculated over a 5 minute window allowing 600 requests.

HTTP Headers and Response Codes

When an application exceeds the rate limit for a given endpoint, the request will return an HTTP 429 “Too Many Requests” response code. 

Scripting APIs Rate Limits

Scripting APIs, in this context, refers to the scriptr.io built-in APIs that you invoke within your scripts (e.g. sendMail, save device, etc.).

Peak Rates

Rates are calculated over a 1 second window and are configured with a 20 requests/second limit.

Average Rates

Average rate limits are calculated over a 5 minute window allowing 3,000 API calls.

HTTP Headers and Response Codes

When an application exceeds the rate limit for a given scripting API, the API will return a 429 “Too Many Requests” response code.