The Command API

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

Status

Returning a command response normally logs an [OK] status.

To prevent the command from being written to the log file, for example to avoid sensitive information being written in the log, either prefix a string response with ! or set "log": false in a JSON response.

For string responses, the leading ! is removed before the response is sent to the client, so ! suppresses logging with no response text, while !page:home suppresses logging and still sends page:home.

For JSON responses, "log": false only suppresses the server log; the rest of the response is still processed normally.

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, and can also disable logging. In Javascript Events, JSON objects can be returned directly:

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

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();
}

Navigation

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 text to the clipboard, use one of the following responses:

copy:<text>

{ "copy": "<text>" }

note

Browser clipboard security rules require a user gesture before writing to the clipboard. For this reason, copy:<text> and { "copy": "<text>" } open a Copy popup in the web client instead of silently copying. The user must press Copy to complete the operation.

To copy immediately from a user click, use a Button with action clipboard-copy and set Clipboard Text; because the copy runs from the button interaction, no popup is needed.

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> } ] }

Popup

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, return the error string:

error

Or return a JSON response with error set to true:

{ "error": true }

Error with message

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

{ "error": "<message>" }

The default display mode is a tooltip.

Error with code

For one of the standard localized errors, use the JSON format:

{ "error": { "code": 500 } }

The client resolves the code using the localized error<code> text.

The standard error codes are:

Code	Message
400	Invalid request
401	Authentication required
403	Not allowed for this user
404	Resource not found
408	Request timed out
409	The data was changed by another user
422	Invalid data
429	Too many requests
500	Internal error
501	Operation not supported
503	Service temporarily unavailable

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.

Fields

Commands that send or manage field values can also target those same fields in the reply through a top-level fields property.

This applies to commands generated by:

• a form object
• a table add/edit popup
• a button with action="submit" collecting fields from its container

For generic commands triggered by objects that do not send or own fields, the fields property has no effect.

The reply can target specific fields through a top-level fields property:

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

The supported field properties mirror the editable field attributes used by forms and table edit popups. Some properties trigger a rebuild of the surrounding form or popup so the UI structure stays aligned with the new field definition.

The following properties can be changed in this way:

• type - the field type; redraws the form or popup
• visible - whether the field is visible; redraws the form or popup
• value - the field value
• enabled - whether the field is enabled
• placeholder - the placeholder text
• readonly - whether the field is read only
• items - the items of a select-like field in items mode
• list - the items of a select-like field in list mode
• prefix - the field prefix
• suffix - the field suffix
• clearbutton - whether the clear button is visible
• required - whether the field is required
• focustooltip - the tooltip shown when the field is focused
• error - set or clear the field error state (true, false, or an error message string)
• multienabled - in multi-edit mode, whether the field is enabled for editing

In practice:

• type and visible can rebuild the form or popup layout
• items and list are meaningful only for fields that support selectable values

The error property is a shortcut:

{ "fields": { "<field name>": { "error": true } } }
{ "fields": { "<field name>": { "error": false } } }
{ "fields": { "<field name>": { "error": "<message>" } } }

These forms mean:

• true: set the field in error state
• false: clear the field error state
• "<message>": set the field in error state and set the error message

The client decides how the field error message is displayed based on the field or form attributes (Error Display, Field Error Display).