Skip to main content

The Command API

The Command API enables to perform a set of actions on the HSYCO client, in response to a received command.

Status​

Any returned string causes the log of an [OK] status. If you want to prevent logging, for example to avoid sensitive information to be written in the log file, you should return the string !.

Specific response strings can be used to provide feedback to the user, or to navigate the interface.

For more advanced errors, JSON responses can be used. JSON can combine more than one action in a single response. In Javascript Events, JSON objects can be returned directly:

function userCommand(session, userid, name, param) : {
    return { "error": "An error occurred" };
}

In Java Events, JSON objects have to be converted to a string:

static String userCommand(String name, String param) {
    return "{\"error\": \"An error occurred\"}";
}

static String userCommand(String name, String param) {
    JSONObject json = new JSONObject();
    json.put("error", "An error occurred");
    return json.toString();
}

The following responses can be used to navigate the interface:

page:<page name> - navigate to the specified page
page:back - navigate back
page:forward - navigate forward
page:close - close the current popup
page:close-all - close all popups

These can also be specified in JSON format:

{ "page": "<page name>" }
{ "page": "back" }
{ "page": "forward" }
{ "page": "close" }
{ "page": "close-all" }

Pages can also be specified as an array, to perform multiple navigation actions:

{ "page": ["close-all", "popup2"] }

This will close all popups and open the page "popup2".

If a page has been opened by a command action, the userCommand function will be called again when that page is closed, with "/close" appended to the param.

To navigate to a specific URL, use the following response:

{ "url": "<url>" }
{ "url": "<url>", "target": "<target>" } - open the url in the specified browser tab, can be "_self", "_blank" or a custom name

To specify the url of another project, you can use a relative path:

{ "url": "../<project name>", "target": "<target>" }

Clipboard Copy​

To copy a text in the clipboard, use the following response:

copy:<text>

App​

When the interface is loaded inside the HSYCO App (iOS or Android), you can send a specific command to the app by returning a string that starts with “app:“ followed by the command:

app:speech - enable speech recognition
app:codescan - enable qr/bar code scanning

You can also share trigger the app's share function by returning the following string:

{ "share": "<text>" }

Download​

To initiate a file download, use the following response:

{ "download": { "name": "<command name>", "parameter": "<parameter>" } }

This will trigger a download command.

Toast​

To display a toast message, use the following response:

{ "toast": "<message>" }

Toast can also be displayed with a specific duration in milliseconds:

{ "toast": { "message": "<message>", "duration": <duration> } }

An optional type can also be specified:

{ "toast": { "message": "<message>", "type": "<info|success|warning|error>" } }

By default, displaying a toast with the same message will refresh the duration of the existing toast. To force the display of a new toast, use the following response:

{ "toast": { "message": "<message>", "duplicate": true } }

To close a toast with a specific message, use the following response:

{ "toast": { "message": "<message>", "close": true } }

To open multiple toasts, you can specify an array of toast objects:

{ "toast": [ { "message": "<message1>", "duration": <duration1> }, { "message": "<message2>", "duration": <duration2> } ] }

To display a popup message, use the following response:

{ "popup": "<message>" }

Popup can also be displayed with a specific title:

{ "popup": { "title": "<title>", "message": "<message>" } }

An optional type can also be specified:

{ "popup": { "title": "<title>", "message": "<message>", "type": "<info|success|warning|error>" } }

Error management​

A command can return an error state and optional error message and display mode.

Simple error​

For a simple error, just return the "error" string:

error

Error with message​

For an error with a message, use the JSON format:

{ "error": "<message>" }

The default display mode is a tooltip.

Error with display mode and timeout​

To display the error with a specific display mode and/or timeout, use the following format:

{ "error": { "message": "<message>", "display": "<tooltip|popup|toast>", "timeout": "<ms>" } }

The optional timeout is the time in milliseconds before the error message disappears.

Tooltip will display at the bottom of the object that triggered the command, e.g. a button or field object.

Toast will display at the top right of the screen. This can be changed in the Project's attributes.

Popup will display a modal in the center of the screen.

Rollback​

If the command is generated from an object with a value (field, slider, etc.), the value can be rolled back to the previously valid one by adding the "rollback" key to the response:

{ "error": "<message>", "rollback": true }

The valid value is the parameter of the last command generated from the object that did not return an error.

Submit​

Submit callbacks can also return error states for each field, using the following format:

{ "error": { "<field name>": "<message>", "<field name>": "<message>", ... } }

For each field, you can specify:

A generic error:

{ "error": { "<field name>": true } }

An error with a message:

{ "error": { "<field name>": "<message>" } }

Or an error message with a display mode:

{ "error": { "<field name>": { "message": "<message>", "display": "<tooltip|popup|toast>" } } }