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 Type | Sender | Description |
|---|---|---|
| AcknowledgementMessage | Both | Sent back to acknowledge reception of message |
| EventsMessage | Server | Contains events from the server |
| HeartbeatMessage | Both | Sent to verify if other party is still available and to report user session as active |
| SolutionSubscriptionMessage | Client | Sent to subscribe to events of specific solutions |
| SolutionUnsubscriptionMessage | Client | Sent 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 Type | Scope | Description |
|---|---|---|
| EngineEvent | Session | related to the Tryout engine in the current user session |
| InactivityUserEvent | Session | indicates that the current user session is about to expire |
| LocksExpiredEvent | Session | indicates that the locks in the current user session have expired |
| SentToBinEvent | Solution | indicates that a document was deleted and move to the bin |
| SessionReactivatedEvent | Session | indicates that the session was reactivated and is no longer about to expire |
| SolutionLogEvent | Global | indicates that changes were made to a solution |
| TaskEvent | Session | report 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.