WebSocket User API

Overview

WebSocket User API is used to connect user applications. It requires authorization and configuring the WebSocket connection for specific APIs available to the user by rights (the opts.roles field of the user entity).

Authorizing a user-api connection

The login request within user-api can be made with the domain, user name, and password.

Authorization request with login, password, and domain:
["login", {"qid":0.19082918216295153,"login":"admin","pwd":"123","domain":"test.incoplax.com"}]
Authorization request by an active HTTP session:
[
  "login",
  {
    "qid":0.19082918216295153,
    "rsessionid":"06b64123-0176-13d6-89ab-02004c4f4f50"
  }
]

The active HTTP session identifier can be taken by the application from the REST API /rest/v1/iam/sessions/current.

Authorization request by the session obtained in the login response (the sessionid field), for example for reconnection:
[
  "login",
  {
    "qid":0.19082918216295153,
    "sessionid":"f098f576-0176-1572-b7ce-02004c4f4f50"
  }
]

rsessionid carries only the HTTP session identifier; sessionid carries the identifier returned in the login response. If the user has an active HTTP session, the password login response returns its identifier, otherwise the identifier of the new WebSocket session. If the specified session is not found or has expired and no login/password is passed, error 1407 with msg_code 10025 ("Session not found or expired.") is returned.

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

[
  "login_result",
  {
    "qid":0.19082918216295153,
    "result":"ok",
    "td":"test.incoplax.com",
    "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)"}
    ]
  }
]

After connection authorization, it is registered with the Registrar service, where it is maintained while active. Connection information is available to Registrar service clients, including via the API and from scripts (the "Operation" components, for example, where search with filtering and masking is possible). Connection identifiers can be used in the "WebSocket connection operation" script component to send events and requests to a remote application/system, and to manage file exchange.

websocktemp - directory for temporary files

Each WebSocket connection is bound to a user session. On each web server serving the WebSocket connection there is a temporary directory of this session, accessible:

  • to applications via the REST API /rest/v1/fs/targets/websocktemp within the same session;

  • to scripts via the "WebSocket connection operation" component with the "websocktemp files" category selected.

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

  • the server or web server role restarted;

  • 30 seconds after the last WebSocket connection in this session on this web server closes, if no new WebSocket connections with this session appeared by then.

States

Regardless of which APIs are connected via the setup method, the server always notifies each connection about changes in the authorized user state.

[
  "user_state_changed",
  {
    "presence": "registered",
    "state": "undefined"
  }
]
  • presence - state requested by the user. Treated by the system as a section (for example: registered, away, callcenter).

  • state - child state within a specific presence. Generated by the server based on internal servicing logic (for example: free, busy, break within callcenter).

Connection information

Request for 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","monitor","scripteditor","stat","test"],
    "timezone":"default",
    "userlogin":"admin",
    "username":"Administrator"
  }
]

Connection check (ping)

Also available before authorization.

["ping", {"qid":1}]
["ping_result", {"qid":1, "result":"ok"}]

Connection user information (info)

["info", {"qid":2}]
[
  "info_result",
  {
    "qid":2,
    "result":"ok",
    "userid":"e7adf0aa-05b7-8163-948c-3392a9660db9",
    "login":"admin",
    "domain":"test.rootdomain.ru",
    "capabilities":["rest","subscr"]
  }
]

Setting user presence (set_user_presence)

Sets the user presence state (see States). The response contains the set presence and state.

["set_user_presence", {"qid":3, "presence":"away"}]
["set_user_presence_result", {"qid":3, "result":"ok", "presence":"away", "state":"undefined"}]

Ending the session (logout)

Deletes the connection session and closes the connection.

["logout", {"qid":4}]

Available User APIs

The following capabilities can be configured and connected:

  • inited - service module connected automatically to handle setup and login requests.

  • loggedin - service module connected automatically after authorization to handle setup requests and send user_state_changed events.

  • scriptnotify - module for sending notifications from scripts.

  • scripteditor - module for serving the script editor client application.

  • rest - managing system classes (static and dynamic).

  • subscr - module for handling event subscription requests and notifications.

  • webconstr - plugin for exchanging events with web applications written with the web constructor.

  • quota - plugin for working with the access quota service.

  • dmsquery - executing an arbitrary read query.

Plugins implementing other arbitrary User APIs and corresponding capabilities are also supported.