With this api endpoint you can run a command on a scene. You can run any built-in command or any command you create in your own plugin.
POST https://clara.io/api/scenes/{uuid}/command/{plugin}/{command}
options.get('data').curl -X POST "https://clara.io/api/scenes/de8891ef-6ee5-4a2c-8884-507e3648ea93/command/presets/threeLights" \
-u username:c3be3060-fe81-467b-aa62-0ee42eea9c8bPassing data to the command:
curl -X POST \
-F data='hello world' \
"https://clara.io/api/scenes/de8891ef-6ee5-4a2c-8884-507e3648ea93/command/myplugin/mycommand" \
-u username:c3be3060-fe81-467b-aa62-0ee42eea9c8bExecuting ctx commands directly. This requires plugins access be added to your account; email support@exocortex.com to request this permission.
curl -X POST \
-F data='ctx("Box#Transform[name=Transform]").set({"rotation":{"x":0,"y":1,"z":0}});' \
"https://clara.io/api/scenes/de8891ef-6ee5-4a2c-8884-507e3648ea93/command/plugins/executeJavascript" \
-u username:c3be3060-fe81-467b-aa62-0ee42eea9c8bThe return value of the command is a JSON job object upon the success or failure of the executed command, which is determent by the callback of the execute function of the command. For example, the following code is from a custom plugin of adding the material:
execute: function(ctx, options, callback) {
this.ctx = ctx;
var self = this;
var jsonString = options.get('data');
var ids = [];
if (_.isEmpty(jsonString)) {
console.error("No json data provided");
} else {
var materials = jsonString;
if(Array.isArray(materials)) {
_.each(materials, function(material) {
var id = self.setupMaterial(material);
ids.push(id);
});
} else {
var id = self.setupMaterial(materials);
ids.push(id);
}
// if an error occurs, callback will catch it and replace the first argument with error object
callback(null, ids);
}
},The callback function takes two arguments, the first one is the error object and passing it to the function will result in the failure of the command and the error object will be stored inside the error attribute of the return object. The second argument takes a variable as return value once the command runs successfully. This allows you to custom return values by passing custom value as the second argument to the function, or use try/catch block to custom error messages:
try {
if (situation1) {
throw {message: 'error1'};
} else if (situation2) {
throw {message: 'error2'}
}
} catch(e) {
callback(e);
return;
}For example, running the example plugin will have the following return value:
{
"_id": "4260f647-868f-462f-89dc-d9b43f4e3ee6",
"type": "command",
"data": {
"plugin": "CreateMaterials",
"command": "CreateMaterials",
"data": "{\"name\":\"MyMaterial\", \"baseMap\":\"MyImage.jpg\",\"baseColor\":{\"r\":.5,\"g\":.5,\"b\":.5},\"baseMapTransparent\":\"true\"}"
},
"sceneId": "683ed374-f06d-438d-8994-aa306c105229",
"name": "API command CreateMaterials",
"owner": "Hjlxc",
"status": "ok",
...
"duration": 4,
"message": null,
"result": [
"f260d80f-e698-4d32-b6cf-48ef54b9c5d0"
],
...
"log": [
{
"status": "pending",
"subStatus": "pending",
"time": "2017-04-17T20:59:38.491Z",
"_id": "58f52cba427f30616f5418de"
},
{
"status": "working",
"time": "2017-04-17T20:59:42.685Z",
"_id": "58f52cbec6afc265ee6ecbf1"
},
{
"status": "ok",
"time": "2017-04-17T20:59:43.230Z",
"_id": "58f52cbfc6afc265ee6ecbf2"
}
],
"logFiles": [],
"files": [],
"id": "4260f647-868f-462f-89dc-d9b43f4e3ee6"
}Notice the status is "ok" and the result is the created material id as we pass the id as the second argument to the callback function.
In the case of failure, for example, if we change var materials = jsonString to var materials = jsonStrings, the try block should throw an error because the jsonStrings is not defined. In this case, running the new command will result to:
{
"_id": "901634d4-08b8-4eed-95ed-51636ca9fe72",
"type": "command",
"data": {
"plugin": "CreateMaterials",
"command": "CreateMaterials",
"data": "{\"name\":\"MyMaterial\", \"baseMap\":\"MyImage.jpg\",\"baseColor\":{\"r\":.5,\"g\":.5,\"b\":.5},\"baseMapTransparent\":\"true\"}"
},
"sceneId": "683ed374-f06d-438d-8994-aa306c105229",
"name": "API command CreateMaterials",
"owner": "Hjlxc",
"status": "failed",
"duration": 0,
"error": "{\"message\":\"jsonStrings is not defined\",\"stack\":\"ReferenceError: jsonStrings is not defined\\n at registrar.defineCommand.execute (evalmachine.<anonymous>:67:27)\\n at childChange (/srv/clara/current/exo.js:13209:28)\\n at /srv/clara/current/exo.js:13542:7\\n at Function._.each._.forEach (/srv/clara/current/node_modules/underscore/underscore.js:153:9)\\n at exo.sceneGraph.Change.highbrow.extend.evaluate (/srv/clara/current/exo.js:13541:7)\\n at _.extend.exec (/srv/clara/current/exo.js:24953:43)\\n at Function.exec (/srv/clara/current/exo.js:24653:40)\\n at /srv/clara/current/lib/commands/command.js:10:20\\n at /srv/clara/current/lib/commands/utils.js:297:9\\n at Function.module.exports.connectServerSide (/srv/clara/current/lib/sse/ChangeQueue.js:21:5)\"}",
"message": null,
"log": [
{
"status": "pending",
"subStatus": "pending",
"time": "2017-04-17T20:44:49.466Z",
"_id": "58f52941eacd78567725489c"
},
{
"status": "working",
"time": "2017-04-17T20:44:49.922Z",
"_id": "58f52941c68e485c1854b344"
},
{
"status": "failed",
"time": "2017-04-17T20:44:50.292Z",
"_id": "58f52942c68e485c1854b345"
}
],
"logFiles": [],
"files": [],
"id": "901634d4-08b8-4eed-95ed-51636ca9fe72"
}This time, we get a status of "failed" with an error message "jsonStrings is not defined", just as we expected.
When using the Clara Node SDK:
$ clara scenes:command [options]