Websocket User-API

Table of Contents

Overview

Overview

Websocket User-API is used to connect user applications. Requires authorization and configuration of a websocket connection to specific APIs available to the user by rights (opts.roles field of the entity user).

Connection authorization user-api

A login request within user-api can be made with a domain, username and password.

Request authorization with login, password and domain:

["login", {"qid":0.19082918216295153,"login":"admin","pwd":"123","td":"test.era-platform.ru"}]

Request authorization by active session:

[
  "login",
  {
    "qid":0.19082918216295153,
    "rsessionid":"06b64123-0176-13d6-89ab-02004c4f4f50"
  }
]

The active session ID can be taken by the application either from the REST-API /rest/v1/iam/sessions/current, or from the RSessionId cookie in the browser, which appears after authorization in the underlying web application app-root.

If the setup method is called before authorization, all APIs return "ok" in response to it, but after authorization, the server will send a modified list of requested APIs in response to the login request (field `capabilities):

[
  "login_result",
  {
    "qid":0.19082918216295153,
    "result":"ok",
    "td":"test.era-platform.ru",
    "login":"admin",
    "register":"ok",
    "sessionid":"f098f576-0176-1572-b7ce-02004c4f4f50",
    "capabilities": [
      {"key":"scripteditor", "result":"ok"},
      {"key":"scriptnotify", "result":"ok"},
      {"key":"test", "result":"error", "errormsg":"Access denied by IAM (route not found)"}
    ]
  }
]

Once a connection is authorized, it is registered on the Registrar service, where it is maintained for as long as it is active. Information about connections is available to clients of the Registrar service, including via API and from scripts (components "Operation", e.g., where search with filtering and masking is possible). Connection IDs can be used in the websocket Connection Operation scripting component to send events and requests to the remote application/system, as well as manage file sharing.

websocktemp - temporary file directory

Each websocket connection is mapped to a user session. On each web server serving the websocket connection, there is a temporary directory of that session that can be accessed:

for applications via REST-API /rest/v1/fs/targets/websocktemp within the same session;
The "Operation with websocket connection" component with the selected "files" category is used for scripts websocktemp".

The websocktemp directory and all its contents are automatically removed from the web server in the following cases:

the server or web server role has restarted;
30 seconds after the last websocket connection within this session is closed on this web server, if there are no new websocket connections with this session by that time.

States

Regardless of which api’s are connected using the setup method, the server always notifies each connection of changes in the authorized user’s state.

[
  "user_state_changed",
  {
    "presence": "registered",
    "state": "undefined"
  }
]

presence - A state that is ordered by the user himself. Considered by the system as a partition (e.g: registered, away, callcenter).
state - a child state within a particular presence. Generated by the server based on internal service logic (for example: free, busy, break within the callcenter).

Connection information

Requesting connection information

[
  "connection_info",
  {
    "qid":930293482233
  }
]

Response

[
  "connection_info_result",
  {
    "qid":930293482233,
    "result":"ok",
    "site":"main_site",
    "ownertype":"user",
    "domain":"test.rootdomain.ru",
    "userid":"e7adf0aa-05b7-8163-948c-3392a9660db9",
    "sessionid":"0de5ea8b-017d-9458-00d5-7cd30a921f58",
    "connectionid":"aa1bd0bb-017d-9638-e89d-7cd30a921f58",
    "capabilities":["rest","scripteditor","scriptnotify","subscr"],
    "datetime":"2021-12-07T18:48:54.191Z",
    "timestamp":1638902934191,
    "webservers":["http://192.168.0.112:80"],
    "roles":["admin","crud","monitor","scripteditor","stat","test"],
    "timezone":"default",
    "userlogin":"admin",
    "username":"Administrator"
  }
]

Affordable User-API

The following can be configured and connected capabilities:

inited - a service module, plugged in automatically, to handle setup requests and login.
loggedin - service module, automatically connected after authorization, to process the setup request and send events user_state_changed.
scriptnotify - module for sending notifications from scripts.
scripteditor - module for maintaining the script editor client application.
rest - management of system classes (static and dynamic).
subscr - module for servicing event and notification subscription requests.
webconstr - A plugin for sharing events with web applications written in web builder.

Plug-ins implementing other arbitrary User-APIs and corresponding plug-ins are supported capabilities.