Skip to main content

How it works

Configuration​

  • FEATURE_ETHERPAD_ENABLED - Used to enable etherpad feature in feathers backend

  • FEATURE_COLUMN_BOARD_COLLABORATIVE_TEXT_EDITOR_ENABLED - Enables etherpad feature on column boards

  • ETHERPAD__COOKIE_EXPIRES_SECONDS - Time in seconds after which a session expires

  • ETHERPAD__COOKIE_RELEASE_THRESHOLD - Time in seconds after which a session is not returned to the user

  • ETHERPAD__API_KEY - Api key used for authentication of schulcloud server requests

  • ETHERPAD__URI - Uri of etherpad api for all calls like create, delete etc. Used as base path for api client in nest and feathers backend.

  • ETHERPAD__PAD_URI - URI to etherpad client api. Used in backend in collaborative text editor and lesson to build return url. Used in legacy client to build url.

  • ETHERPAD_OLD_PAD_URI - Used in feathers backend to restrict access to old etherpad urls to lesson context. Only defined in default.schema.json and not in dof-app-deploy

  • ETHERPAD__PAD_PATH - Path to etherpad client api. Used in legacy client to set path on cookie.

  • ETHERPAD__NEW_DOMAIN - Etherpad Domain. Used in legacy client to validate url

  • ETHERPAD__OLD_DOMAIN - Old Etherpad Domain. Used in legacy client to identify old urls in lessons and transform them to urls with new domain.

Creating and Opening an Etherpad Element on a Column Board​

Requests of etherpad creation

Creating an Etherpad Element​

  1. The user initiates the process by creating an Etherpad element on a column board.
  2. Vue then sends a request to the board module in the Schulcloud server for a new Etherpad element.
  3. The server responds by returning an Etherpad element which is then displayed on the board.

Interacting with the Etherpad Element​

  1. When the user clicks on the Etherpad element, the Vue client sends a request to the collaborative text editor module in the Schulcloud server for a new Etherpad.
  2. The Schulcloud server is capable of creating Etherpads based on parent types. The parent type is further used for handling authorisation of the etherpad. Currently, the only parent type is a column board element.

Grouping and Creating Etherpads​

  1. The Schulcloud server first creates a group that clusters several Etherpads together. Each group shares a session and a new group is created for every column board element. This requires sending a request to the Etherpad server.
  2. Once the group is created, the server can send a request to create an Etherpad within that group.
  1. For session creation, the server first needs to request an Etherpad author and then the session for that author.
  2. With that session, the server can set a session cookie in the client's browser and return the Etherpad URL to Vue.

Opening the Etherpad​

In the final step, Vue opens the Etherpad URL in a new browser tab, enabling the user to interact directly with the Etherpad. It's important to note that the Etherpad client interface displayed to the user is served by the Etherpad server, and as such, it is not a part of our own codebase.

Etherpad Adapter​

For the communication with the Etherpad server, the Schulcloud server uses an adapter. This adapter is responsible for handling all requests to the Etherpad server and ensuring that the correct data is sent and received. This adapter uses a client that is generated by open api generator. Client generation can be triggered with generate-client:etherpad and should be executed after update of etherpad server.

Authentication​

The authentication process in our system works via a token. This token is sent with each request as a parameter to ensure secure communication.

The token is defined by the ETHERPAD_API_KEY environment variable. This variable holds the key used for authentication, ensuring that only authorized requests are processed.

In the Schulcloud server, this API key is passed to the etherpad adapter on its initialization in the collaborative text editor module.

Session managment​

Etherpad Session Creation and Expiration​

Each interaction with an Etherpad element initiates the creation of a new session. The lifespan of this session is determined by the ETHERPAD_COOKIE__EXPIRES_SECONDS environment variable. Once this time period elapses, the user loses access to the pad. This loss of access is indicated by the display of a non-translated English message: "You do not have permission to access this pad." However, even after the session expires, users can still view the pad content as long as they do not interact with it.

Session Reuse​

Upon subsequent interactions with the Etherpad element, an existing session for that element may be reused. Whether an old session is reused or a new one is created depends on the environment variable settings. The ETHERPAD_COOKIE_RELEASE_THRESHOLD variable determines the remaining validity period of a session for it to be delivered to the user. In the current production environment, both ETHERPAD_COOKIE_RELEASE_THRESHOLD and ETHERPAD_COOKIE__EXPIRES_SECONDS are set to the same value of 2 hours. This configuration results in the creation of a new session for each interaction with an Etherpad element.

Session Renewal​

Currently there is no automatic session renewal upon interaction. Etherpad provides the COOKIE_SESSION_REFRESH_INTERVAL configuration variable, which specifies the time period after which a user's session is automatically renewed in an open tab. However, this variable is currently unset, and the default value of 1 day has no effect because it exceeds the ETHERPAD_COOKIE__EXPIRES_SECONDS value. Therefore, sessions are not automatically renewed.

Session Removal​

When a user logs out of Schulcloud, all sessions are terminated, and the user loses access to the pads upon interaction. However, Etherpad sessions are not automatically removed upon user auto-logout in Schulcloud. As long as ETHERPAD_COOKIE__EXPIRES_SECONDS and JWT_TIMEOUT_SECONDS are set to the same value, all sessions should theoretically become invalid after auto-logout.

A cookie named sessionID is stored for each session. These cookies are not programmatically removed after the ETHERPAD_COOKIE__EXPIRES_SECONDS period or upon Schulcloud logout.

Legacy Topics​

Same session behavior also applies to legacy code. Env vars are used by both implementations.

In contrast to the nest code in legacy code a session is created for every course and stored as a cookie for every etherpad.