# Epic COMMS-373 - Live-collaboration for documents

Project: Stream Communicator
Status: closed
URL: https://community.openproject.org/work_packages/COMMS-373

## Detailed specification

### Motivation and background information

**Problem**

  - I need to create, edit, organize and find documents that relate to my projects.

  - I need to have an intuitive and modern text editing experience.

  - I need to collaborate with co-workers in real-time on documents.

  - I need to find and create work packages that relate to the document I'm working on directly from the document.

  - I need to have AI tools to assist me in text editing.

**Pain**

To efficiently collaborate with colleagues in a remote environment it is often necessary to work in the same context at the same time. Without live-collaboration, only one person can edit at the same time and this forms a significant bottleneck to the flow of ideas and conversation. Without integration with project management objects via macros, it is necessary to switch context and update information manually.  
Without AI tools integration it is necessary to either forsake their use or context switch to a different tool/browser tab.

### Acceptance criteria

### Out of scope

| Attribute | Value |
| --- | --- |
| Mockups | https://www.figma.com/design/d3zhm0R0pjHJvQd3XTlxuS/New-Documents-module?node-id=1044-3801 |

## Planning

| Attribute | Value |
| --- | --- |
| Roadmap | 2026 Q1 |
| Date |  |
| Votes |  |
| List | PM² PMflex, RM Document collaboration |
| Target versions |  |
| Sprint |  |
| Backlog bucket |  |
| Relevance |  |

## Subitems

| ID | Type | Subject | Status | Assignee | Target versions | Project | Priority | Spent time |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| COMMS-390 | Feature | Index page for documents module | closed |  | 16.6.0 | Stream Communicator | Medium |  |
| COMMS-377 | Feature | Seeding Document types | closed |  | 17.0.0 | Stream Communicator | Medium |  |
| COMMS-379 | Feature | Collaborative editing | closed |  | 17.0.0 | Stream Communicator | Medium |  |
| COMMS-407 | Feature | Document show/edit view layout | closed |  | 17.0.0 | Stream Communicator | Medium |  |
| COMMS-413 | Feature | Administration of document types | closed |  | 17.0.0 | Stream Communicator | Medium |  |
| COMMS-441 | Feature | Ensure that the existing Document permissions are respected | closed |  | 17.0.0 | Stream Communicator | Medium |  |
| COMMS-497 | Feature | Add i18n for BlockNote | closed |  | 17.0.0 | Stream Communicator | Medium |  |
| COMMS-509 | Feature | List currently connected users | closed |  | 17.0.0 | Stream Communicator | Low |  |
| COMMS-477 | Feature | Presence indicator: Display connected users in a list | closed |  | Product Backlog | Stream Communicator | Medium |  |
| COMMS-384 | Open Point | Explore workflow and version requirements to decide on the starting point (wiki module vs. documents module) | decided |  |  | Stream Communicator | Medium |  |
| COMMS-412 | Open Point | How can we attribute changes to multiple users? | new |  |  | Stream Communicator | Medium |  |
| COMMS-414 | Open Point | Should OpenProject support BlockNote without a YJS provider (collaboration server) | decided | Bruno Pagno |  | Stream Communicator | Medium |  |
| COMMS-422 | Open Point | Is it worth to use BlockNote with ariakit instead of mantine? | decided |  |  | Stream Communicator | Medium |  |
| COMMS-431 | Open Point | How well does copying rich text from CKEditor5 to BlockNote editor work? | new |  |  | Stream Communicator | Medium |  |
| COMMS-442 | Open Point | RISK: Does Mantine satisfy our accessibility needs | decided |  |  | Stream Communicator | Medium |  |
| COMMS-443 | Open Point | When do we first auto-save new documents | decided | Judith Roth |  | Stream Communicator | Medium |  |
| COMMS-539 | Open Point | Should documents have an author? | decided | Kabiru Mwenja |  | Stream Communicator | Medium |  |

## Bugs and other work packages

| ID | Type | Subject | Status | Assignee | Target versions | Module |
| --- | --- | --- | --- | --- | --- | --- |
| COMMS-488 | Code maintenance | Make the YJS provider generic, instead of specific for documents | new |  | Wish List |  |
| COMMS-487 | Code maintenance | Consider using signaling instead of a full resource request when authenticating users on the Hocuspocus server | new |  | Wish List |  |
| COMMS-607 | Bug | Build op-blocknote-hocuspocus Docker images for all relevant platforms | closed |  |  |  |
| COMMS-417 | Task | Define data model for documents with and without collaboration server | closed |  |  |  |
| COMMS-383 | Task | Identify places/services that are connected to work packages | closed | Hagen Mahnke |  |  |
| BNE-4 | Task | Identify BlockNote missing features in relation to CKEditor | closed | Bruno Pagno |  |  |
| COMMS-539 | Open Point | Should documents have an author? | decided | Kabiru Mwenja |  |  |
| COMMS-443 | Open Point | When do we first auto-save new documents | decided | Judith Roth |  |  |
| COMMS-442 | Open Point | RISK: Does Mantine satisfy our accessibility needs | decided |  |  |  |
| COMMS-422 | Open Point | Is it worth to use BlockNote with ariakit instead of mantine? | decided |  |  |  |
| COMMS-414 | Open Point | Should OpenProject support BlockNote without a YJS provider (collaboration server) | decided | Bruno Pagno |  |  |
| COMMS-384 | Open Point | Explore workflow and version requirements to decide on the starting point (wiki module vs. documents module) | decided |  |  |  |
| COMMS-431 | Open Point | How well does copying rich text from CKEditor5 to BlockNote editor work? | new |  |  |  |
| COMMS-412 | Open Point | How can we attribute changes to multiple users? | new |  |  |  |

## Details

| Attribute | Value |
| --- | --- |
| Module |  |
| Enterprise plan | Community (COM) |
| Labels |  |

## People

| Attribute | Value |
| --- | --- |
| Assignee | Parimal Satyal |
| Accountable |  |
| Product manager |  |
| Designer |  |
| Developers |  |
| Requested by |  |
| Interest by |  |

## Estimates and progress

| Attribute | Value |
| --- | --- |
| Work | 120d 0h · Σ 120d 0h |

## Description

# User Problem

## User

Any user working with long-lived documents that involve multiple steps and/or users.

## 

# Business Case

## Reach

This is a prevalent problem especially in remote work contexts.

## Impact

On average a I assume a medium impact for users. I think it will have a large impact for users that need to work collaboratively in a remote context. For other users the impact will be fairly small.

## Confidence

Confidence is very high, we constantly see the need for this in our own work.

## Urgency and Priority

This has high priority as we're preparing to integrate with other applications that use BlockNote (such as Xwiki and Docs) through OpenProject specific BlockNote extensions.

## Solution

Adapt existing documents module, adapt the existing live-collaboration features from our hackathons. The editor will be replaced with BlockNote and Yjs/Hocuspocus will be used to get live-collaboration. Additionally we hope to integrate text transformation AI features in this version.

## Differentiation

Direct integration into the project management software, combined with a modern text editing experience.

# Roadmap

## Version 1

#### List of documents (Index)

  - <mention class="mention" data-id="66595" data-type="work_package" data-text="##66595">\#\#66595</mention>

  - Columns for Name, Type, and Last Edited

  - Search titles

  - Filtered views by Types in left hand menu

  - ~~Sort by table columns~~
    
      - *Leave this out of version 1, as Design team wants to do more work to design this in general so it can also be applied to workpackages for example.*

#### ~~Clean View (Distraction free)~~  *Moved out of version 1*.

  - ~~<mention class="mention" data-id="67420" data-type="work_package" data-text="##67420">##67420</mention>~~

  - ~~In this view the focus is on the text being read/edited and there are very few elements apart from that main content~~

  - ~~Sidebar collapsed so the content is completely centered horizontally~~

  - ~~Default for opening a (collaborative) document~~

  - ~~directly editable~~

  - ~~Only contains~~
    
      - ~~the main content~~
    
      - ~~the title (edit in place)~~
    
      - ~~the type~~
    
      - ~~active collaborators~~

#### Show/Edit view

  - <mention class="mention" data-id="67424" data-type="work_package" data-text="##67424">\#\#67424</mention>

  - ~~detail view can be enabled/disabled, it adds further elements to the clean view,~~ for now it will only contain
    
      - Attachments

  - Design to extend to other things we add later (Activity, Versions...)

  - Collaboration
    
      - Project permissions determine access control to document (no document-level permissions, yet)
    
      - **\[Simultaneous editing (via Hocuspocus and Yjs)\]**

#### Migration

  - <mention class="mention" data-id="67425" data-type="work_package" data-text="##67425">\#\#67425</mention>

  - Turn existing categories into types, documents into collaborative documents and keep attachments

#### ~~AI assistance - STRETCH GOAL~~  *Not for version 1*

  - <mention class="mention" data-id="66329" data-type="work_package" data-text="##66329">\#\#66329</mention>

  - ~~**\[Summarise\] - STRETCH GOAL \#**~~

#### ~~**BlockNote extension "Text to action"**~~

#### **BlockNote extension "Link existing work package"**

  - <mention class="mention" data-id="66326" data-type="work_package" data-text="##66326">\#\#66326</mention>

  - Reference and display work packages (like current macros with \#\# but now with the new / command)
    
      - ~~also transform links to work packages~~ *Out of scope for version 1*

**BlockNote extension "**~~**(Batch)**~~ **create work package** ~~**(from text)**~~**"** ***Will probably not make it into 17.0***

  - ~~Create a work package by typing /wp, then selecting the type, then entering the title and confirming with enter~~
    
      - ~~If this is done in a list/enumeration, the next item should also start in the work package creation flow~~ Batch creation needs to be implemented in later version. It will probably be independent of enumerations.

  - ~~Create a work package list by typing /wp-list (eg. like in the Paris Hackathon 'list mode')~~ There wont be a separate "reate list" mode.

  - ~~Select a list and create a work packages from each item in the list, replace item with work package reference~~ Not part of version 1

  - ~~Reference documents from work packages (eg. with the \# approach in CKEditor or the / command in BlockNote)~~ Not part of version 1

  - *~~Note: Allowing users to choose the type of work package, brings additional challenges because the type may not be valid without certain fields, the subject may be automatically generated. In addition it will not be as smooth to display the status as it is the case of task which has a boolean status (checked / unchecked)~~ Version 1 has no status attribute and also not other custom fields.*

  - *~~Note:~~* *~~Maybe the /keyword needs to be configurable? This extension could be used outside of OpenProject (OpenDesk, elsewhere) to invoke the OP-specific dropdown.~~*

#### API

  - We have an API and need to make sure we don't break it. The strategy to achieve this will depend on the migration decision
    
      - *Note: The existing API only provides GET for documents, simplifying this significantly.*

  - How can this work with YJS documents for creates and updates?
    
      - ***TASK: we need to research/prototype how we can do this.***

#### Rename Categories to Types

  - *Note: because we're not introducing Status yet, on the surface this is just a rename - even if we create a larger change and migration underneath.*

  - As long as we have not migrated the existing documents, it will be necessary to ~~use the type~~ a DB attribute to differentiate between a collaborative BlockNote document and the old CKEditor5 documents

  - ***NOTE: There is a way to configure Categories, we'll need to adapt it to Types.***

## 

## Further versions

### Collaboration

<mention class="mention" data-id="67551" data-type="work_package" data-text="###67551">\#\#\#67551</mention>

### AI assistance (WIP)

  - **\[Text to Task\]**
    
      - Mark some text and let AI create a suitable task (bug, feature) with a good description.

  - **\[Summarise\]**

  - **\[Transform text according to user instructions\]**

  - **\[Translate\]**

### Integrations

<mention class="mention" data-id="67429" data-type="work_package" data-text="###67429">\#\#\#67429</mention>

and

<mention class="mention" data-id="67526" data-type="work_package" data-text="###67526">\#\#\#67526</mention>

### Workflows (WIP)

<mention class="mention" data-id="67590" data-type="work_package" data-text="###67590">\#\#\#67590</mention>

### **File based documents (WIP)**

<br>

### **Other (WIP)**

  - **\[Outline\]**

  - Quick filters for Index

  - Notes

# Launch and Growth

## Measures

*?*

## Messaging

Edit documents collaboratively in OpenProject.

From text to action

<figure class="table op-uc-figure_align-center op-uc-figure"><table class="op-uc-table"><tbody><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Headline</p></th><td class="op-uc-table--cell"><p class="op-uc-p"><s><strong>Turn ideas into action — together.</strong></s></p><p class="op-uc-p"><strong>Great texts are written together</strong></p></td></tr><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">First Paragraph</p></th><td class="op-uc-table--cell"><p class="op-uc-p">OpenProject 17 introduces real-time collaboration for text documents.</p><p class="op-uc-p">Every great project starts with an idea — but capturing and structuring those ideas together has always been tricky. Notes get scattered, access is limited, and context is lost.</p><p class="op-uc-p">With the new Documents module, teams can now co-write, plan, and refine ideas directly in OpenProject. Reference milestones, link work packages, and move seamlessly from text draft to actionable project plan — all in one place.</p></td></tr><tr class="op-uc-table--row"><th class="op-uc-table--cell op-uc-table--cell_head"><p class="op-uc-p">Customer Quote</p></th><td class="op-uc-table--cell"><p class="op-uc-p"><br data-cke-filler="true"></p></td></tr></tbody></table></figure>

## Go to market

?

*How are you planning on getting this into users' hands?*