Collaboration Engine

Collaboration Engine is a solution for building real-time collaboration features into web apps with a few lines of code. This means that end users can collaboratively edit and communicate in real time, directly within secure Vaadin web applications.

Important
Collaboration Engine requires a license file for use in production mode
Collaboration Engine follows a runtime billing model, based on the number of end users using collaborative features in an application. Developers can start with a free 10 end user / month license, or request a commercial license with a larger quota of end users. Visit the Setting up for production section of our documentation to learn how to download and install a license.

Currently Supported Use Cases

Collaboration Engine currently supports the following use-cases:

Collaborative form editing

End users can edit forms together in real time.

Avatars

End users see who else is looking at the same data as they are. The avatars are automatically updated when users join or leave.

Low-level API

Build your own collaborative experiences by sharing data in a CollaborationMap data structure.

How Collaboration Engine works

Collaboration Engine offers an intuitive library that connects to a collaborative backend (the "engine").

This backend handles the sharing of data and user-state between application instances in real-time. It currently runs in-memory on the application server, although a hostable version that you can deploy within your infrastructure is forthcoming.

Architecture of a Vaadin application using Collaboration Engine

Central Concepts

Topics

Collaboration between users is managed by collecting data into "topic" instances that are shared between all users interacting with the same part of the application. A topic can be compared to a chat room - it has an identifier (topic id) that is unique in the context of the application and participating members will receive all updates made to any topic that they’re participating in. Topic ids are freeform strings that the developer may choose, like "app" or "contract-126-address". When building a topic for a work item, it is a good convention to have the name of the entity, and the identifier for the entity in the topic id. For example, if you are making a form for editing a Person entity, and the Person has the id 120, a good topic name would be "person/120".

Helpers for Specific Use Cases

There are two high-level APIs that enable the specific use case of editing a form together.

CollaborationBinder enhances the regular Vaadin Binder to share the current value of each field with all other users configured to use the same topic.

CollaborationAvatarGroup is a component that shows the avatar of each user who is present in a given topic, for example, all the users currently looking at or editing the same item.

Low-Level API

The low-level Topic API allows synchronizing arbitrary data between users. It is used internally by CollaborationBinder and CollaborationAvatarGroup but can also be used separately to create custom collaborative user experiences. The entry point to using the Topic API is by opening a TopicConnection through CollaborationEngine.getInstance().

A topic has multiple named maps which are shared across connections. Each map contains many <String-key, value> pairs.

It is strongly recommended that shared values are immutable instances since subscribers are notified only when the shared value is replaced with another instance but not when the contents of an existing value is updated.

For complex values, a conditional replace operation is available to prevent overwriting concurrent modifications to other parts of the shared data.

Feature Limitations

Collaboration Engine is production-ready and stable, however the following features are still under development, and are not currently available:

  • Missing support for complex data structures with nested arrays and maps.

  • Topic data is not persisted between server restarts. Applications can manually persist topic data and repopulate after a restart if necessary.

  • Collaboration between multiple nodes or pods in a cluster of application servers is not supported. A future version will enable running Collaboration Engine as a standalone server or a cloud deployment that can be used from multiple application servers.

  • Collaboration Engine can be used only in Vaadin views implemented with Flow. Support for Fusion will be added later.