# Problem

When organisations structure work in projects they usually have files that belong to that project.

* Many of these files have a longer life cycle as work packages and are relevant to many work packages.
* Some files are relevant to the project but are not linked to any specific work package.

_**Example:** One task could be to sketch a draft and the next task could be to finalize the document. That would make two work packages for one Begin of the insertiondocument. After the document is finalized and the last work package is closed, you still want to know where the document is stored, no matter if the project simply continues or even gets archived._End of the insertion Begin of the deletion document._End of the deletion

The challenge Begin of the insertionof this EPICEnd of the insertion is to allow all project members access to that shared folder so that everybody has access to either read, write or share all files in that folder. Begin of the insertionHaving the sharing syncedEnd of the insertion Begin of the deletion ItEnd of the deletion boosts productivity and acceptance Begin of the insertioninEnd of the insertion Begin of the deletion ifEnd of the deletion the project Begin of the insertionteam. NoEnd of the insertion Begin of the deletion folder is automatically shared with any project member, so that noEnd of the deletion tedious manual sharing is necessary.

## Current work around

Currently some Begin of the insertionorganizationsEnd of the insertion Begin of the deletion organisationsEnd of the deletion use the OpenProject module _Documents_ to share files with team members. However, that module lacks usability in many ways:

* Files uploaded to that module are not synced with a Desktop, Begin of the insertionas it lacksEnd of the insertion Begin of the deletion lackingEnd of the deletion WebDAV etc.
* Begin of the insertionThis leads to the inconvenience that uploading ofEnd of the insertion Begin of the deletion UploadingEnd of the deletion files needs to be done one by Begin of the insertionone instead of complete folders.End of the insertion Begin of the deletion one.End of the deletion
* Referencing those files from within work packages Begin of the insertion(as "inputs" or "outputs" of a task)End of the insertion with normal HTML links is a tedious and error prone process. It is not Begin of the insertionefficientlyEnd of the insertion Begin of the deletion seriouslyEnd of the deletion supported.

Working with the _Documents_ module is OK, when you only want to share a couple of documents that you rarely update. Real work on those files is not practical.

## Solution

In OpenProject we allow Begin of the insertionproject admins to choose or createEnd of the insertion Begin of the deletion choosingEnd of the deletion a folder in an external file storage such as Begin of the insertion_Nextcloud_ per project.End of the insertion Begin of the deletion _Nextcloud_. Project admins will be able to setup a specific folder on the file storage system.End of the deletion The OpenProject project menu will have a menu item Begin of the insertioncalledEnd of the insertion "File storage". Clicking that menu item Begin of the insertionthe user leaves OpenProject andEnd of the insertion will directly open the shared folder in the web interface of the external file storage. Begin of the deletion The user leaves OpenProject.End of the deletion

### Without LDAP

Many Begin of the insertionsmaller organizationsEnd of the insertion Begin of the deletion organisationsEnd of the deletion do not have an LDAP server that could get used for having users and groups in both systems, OpenProject and Nextcloud in sync. In this scenario the project admins need to manually ensure that all project members (users and groups) have the correct access privileges (read, write, share) on the shared folder.

### With LDAP (advanced setup)

#### LDAP setup

Larger Begin of the insertionorganizationEnd of the insertion Begin of the deletion organisationEnd of the deletion typically have an LDAP server that can sync users and groups to both systems, OpenProject and Begin of the insertionthe external file storage, i.e.End of the insertion Nextcloud. OpenProject knows which Begin of the deletion users andEnd of the deletion groups are synced with LDAP Begin of the deletion (<mention class="mention" data-id="9177" data-type="user" data-text="@Oliver Günther">@Oliver Günther</mention> is that true?)End of the deletion and which are not. In the following Begin of the insertionwe&#39;llEnd of the insertion Begin of the deletion I willEnd of the deletion call those users and groups that are synced with LDAP &quot;_LDAP principals_&quot;. Begin of the insertion

End of the insertion Every time memberships of a OpenProject project Begin of the insertionchange a background job gets queued in OpenProject that doesEnd of the insertion Begin of the deletion change,End of the deletion the Begin of the insertionfollowing per project:

1. AddEnd of the insertion new Begin of the insertionsharings for new memberships
2. Remove sharings when memberships are removed
3. Update permissions for existing sharings

for every memberEnd of the insertion set of _LDAP principals_ Begin of the insertiongetsEnd of the insertion Begin of the deletion areEnd of the deletion transferred to the file storage instance, together with their permissions, as they are defined in through their roles in the project. Begin of the insertionWhatEnd of the insertion

#### New file sharing permissions per project

OpenProject&#39;s permissions per projects will get extended with:

* Read shared folders and files

## Write shared folders and files

* Re-share shared folders and files
* Delete shared folders

#### Managing sharings in the file storage with a central, artificial user &quot;_OpenProject user&quot;_

On the file storage&#39;s side there needs to be an artificial user that can act on behalf of OpenProject. We call that user the &quot;_OpenProject_&quot; user. The _OpenProject_ user will be the one re-sharing folders and files in the file storage with those LDAP principals as they are communicated with their privileges. To allow the _OpenProject user_ to re-share folders and files those need to be shared with the _OpenProject user_ in the first place. To achieve that, every time a project admin sets up a project folder, that folder needs to get directly shared with the _OpenProject user_.

During the setup up of the integration of OpenProject with the file storage instance the admin also has to setup the _OpenProject user_ manually and safe its identifier **(Todo: What is the identifier for sharing? A user ID? How does a admin obtain it? Or e-mail?)** in the file storage&#39;s settings in OpenProject\_.\_

#### Fixing/re-syncing sharing permissions per project

OpenProject and the file storage instance are two independent systems. Network communication between the two can fail for a multitude of reasons. Therefore it is crucial that failed request for sharing _LDAP principals_ can be triggered anew manually. Therefore a button in the project&#39;s _File storage_ settings can trigger a new sync request per storage.

## Out of scope

* Enforcing that all files linked from a work package also have to be located in the project&#39;s shared folder.

## Implementation chunks

* Folder selector in project&#39;s file storage settings
* OAuth for _OpenProject user_ with access token refreshing etc.
* Re-sync button for memberships and permissions in project settings
* Hook into membership changes in OpenProject to trigger re-syncing of memberships of _LDAP principals_ and their permissions on the shared folder.
* **... this list still needs to be completed.**