Teneo Developers

Studio Web Sockets API

Introduction

Teneo Studio exposes a web socket API that can be used to establish a permanent two-way communication between the client and the server.

Currently, the API contains only one endpoint which can be used to subscribe to real-time events that take place on the server. It also enables clients to report the user session as idle such that the server can expire the session if the user is no longer active.

A web socket client implementation in Java is already provided in the Studio Client.

Events Web Socket Endpoint

Endpoint

The web socket endpoint can be accessed both via the ws and the secure wss protocols:

<protocol>://<studio-server>/ws/events/<auth-token>

The <auth-token> is the temporary auth token that can be obtained as described in the section-below.

Messages

The following message types can be interchanged. Their models are defined in the Studio REST API. Note that each message must have a type and an id (UUID) property.

Message TypeSenderDescription
AcknowledgementMessageBothSent back to acknowledge reception of message
EventsMessageServerContains events from the server
HeartbeatMessageBothSent to verify if other party is still available and to report user session as active
SolutionSubscriptionMessageClientSent to subscribe to events of specific solutions
SolutionUnsubscriptionMessageClientSent to unsubscribe from events of solutions

Usage

Authentication

In order to establish a web socket connection, the client must obtain a temporary token from the REST web socket endpoint while authenticating with the usual session token.

The token can then be passed in the url when establishing the connection (see endpoint). Note that the token is only valid temporarily (default: 60 seconds), it can only be used once, and it can only be used if the user session with which it was obtained is still valid. There are, however, no restrictions to the amount of web socket connections that can be established for the same user session.

Message Interaction

The reception of each message (except for the AcknowledgementMessage itself) must be acknowledged by replying with an AcknowledgementMessage that contains the same id as the message that was received. The server will stop sending new messages until it receives the acknowledgement message. The server will disconnect the web socket connection if the acknowledgement message is not received within a certain timeout (default: 30 seconds).

The acknowledgement messages sent by the server might contain additional error info (errorInfo) if a problem is encountered when processing a message that was received. Setting that property on the client side has no effect.

Events

When a web socket connection is established, the client is already subscribed to session and global events, i. e. any type of event that take place inside the user session or globally on the server. In order to receive events that happen inside a specific solution in Studio, the client must explicitly subscribe to that solution by sending a SolutionSubscriptionMessage that includes id of the solution in question. Similarly, in order to unsubscribe from solutions, the client must send a SolutionUnsubscriptionMessage.

The following events are sent by the server. Their models are defined in the Studio REST API.

Event TypeScopeDescription
EngineEventSessionrelated to the Tryout engine in the current user session
InactivityUserEventSessionindicates that the current user session is about to expire
LocksExpiredEventSessionindicates that the locks in the current user session have expired
SentToBinEventSolutionindicates that a document was deleted and move to the bin
SessionReactivatedEventSessionindicates that the session was reactivated and is no longer about to expire
SolutionLogEventGlobalindicates that changes were made to a solution
TaskEventSessionreport status updates about tasks that are running on the server

Session Inactivity

In general, a user session expires if there is no communication between the client and the server via the REST API. Communication on the web socket API does not keep the user session alive.

Furthermore, a client could report the current session as idle, meaning that even requests to the REST API will no longer keep the user session alive and the session is bound to time out after a while. This is useful if the client implements a user interface and performs periodic requests to the server, or requests triggered by incoming events, although the user is no longer active on the interface.

Once a client reports a session as idle, it must report it explicitly as active in order to stop the session from expiring.

Reporting a session as idle is done by setting the idle property as true on the AcknowledgementMessage. Reporting a session as active is done by setting the idle property as false or by sending a HeartbeatMessage to the server.

If a user session has multiple web socket connections, all connections must report the session as idle if the client wants a session to expire eventually due to user inactivity.

Connection Interruption

If the web socket connection is disconnected abnormally, the client can re-connect to the previous session in order to guarantee that no events are lost during the connection loss (as long as the user session is still valid). In order to do so, the client must again authenticate with a new temporary token, but it may pass the previous temporary token via the reconnect query parameter:

<protocol>://<studio-server>/ws/events/<auth-token>?reconnect=<previous-auth-token>

The previous-auth-token refers to the token that was used in the last successful connection attempt.