Collaboration Kit, formerly known as “Collaboration Engine”, is a solution for building real-time collaboration features into web applications with a few lines of code. This means that users can collaboratively edit and communicate in real time, directly within secure Vaadin web applications.
Collaboration Kit requires a license file for use in production modeCollaboration Kit follows a runtime billing model, based on the number of users using collaborative features in an application. Developers can start with a free 50 user / month license, or request a commercial license with a larger quota of users. Visit the Setting up for production section to learn how to download and install a license.
Supported Use Cases
Collaboration Kit supports the following use cases:
Users see who else is looking at the same data as they are. The avatars are automatically updated when users join or leave.
Users can send messages with each other within the application, either in real time or asynchronously.
Build your own collaborative experiences by sharing data in
CollaborationList data structures.
See the Collaboration Kit Sampler for live examples with source code.
How Collaboration Kit Works
Collaboration Kit 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 standalone version that you can deploy within your infrastructure is forthcoming.
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’s unique in the context of the application, and participating members receive all updates relating to any topic that they are participating in.
Topic IDs are free-form strings that the developer may choose, such as "app" or "contract-126-address".
When building a topic for a work item, it’s 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
Collaboration Kit includes several high-level APIs that address the specific use cases of collaboratively editing a form and having real-time discussions.
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 every user who is present in a given topic, for example all the users currently looking at or editing the same form.
CollaborationMessageList is a component that displays messages submitted with a
CollaborationMessageInput component in real time.
Collaboration Managers provide a mid-level API to handle collaborative data for the most common use cases and let developers build their own collaborative logic and custom components:
PresenceManager lets you mark user presence in a Topic and subscribe to presence changes. See Presence Manager documentation for more information.
MessageManager can submit messages to a Topic and subscribe to incoming new ones. See Message Manager documentation for more information.
FormManager lets you set property values and field highlighting in a form, and to react to changes in these. See Form Manager documentation for more information.
The low-level Topic API allows synchronizing arbitrary data between users.
It’s used internally by Collaboration Managers but can also be used separately to create custom collaborative user experiences.
The entry point to using the Topic API is by opening a
A topic has multiple named maps and lists which are shared across connections. Each map contains many <String-key, value> pairs, while a list contains ordered values.
It’s strongly recommended that shared values should be immutable instances, as subscribers are notified only when the shared value is replaced with another instance, but not when the content of an existing value is updated.
For complex values in a map, a conditional replace operation is available to prevent overwriting concurrent modifications to other parts of the shared data.
Collaboration Kit is production-ready and stable, however the following features are still under development, and aren’t currently available:
Missing support for complex data structures with nested arrays and maps.
Topic data isn’t persisted between server restarts. Applications can manually persist topic data and repopulate after a restart if necessary.