## Open Questions and Subsequent Decisions

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

* [ ] Only 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't access the _contents_ of the folder, merely see that it's linked to the work package. To access containing files, she will have to click through and access them on Nextcloud.
* [ ] Replace 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.
* [ ] Are we going to create our own file or folder picker vs. reusing Julien's?
**Decision**: Couldn'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'll create our own.
* [ ] Are 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't know yet, but surely prudent to plan ahead with the assumption that this may happen in the future.
* [ ] When 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...).

## Specification

**As an** OpenProject user
**I want to** be able to associate relevant files 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 the same file(s) with several work packages with making additional copies.
* I can update the relevant file(s) on Nextcloud and know that the workpackage 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 Nextcloud:
* ID
* Path (the hierarchy in Nextcloud's folder structure) Begin of the insertion
* End of the insertion Begin of the deletion
End of the deletion Name
* File Type (and corresponding icon, if possible) Begin of the insertion
* Other meta (for file information, does the API return any of these?)
* Format (eg. PDF, Word document, RTF, JPEG...)
* Last modified
* Created by
* Created (date)End of the insertion
2. Expose this information with additional API endpoints
1. Return a list of all files linked to a particular work package
2. Return a list of all work packages linked to a single file adding a new work package filter on file ID.(this information will be displayed/accessed on Nextcloud)
3. Add a"Nextcloud" tab to work package split screen (described more in detail below)  that allows the user to access linked files. This tab should allow the user to:
1. Add Begin of the insertionfolder(s) andEnd of the insertion file(s) as links
2. Remove each link (manually)
3. Download the file Begin of the insertionor folderEnd of the insertion locally
4. Access the file Begin of the insertionor folderEnd of the insertion in Nextcloud (in a new tab)
5. Log in to Nextcloud if the user is not connected
4. Make these linked files Begin of the insertionand foldersEnd of the insertion visible under the "Files" section of a work package full screen Begin of the insertionview _(mockups in progress, a few points of clarification required)_End of the insertion Begin of the deletion view End of the deletion
5. Authentication and authorization (OIDC)
_(This is really a tricky one and we need to work get a better understanding of it. The specification here is not sufficient. Here some suggestions \[WL\])_
1. Show login (unless already logged in), then authorize OP backend to access NC on behalf of the user.
2. Save these user tokens in the backend.
3. Make sure to solicit updated tokens before they time out using refresh tokens (Cronjob?).
6. File/folder picker for referencing existing files/folders in Nextcloud
1. Begin of the insertion~~ThatEnd of the insertion Begin of the deletion ThatEnd of the deletion file/folder picker should also allow for creating folders while picking (Not necessarily in the first version but obviously soon Begin of the insertionafter)~~End of the insertion Begin of the deletion after)End of the deletion
_(Open question <mention class="mention" data-id="72512" data-type="user" data-text="@Marc Alcobé">@Marc Alcobé</mention> <mention class="mention" data-id="72513" data-type="user" data-text="@Parimal Satyal">@Parimal Satyal</mention> <mention class="mention" data-id="3" data-type="user" data-text="@Niels Lindenthal">@Niels Lindenthal</mention>: How do we determine who has access to these instantly created folders? Do simply inherit the access privileges from the parent folder? \[WL\])_ Begin of the insertion
_(**Response from Product:** <mention class="mention" data-id="42086" data-type="user" data-text="@Wieland Lindenthal">@Wieland Lindenthal</mention>: Excellent question; file upload introduces new challeneges that we still haven&#39;t fully had a chance to appreciate. I suggest we first discuss and decide together if we want to include file upload in v1 before getting to specifying/mocking-up the details.)_End of the insertion
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.
7. Begin of the insertion~~File/folder upload~~End of the insertion Begin of the deletion File/folder uploadEnd of the deletion
1. Begin of the insertion~~AllowEnd of the insertion Begin of the deletion AllowEnd of the deletion uploading Begin of the insertionfiles~~End of the insertion Begin of the deletion filesEnd of the deletion
2. Begin of the insertion~~AllowEnd of the insertion Begin of the deletion AllowEnd of the deletion uploading entire folder structures (just as NC allows it, Begin of the insertiontoo)~~ _~~(IEnd of the insertion Begin of the deletion too) _(IEnd of the deletion still don&#39;t know, how they do that. Webdav? I need to investigate it Begin of the insertion\[WL\])~~_End of the insertion Begin of the deletion \[WL\])_End of the deletion
3. Begin of the insertion~~WhileEnd of the insertion Begin of the deletion WhileEnd of the deletion picking the destination location also allow for creating new folder structures in NC, similar to the file/folder picker Begin of the insertionabove.~~
_(**Note from Product**: This sectionstriked out only until we decide what to do about file upload)_End of the insertion Begin of the deletion above.End of the deletion
8. Delete a link between a work package and a file/folder

## The Nextcloud tab

For the Nextcloud tab to appear in the work package split screen, the bridge between OpenProject and Nextcloud should already have been established in settings. The precise interface to do has yet to be described, but for now it involves sharing the API access token with the OpenProject app in Nextcloud.

The following assumes that the link has already been made.

The Nextcloud tab appears right to &quot;Watchers&quot; and left to Github. Clicking on it with display an empty screen with Begin of the insertionthreeEnd of the insertion Begin of the deletion twoEnd of the deletion buttons:

* Link Begin of the insertionfiles or foldersEnd of the insertion Begin of the deletion file(s)End of the deletion
* Begin of the insertionSort by
* End of the insertion Settings

Begin of the insertionWhen there are files or folders that are already linked, there will be a number next to the word &quot;Nextcloud&quot; with the number of linked items. For example: &quot;**Nextcloud (4)**&quot; (if there are for example 3 files and 1 folder linked to the work package).

End of the insertion _Note that this split screen view is naturally also available in split screen view accessed via a work package list._

Begin of the insertion###End of the insertion **Link Begin of the insertionfiles or folders**End of the insertion Begin of the deletion file(s)**End of the deletion

Clicking on this button has two possible behaviors:

* If the user is not logged in to Nextcloud, then a login dialogue is displayed Begin of the insertion~~(withEnd of the insertion Begin of the deletion (withEnd of the deletion the username/email field; a password field; a &quot;forgot password?&quot; link and the &quot;Log in to Nextcloud&quot; Begin of the insertionbutton).~~ The login dialogue is provided by NextCloud and is not designed or implemented by OpenProject. _(Note: mockups don&#39;t show the NextCloud login screen yet)._End of the insertion Begin of the deletion button)End of the deletion
* If the user is logged in, a file-picker dialogue is displayed

The file picker allows the user to navigate through the folders on Nextcloud visible to OpenProject. By default (and by design in the first first iteration), this will be everything under the &quot;OpenProject&quot; folder under home that was created at the moment the two accounts _(&quot;accounts&quot;? you mean the two instances, OP and NC \[WL\])_ were linked. _(I am not a big fan of that. Why do we need to restrict the integration to only work within a specific folder? Why can&#39;t we allow access to everything the current Nextcloud user has access to? \[WL\]) &lt;-- What did we decide here <mention class="mention" data-id="72513" data-type="user" data-text="@Parimal Satyal">@Parimal Satyal</mention> <mention class="mention" data-id="72512" data-type="user" data-text="@Marc Alcobé">@Marc Alcobé</mention>?_ Begin of the insertion

End of the insertion Begin of the deletion

End of the deletion The user is then free to navigate through the folder hierarchy to locate files Begin of the insertionand foldersEnd of the insertion to link. They may either select a single file or Begin of the insertionfolder,End of the insertion multiple files Begin of the insertionand foldersEnd of the insertion to link by clicking on the corresponding checkbox(es) next to Begin of the insertioneach itemEnd of the insertion Begin of the deletion the file name(s)End of the deletion and then clicking on the primary &quot;Link Selected&quot; button. This button remains disabled until at least one file Begin of the insertionor folderEnd of the insertion is Begin of the insertionselected.End of the insertion Begin of the deletion selected. End of the deletion

Begin of the insertionA folder can both be clicked to drill in to it, or selected by clicking on the checkbox next to it. A file obviously can only be selected.

End of the insertion The linked files Begin of the insertionand foldersEnd of the insertion then show up in the file list below where the &quot;Link Begin of the insertionfilesEnd of the insertion Begin of the deletion file(s)&quot;End of the deletion and Begin of the insertionfolders&quot; andEnd of the insertion Settings buttons are.

Begin of the insertion_Note: Please note that both technically and functionally, a link to a file or a folder works the same way. Linking a folder **does not** link the enclosed files to the work package, just the folder itself._

###End of the insertion **File list**

The upper half of the area below the buttons represents the file list. The file list contains a list of all files Begin of the insertionand foldersEnd of the insertion that are linked with a work package, Begin of the insertionseparatedEnd of the insertion Begin of the deletion displayedEnd of the deletion in Begin of the insertiontwo parts by default inEnd of the insertion alphabetical Begin of the insertionorder, as in:End of the insertion Begin of the deletion order.End of the deletion

Begin of the insertion* All files (A-Z)
* All folders (A-Z)

End of the insertion Each item in the file list is a linked file, with these elements in single line:

* An icon representing file type (acquired from Nextcloud, else we can provide a generic file Begin of the insertionicon), or folderEnd of the insertion Begin of the deletion icon)End of the deletion
* The Begin of the insertionfile/folderEnd of the insertion Begin of the deletion fileEnd of the deletion name
* The file size
* Download button (direct link to the file)
* View in Nextcloud button (opens in a new tab)
* A more icon with, for the moment, only one item
* Remove link

Begin of the insertion**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

**Open:** These options to be discussed.

Clicking on one of the other options changes the sort order accordingly. The files and folders are nevertheless listed separately (files first, then folders).

End of the insertion **Settings button**

_A description of the behavior of the Settings button will subsequently be added._

Begin of the insertion###

### File Information

The lower half of the split-screen is reserved for the &quot;File information&quot; section. This is empty till a file or folder is selected. For the item selected, it lists:

* Filename
* File size
* Format
* Last modified
* Created by
* Created (date)

This zone is &quot;sticky&quot;, in that if the file list above it is especially long, a vertical scroll will be needed.

_Note: this zone will almost certainly also evolve to include the Activity stream once we decide to include that._



End of the insertion ## Nextcloud elements in the Activity tab

_To be defined..._

_(I believe that this is out of scope for the MVP, right? \[WL\])_

## Out of scope

* Setting file access permissions in Nextcloud.
* Direct file upload in OpenProject in the very first version (though obviously will come very soon after)
* **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.

## Visuals

_An empty Nextcloud tab in a work package split screen view_

<figure class="image op-uc-figure"><div class="op-uc-figure--content"><img class="op-uc-image" Begin of the insertionsrc="/api/v3/attachments/24689/content"></div></figure>End of the insertion Begin of the deletion src="/api/v3/attachments/23998/content"></div></figure>End of the deletion

_A Begin of the insertionsingle file (selected)End of the insertion Begin of the deletion dialogue inviting the user to logEnd of the deletion in Begin of the deletion to Nextcloud to be able to accessEnd of the deletion the file Begin of the insertionlist, with file information visible underneath and a (1) next to the Nextcloud tab title_End of the insertion Begin of the deletion picker_End of the deletion

<figure class="image op-uc-figure"><div class="op-uc-figure--content"><img class="op-uc-image" Begin of the insertionsrc="/api/v3/attachments/24690/content"></div></figure>End of the insertion Begin of the deletion src="/api/v3/attachments/23999/content"></div></figure>End of the deletion

_The file picker allows the user to traverse the folder hierarchy to locate files Begin of the insertionand foldersEnd of the insertion to link with the current work package_

<figure class="image op-uc-figure"><div class="op-uc-figure--content"><img class="op-uc-image" Begin of the insertionsrc="/api/v3/attachments/24691/content"></div></figure>End of the insertion Begin of the deletion src="/api/v3/attachments/24000/content"></div></figure>End of the deletion

_Each file Begin of the insertionor folderEnd of the insertion Begin of the deletion in the fileEnd of the deletion list has action buttons to download or view in Nextcloud, and a more Begin of the insertionbutton. Note the Nextcloud tab title now says (4)._End of the insertion Begin of the deletion button_End of the deletion

<figure class="image op-uc-figure"><div class="op-uc-figure--content"><img class="op-uc-image" Begin of the insertionsrc="/api/v3/attachments/24693/content"></div></figure>



End of the insertion Begin of the deletion src="/api/v3/attachments/24001/content"></div></figure>

End of the deletion ## Figma link

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

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