## Specification

**As an** OpenProject user
**I want to** be able to see relevant linked files that I have on Nextcloud with work packages
**so that I**

* have all the relevant attachments concerning the work package,
* can be confident about having the latest version of the file(s),
* be confident that any updates to relevant files will not require manual relinking,
* I can associate the Begin of the deletion theEnd of the deletion same file(s) with several work packages Begin of the insertionwithoutEnd of the insertion Begin of the deletion withEnd of the deletion making additional copies.
* I can update the relevant file(s) on Nextcloud and know that the Begin of the insertionwork packageEnd of the insertion Begin of the deletion workpackageEnd of the deletion will still point to the right file(s) with all my updates.

## Example use cases

* There is a complex calculation that needs to be done in a spreadsheet tool. The work package describes the workflow to work on a specific part of that (eg. energy projections for a construction project). Other people are working on other parts, but it's important for everybody to have access to the same latest version (including the work of other people).
* Preparing slides for a workshop. Several users need to work collaboratively on different sections. This is easier if everyone is working on a single file to avoid version conflicts and facilitate collaboration.
* Creating a new quote. This requires input from contractors to specific files.

## Implementation considerations

1. Extend the data model in OpenProject to store certain information about files hosted in Begin of the insertionexternal file storages, such as Nextcloud and make it accessible viaEnd of the insertion Begin of the deletion Nextcloud:End of the deletion
Begin of the insertion1. OpenProject admin interface: Managing file storages.End of the insertion Begin of the deletion * IDEnd of the deletion
Begin of the deletion * Path (the hierarchy in Nextcloud's folder structure)
* Name
* File Type (~~and corresponding icon, if possible~~ _Icons are provided by OP_)
* Other meta (whatever is possible to extract)
* Format (eg. PDF, Word document, RTF, JPEG...)
* Last modified
* Created by
* Created (date)
End of the deletion 2. Begin of the insertionProject admin interface: Adding and removing file storages to projects.
3. End of the insertion Expose Begin of the insertionfile linkEnd of the insertion Begin of the deletion thisEnd of the deletion information with additional API endpoints Begin of the insertion(defined in <mention class="mention" data-id="40228" data-type="work_package" data-text="#40228">#40228</mention>)
End of the insertion Begin of the deletion
1. Return a list of all files linked to a particular work package
End of the deletion 2. Begin of the insertionAllow multiple, differentEnd of the insertion Begin of the deletion Return a list of all work packages linked to a singleEnd of the deletion file Begin of the insertionstorages per OpenProject instance and project (defined in <mention class="mention" data-id="40536" data-type="work_package" data-text="#40536">#40536</mention>) End of the insertion Begin of the deletion adding a new work package filter on file ID. (this information will be displayed/accessed on Nextcloud)End of the deletion
3. Begin of the insertionInEnd of the insertion Begin of the deletion Add a&quot;Nextcloud&quot; section inEnd of the deletion the Begin of the insertionOpenProject frontend for work packages add a _Files_End of the insertion Begin of the deletion filesEnd of the deletion tab that Begin of the insertionshows both, attachments (<mention class="mention" data-id="41340" data-type="work_package" data-text="#41340">#41340</mention>)End of the insertion Begin of the deletion allows the user to seeEnd of the deletion and Begin of the insertionlinksEnd of the insertion Begin of the deletion access on Nextcloud linked files. This tab should allow the user to:
1. See what files has been linkedEnd of the deletion to Begin of the insertionfiles in external storages (defined below).
4.End of the insertion Begin of the deletion this work package
2.End of the deletion Begin of the insertionAuthenticationEnd of the insertion Begin of the deletion ~~Add folder(s)End of the deletion and Begin of the insertionauthorisation (OAuth2)End of the insertion Begin of the deletion file(s) as links~~ In this version linking is only possible through NextcloudEnd of the deletion
Begin of the insertion1.End of the insertion Begin of the deletion 3.End of the deletion Begin of the deletion ~~Remove each link (manually)~~End of the deletion In Begin of the insertionorder to fetchEnd of the insertion Begin of the deletion this version removing is only possible through Nextcloud \[<mention class="mention" data-id="42086" data-type="user" data-text="@Wieland Lindenthal">@Wieland Lindenthal</mention> is this correct?\]
4. DownloadEnd of the deletion the Begin of the insertionlatest meta data ofEnd of the insertion Begin of the deletion file or folder locally
5. Open the specific file(s) in Nextcloud (inEnd of the deletion a Begin of the insertionfile (name, type, size ...) OpenProject needs to be able to query thatEnd of the insertion Begin of the deletion new tab)
6. Open the containing folder in Nextcloud (in a new tab)
7. See theEnd of the deletion information Begin of the deletion of the file(s) (metadata)
8. Log/connectEnd of the deletion in Begin of the deletion to Nextcloud ifEnd of the deletion the Begin of the insertionnameEnd of the insertion Begin of the deletion user is not connected
4. Authentication and authorisation (OIDC)
_(This is really a tricky one and we need to work get a better understandingEnd of the deletion of Begin of the deletion it. The specification here is not sufficient. Here some suggestions \[<mention class="mention" data-id="42086" data-type="user" data-text="@Wieland Lindenthal">@Wieland Lindenthal</mention> what isEnd of the deletion the current Begin of the insertionuser. End of the insertion Begin of the deletion status on this? Can we update the specs for this?\])_End of the deletion
Begin of the deletion 1. Show login (unless already logged in), then authorize OP backend to access NC on behalf of the user.
End of the deletion 2. Begin of the insertionFor authorisation we will beEnd of the insertion Begin of the deletion Save these user tokens in the backend.
3. Make sure to solicit updated tokens before they time outEnd of the deletion using Begin of the insertionthe OAuth2 standard.End of the insertion Begin of the deletion refresh tokens (Cronjob?).End of the deletion

## The Nextcloud section in files tab

For the Nextcloud section inside of the files tab to appear in the work package split screen, the Begin of the insertionconnectionEnd of the insertion Begin of the deletion bridgeEnd of the deletion between OpenProject and Nextcloud should already have been established in Begin of the insertiontheEnd of the insertion settings. Begin of the insertionAn admin needsEnd of the insertion Begin of the deletion The precise interfaceEnd of the deletion to Begin of the insertionsetupEnd of the insertion Begin of the deletion do has yet to be described, but for now it involves sharingEnd of the deletion the Begin of the deletion API access token withEnd of the deletion the Begin of the insertionfile storageEnd of the insertion Begin of the deletion OpenProject appEnd of the deletion in Begin of the deletion Nextcloud \[<mention class="mention" data-id="42086" data-type="user" data-text="@Wieland Lindenthal">@Wieland Lindenthal</mention> what aboutEnd of the deletion the Begin of the insertionadmin settings and a project admin needsEnd of the insertion Begin of the deletion bridge interface? Do we needEnd of the deletion to Begin of the insertionactivate the file storage on a project. End of the insertion Begin of the deletion do something here?\]End of the deletion

The following assumes that the link has already been made.

The Nextcloud section appears right bellow the &quot;Attachments&quot; section of the files tab.

* In case there is Begin of the insertionfile storage setup onEnd of the insertion Begin of the deletion a connection inEnd of the deletion the Begin of the insertionprojectEnd of the insertion Begin of the deletion instanceEnd of the deletion but the user Begin of the insertionhasEnd of the insertion Begin of the deletion isEnd of the deletion not Begin of the insertionyet authorized OpenProject to act on her behalf inEnd of the insertion Begin of the deletion logged intoEnd of the deletion Nextcloud the following message will be displayed &quot;Login to Begin of the insertionNextcloud.End of the insertion Begin of the deletion Nexcloud.End of the deletion To add a link or upload files for the first time, please login to Nextcloud.&quot;, an illustration, a button to login Begin of the insertiontoEnd of the insertion Begin of the deletion inEnd of the deletion Nextcloud and the files related with this work package Begin of the insertionareEnd of the insertion greyed out. Begin of the insertionNote, the file names are already listed here although the current user might not have an account on Nextcloud, or might not have access rights for the files within Nextcloud. However, somebody in the project team linked that file and wanted to make it visible to other project team members. So if the current user has no access yet she will know that the file is there and that it is worth to connect her Nextcloud account and ask the file owner to also share that file with her. The overall goal of the integration is to make people find the relevant files.End of the insertion

<figure class="image op-uc-figure" style="width:75%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/30579/content"></div></figure>

* In case there is a connection done but no files linked an illustration and Begin of the insertiona messageEnd of the insertion Begin of the deletion  messageEnd of the deletion is displayed bellow the sub-header &quot;Link files in Nexcloud. In order to link files to this work package please do it via Nextcloud&quot;. Bellow a button to access Nexcloud will be displayed.

<figure class="image op-uc-figure" style="width:75%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/30582/content"></div></figure>

* In case the instance has a connection but it is broken because of some technical reason or Begin of the insertiontheEnd of the insertion login Begin of the insertionfailed, thenEnd of the insertion Begin of the deletion failEnd of the deletion the following message will be displayed &quot;No Nextcloud connection. Some Nextcloud settings are not working. Please try to login again or contact your Nexcloud administrator.&quot;, an illustration and a button to login in Nextcloud.

<figure class="image op-uc-figure" style="width:75%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/30580/content"></div></figure> Begin of the insertion

End of the insertion Begin of the deletion



End of the deletion When there are files or folders that are already linked, this will affect the number on the Begin of the insertion_Files_End of the insertion Begin of the deletion FilesEnd of the deletion tab and will be displayed in the &quot;Nextcloud&quot; file list as specified bellow:

### **File list**

The file list contains a list of all files and folders that are linked with a work package trough Nextcloud. This list will be ordered by date of modification of the file (as its displayed on the list) being the first one in the list the latest modified Begin of the insertionfile.End of the insertion Begin of the deletion file \[<mention class="mention" data-id="42086" data-type="user" data-text="@Wieland Lindenthal">@Wieland Lindenthal</mention>, I think we still need to validate this is possible\]End of the deletion

Each item in the file list is a linked file/folder, and it will be represented with these elements in a single line:

* An icon representing file type or folder (by clicking on this element the user will open the file/folder in a new tab)
* The file/folder name (by clicking on this element the user will open the file/folder in a new tab)
* Date of modification of the file
* User who did the modification Begin of the deletion \[<mention class="mention" data-id="42086" data-type="user" data-text="@Wieland Lindenthal">@Wieland Lindenthal</mention> is this correct? or is the creator of the file?\]End of the deletion
* On hover to this list element there will be multiple options:
* Download file
* Open containing folder: opens the folder where the file is stored (in the case of folders it opens the folder that contains the folder not the folder itself)
* Open file information (described bellow)
* Remove link

<figure class="image op-uc-figure" style="width:75%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/30567/content"></div></figure>

### File Information

The lower half of the split-screen is reserved for the &quot;File information&quot; section. This will be opened when the Begin of the insertionuser clicksEnd of the insertion Begin of the deletion users clockEnd of the deletion on the file info icon of a file, this will have a open persistent behaviour that Begin of the insertionallowsEnd of the insertion Begin of the deletion will allowEnd of the deletion users to switch between files Begin of the insertionand their meta informationEnd of the insertion Begin of the deletion informationsEnd of the deletion until they close it through the top right &quot;X&quot; icon or tab again on the information button on hover of any file. For the item selected, there is two possibilities of view:

* **With preview:** we have a preview link of the file from Nextcloud and we will display it as the top part of the file information. Bellow it there will be the rest of the Begin of the insertioninformation. Keep in mind that not all information will be available to every Nextcloud user. The list might be incomplete for some files and users:End of the insertion Begin of the deletion information:End of the deletion
* Filename
* File size
* Format
* Last modified
* Created by
* Created (date)

<figure class="image op-uc-figure" style="width:75%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/30568/content"></div></figure>

* **Without preview:** only the basic information will be displayed:
* Filename
* File size
* Format
* Last modified
* Created by
* Created (date)

<figure class="image op-uc-figure" style="width:75%;"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/30569/content"></div></figure>

This zone is Begin of the insertion&quot;sticky&quot;. IfEnd of the insertion Begin of the deletion &quot;sticky&quot;, in that ifEnd of the deletion the file list above it is especially long, a vertical scroll will Begin of the insertionget shown.End of the insertion Begin of the deletion be needed.End of the deletion

##

## Out of scope

The out of scope points mentioned bellow are covered in the next implementation documented in the work package <mention class="mention" data-id="41351" data-type="work_package" data-text="#41351">#41351</mention>:

* File/folder picker for referencing existing files/folders in Nextcloud
1. That file/folder picker should also allow for creating folders while picking (Not necessarily in the first version but obviously soon after)
2. Implementation options
1. One option would be to tunnel a request for file structure through OP&#39;s backend and impersonate the current user (This is currently preferred as it allows reusing the frontend for multiple storage providers)
2. Another option could be using Julian&#39;s file picker/uploader component (This is currently not the preferred option). Then the authentication would be achieved by the browser&#39;s Nextcloud session. If no session is open, the user needs to login first.
* File/folder upload
1. Allow uploading files
2. Allow uploading entire folder structures (just as NC allows it, too) _(I still don&#39;t know, how they do that. Webdav? I need to investigate it \[WL\])_
3. While picking the destination location also allow for creating new folder structures in NC, similar to the file/folder picker above.
* Setting file access permissions in Nextcloud.
* Direct file upload in OpenProject in the very first version
* Activity stream
* The lower half, below the the file list, represents the activity stream. This will contain:
* Activity related to the file (creation, modification, comments) and
* Comments posted directly on Nextcloud
* A Nextcloud icon next to the user icon indicates to the user that these elements correspond to activity on Nextcloud and not activity on the work package.

~~**Sort by**~~
~~Clicking on the &quot;Sort by&quot; button displays a drop-down with these options:~~

* ~~Alphabetical (A-Z)~~ _~~(selected by default)~~_
* ~~Last modified (newest first)~~
* ~~File size biggest first~~
* ~~File size: smallest first~~

## Visuals

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

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

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

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

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

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

##

## Figma link

The Figma prototype associated with this work package is available here:
[https://www.figma.com/file/gtLQfPe09X7XugAH8L7dTy/?node-id=337%3A22899](https://www.figma.com/file/gtLQfPe09X7XugAH8L7dTy/?node-id=337%3A22899)

_(Please ensure that the &quot;Nextcloud in OP Integration - V1.1&quot; page is selected in the top-left page list)_

##

##

## Open Questions and Subsequent Decisions

_(based on our exchange on 20 December at 14h)_

* [ ] Begin of the insertion  OnlyEnd of the insertion Begin of the deletion  OnlyEnd of the deletion link files or also folders?
**Decision:** Link both files and folders in the exact same way, i.e. as a reference to the file/folder in a flat list. The user in OP can&#39;t access the _contents_ of the folder, merely see that it&#39;s linked to the work package. To access containing files, she will have to click through and access them on Nextcloud.
* [ ] Begin of the insertion  ReplaceEnd of the insertion Begin of the deletion  ReplaceEnd of the deletion OP attachments with NC file links? Or join them? Or keep them separate?
**Decision**: NC file links _supplement_ OP attachments and do not replace them. Concretely, any files uploaded to a work package in the classic way (via drag/drop or the upload file selector in the Files section of a work package; via drag/drop in a comment...) will continue to be considered attachments as they are today.
* [ ] Begin of the insertion  AreEnd of the insertion Begin of the deletion  AreEnd of the deletion we going to create our own file or folder picker vs. reusing Julien&#39;s?
**Decision**: Couldn&#39;t complete discussing this topic but to future-proof our file picker and maintain consistency between different file hosting services (should they one day also be supported), we&#39;ll create our own. _This is not relevant for this WP as it belongs to <mention class="mention" data-id="41351" data-type="work_package" data-text="#41351">#41351</mention>._
* [ ] Begin of the insertion  AreEnd of the insertion Begin of the deletion  AreEnd of the deletion we sure that we will have or will never have multiple NC/Google drive/Dropbox/etc. instances connected to an OP instance?
**Decision:** We don&#39;t know yet, but surely prudent to plan ahead with the assumption that this may happen in the future.
* [ ] Begin of the insertion  WhenEnd of the insertion Begin of the deletion  WhenEnd of the deletion are we going to implement file uploads from work packages to NC? In the first version, or the very next?
**Decision:** The product team can explore how file uploads might work from directly within OP (including the complexity that that maybe introduce); however, we do not consider this to be a deal-breaker for the first version or a beta. Whether or not this should be a minimum for a _release_, however, remains open. Also discussed was a need to examine properly how much of the file upload workflow that Nextcloud allows should be recreated in OpenProject (for example, folder creation, bulk upload, folder upload...). _This is now specified in <mention class="mention" data-id="41351" data-type="work_package" data-text="#41351">#41351</mention>._