Content
View differences
Updated by Marc Alcobé about 4 years ago
## 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 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)
* 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)
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" section in the files tab that allows the user to see and access on Nextcloud linked files. This tab should allow the user to:
1. See what files has been linked to this work package
2. ~~Add folder(s) and file(s) as links~~ In this version linking is only possible through Nextcloud
3. ~~Remove each link (manually)~~ In 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. Download the file or folder locally
5. Open the specific file(s) in Nextcloud (in a new tab)
6. Open the containing folder in Nextcloud (in a new tab)
7. See the information of the file(s) (metadata)
8. Log/connect in to Nextcloud if the user is not connected
4. Authentication and authorisation (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 \[<mention class="mention" data-id="42086" data-type="user" data-text="@Wieland Lindenthal">@Wieland Lindenthal</mention> what is the current status on this? Can we update the specs for this?\])_
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?).
## The Nextcloud section in files tab
For the Nextcloud section inside of the files 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 \[<mention class="mention" data-id="42086" data-type="user" data-text="@Wieland Lindenthal">@Wieland Lindenthal</mention> what about the bridge interface? Do we need to do something here?\]
The following assumes that the link has already been made.
The Nextcloud section appears right bellow the "Attachments" section of the files tab.
* In case there is a connection in the instance but the user is not logged into Nextcloud the following message will be displayed "Login to Nexcloud. To add a link or upload files for the first time, please login to Nextcloud.", an illustration, a button to login in Nextcloud and the files related with this work package greyed out.
<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 message is displayed bellow the sub-header "Link files in Nexcloud. In order to link files to this work package please do it via Nextcloud". 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> src="/api/v3/attachments/30565/content"></div></figure>
* In case the instance has a connection but it is broken because of some technical reason or login fail the following message will be displayed "No Nextcloud connection. Some Nextcloud settings are not working. Please try to login again or contact your Nexcloud administrator.", 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>
When there are files or folders that are already linked, this will affect the number on the Files tab and will be displayed in the "Nextcloud" file list as specified bellow:
### **File list**
The 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 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\]
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 \[<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?\]
* 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 "File information" section. This will be opened when the users clock on the file info icon of a file, this will have a open persistent behaviour that will allow users to switch between files informations until they close it through the top right "X" 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 information:
* 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 "sticky", in that if the file list above it is especially long, a vertical scroll will be needed.
##
## 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'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's file picker/uploader component (This is currently not the preferred option). Then the authentication would be achieved by the browser'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'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 "Sort by" 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) [https://www.figma.com/file/gtLQfPe09X7XugAH8L7dTy/?node-id=337%3A22899](https://www.figma.com/file/gtLQfPe09X7XugAH8L7dTy/?node-id=337%3A22899)
_(Please ensure that the "Nextcloud in OP Integration - V1.1" page is selected in the top-left page list)_
##
##
## Open Questions and Subsequent Decisions
_(based on our exchange on 20 December at 14h)_
* [ ] Only 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 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 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. _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>._ data-text="#41351">#41351</mention>._
* [ ] Are 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 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...). _This is now specified in <mention class="mention" data-id="41351" data-type="work_package" data-text="#41351">#41351</mention>._
**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 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)
* 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)
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" section in the files tab that allows the user to see and access on Nextcloud linked files. This tab should allow the user to:
1. See what files has been linked to this work package
2. ~~Add folder(s) and file(s) as links~~ In this version linking is only possible through Nextcloud
3. ~~Remove each link (manually)~~ In 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. Download the file or folder locally
5. Open the specific file(s) in Nextcloud (in a new tab)
6. Open the containing folder in Nextcloud (in a new tab)
7. See the information of the file(s) (metadata)
8. Log/connect in to Nextcloud if the user is not connected
4. Authentication and authorisation (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 \[<mention class="mention" data-id="42086" data-type="user" data-text="@Wieland Lindenthal">@Wieland Lindenthal</mention> what is the current status on this? Can we update the specs for this?\])_
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?).
## The Nextcloud section in files tab
For the Nextcloud section inside of the files 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 \[<mention class="mention" data-id="42086" data-type="user" data-text="@Wieland Lindenthal">@Wieland Lindenthal</mention> what about the bridge interface? Do we need to do something here?\]
The following assumes that the link has already been made.
The Nextcloud section appears right bellow the "Attachments" section of the files tab.
* In case there is a connection in the instance but the user is not logged into Nextcloud the following message will be displayed "Login to Nexcloud. To add a link or upload files for the first time, please login to Nextcloud.", an illustration, a button to login in Nextcloud and the files related with this work package greyed out.
<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 message is displayed bellow the sub-header "Link files in Nexcloud. In order to link files to this work package please do it via Nextcloud". 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 login fail the following message will be displayed "No Nextcloud connection. Some Nextcloud settings are not working. Please try to login again or contact your Nexcloud administrator.", 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>
When there are files or folders that are already linked, this will affect the number on the Files tab and will be displayed in the "Nextcloud" file list as specified bellow:
### **File list**
The
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 \[<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?\]
* 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 "File information" section. This will be opened when the users clock on the file info icon of a file, this will have a open persistent behaviour that will allow users to switch between files informations until they close it through the top right "X" 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 information:
* 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 "sticky", in that if the file list above it is especially long, a vertical scroll will be needed.
##
## 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'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's file picker/uploader component (This is currently not the preferred option). Then the authentication would be achieved by the browser'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'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 "Sort by" 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 "Nextcloud in OP Integration - V1.1" page is selected in the top-left page list)_
##
## Open Questions and Subsequent Decisions
_(based on our exchange on 20 December at 14h)_
* [ ] Only
**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
**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
**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. _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>._
* [ ] Are
**Decision:** We don't know yet, but surely prudent to plan ahead with the assumption that this may happen in the future.
* [ ] When
**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>._