### Use cases:

* Begin of the deletion List files that belong to a work package in a separate "Files" tab.
* The tab lists all conventional work package attachments in one section, and
* in another section it lists all links to related files that reside within an external _file storage_. We call these links _file links._ In the first implementation a _file storage_ is a specific Nextcloud instance.
* The tab shows a number indicating the amount of files (attachments + file links) in the tab handle, similar to the "Watchers" tab.
* On each listed _file link_
* A click on the file name opens the file (opens file in Nextcloud file editor/viewer)
* A _download_ button will start downloading file to hard drive (can be deactivated per storage in admin settings)
* A _folder_ button will open the file in its location (opens the directory in Nextcloud where the file is located)
* Delete file link (removes the link but does not delete the file)
* Show meta information per file
* File type _(PDF, JPG,_ etc.)
* File size (_2.8 MB_)
* Last modified time stamp
* Last modified by (name) if available through Nextcloud API
* Created by (name) if available through Nextcloud API
* Owner (name) if available through Nextcloud API
* Path if feasible (a shared file can have multiple paths)
* End of the deletion Create a link between a work package and an existing file in Nextcloud.
* Clicking a button in the "Files" tab will show a file picker with the Nextcloud file structure for that user (Keep in mind that every Nextcloud user has a different file structure)
* To achieve this, the current OpenProject user will need to request authorization from Nextcloud via OAuth, so that OpenProject consequently can make personalized API requests to Nextcloud.
* Upload a file from within a work package in OpenProject
* Chose a location in Nextcloud via a _location picker_
* Save the file in Nextcloud
* Create a _file link_ between the work Begin of the insertionpackageEnd of the insertion Begin of the deletion package End of the deletion
* **Out of scope:** Upload of entire directories, as normal Form uploads do not allow this. So only the upload of individual files will be supported in the first version.
* Delete _file links_ from a work package (without deleting it in Nextcloud).

### Implementation Begin of the insertionchunks:End of the insertion Begin of the deletion blocks:End of the deletion

* Begin of the deletion Files tab in for work packages.
* OAuth reverse direction (authorize OpenProject users in Nextcloud) with refreshing mechanism.
* End of the deletion File picker for selecting link targets (files and directories). Queries Nextcloud with the user's access token (probably via WebDAV). Begin of the insertionTunneled through OpenProject backend.End of the insertion
* Location picker for upload targets (a target is always a directory). Queries Nextcloud with the user's access token (probably via WebDAV). Begin of the insertionTunneled through OpenProject backend.End of the insertion
* If possible, direct upload of files to Nextcloud without tunneling through OpenProject server. This requires some sort of one-time upload tokens, which can get exposed to the OpenProject frontend. Fallback could be tunneling all uploaded files through OpenProject.
* Remove file links from OpenProject when files get deleted in Nextcloud (either some sort of callback triggered by Nextcloud or through polling when user opens the _Files_ tab).

### Implementation decisions:

* The file name we present in OpenProject is the name of the file that the file's owner sees. Apparently in Nextcloud a file can have multiple names and paths every time a file gets shared. To have a "canonical" name for all OpenProject users we will always show the file name that the file's owner sees.
* OpenProject updates the "cached" file name in OpenProject when a user open the _Files_ tab.

### Out of scope:

* Syncing of access rights to the files in Nextcloud according to the roles and privileges of members in a OpenProject project. Begin of the insertionThat will get partly tackled laterEnd of the insertion Begin of the deletion This would require two things
* OpenProject is somehow owning directories and files and can share themEnd of the deletion with Begin of the insertionshared project folders (<mention class="mention" data-id="41400" data-type="work_package" data-text="#41400">#41400</mention>)End of the insertion Begin of the deletion (read or read/write permissions with other Nextcloud users).
* All users and groups are in sync between OpenProject and Nextcloud. It seems a good idea to use LDAP as the single source of truth. However, the timing, when all users and groups have completed syncing with both systems, OpenProject and Nextcloud, does not seem trivial.End of the deletion
* Linking between a OpenProject project (instead of work packages) and files in Nextcloud. That is feasible and intended to built in a later stage. The outlook could be a possible replacement for the current &quot;Documents&quot; module.

### Wire frames (to sketch the idea. Not final design)

Listing attachments and file links in a separate :work package tab

<figure class="image op-uc-figure"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/29264/content"></div></figure>

Linked file&#39;s meta data

<figure class="image op-uc-figure"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/29263/content"></div></figure>

Uploading files via drag&#39;n drop (early concept sketch)

<figure class="image op-uc-figure"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/29265/content"></div></figure>

File picker

<figure class="image op-uc-figure"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/29266/content"></div></figure>