Content
View differences
Updated by Parimal Satyal over 4 years ago
## Open Questions and Subsequent Decisions Missing key decisions from the specification below
_(based on our exchange on 20 December at 14h)_
* [ ] Only link files or also folders?
**Decision:** Link both files and (I believe that linking 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 is useful. Unless we decide different, I assume that it's linked we want to the work package. To access containing files, she will have to click through and access them on Nextcloud. allow it \[WL\])
* [ ] Replace OP attachments with NC file links? Or join them? Or keep them separate?
**Decision**: (I still have a hard time seeing how NC file links _supplement_ OP attachments and do not could replace them. Concretely, any files uploaded to a work package in attachments. For example the classic way (via drag/drop copy and paste or the upload file selector in the Files section drag'n drop of images to comments and description. You'd always need to chose a work package; via drag/drop in a comment...) will continue place where to save the file. Also I don't see how we can allow multiple file storage instances to be considered attachments as connected. So if we don't decide on this I assume that they are today. stay separate \[WL\])
* [ ] 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 (Unless we decide differently I assume that we create our file own picker and maintain consistency between different file hosting services (should they one day also be supported), we'll create our own. as this gives us the biggest flexibility for the future \[WL\])
* [ ] 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 (Until we decide differently I assume that this may happen in the future. will come at some point \[WL\])
* [ ] 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 (We can explore how file uploads might work from directly within OP (including the complexity do it in a second version as there will be workarounds. However, I believe that that maybe introduce); however, we do not consider this to be is a deal-breaker crucial feature in overall workflow/UX. I vote for allowing uploading right in 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...). \[WL\])
## Specification Spezification
**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)
Name
* File Type (and corresponding icon, if possible)
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 file(s) as links
2. Remove each link (manually)
3. Download the file locally
4. Access the file in Nextcloud (in a new tab)
5. Log in to Nextcloud if the user is not connected
4. Make these linked files visible under the "Files" section of a work package full screen view
_(I am not convinced of that idea. I see the intention here to reduce the risk of confusing attachment files with Nextcloud files. But I am not sure about mixing the two. For example, it makes things more complex if a user has to chose a location in Nextcloud where she wants to store the file. Also attached images can be shown inline in description and comments. Will that work when stored on Nextcloud? What would be the link? How do we ensure that the link is visible to everybody who has access to the WP? Also imagine you want to support more than one file storage instance per project, i.e. a second Nextcloud instance and a Google drive, how do you communicate in which place attachments are stored? I think the situation would be different if we had dedicated places in NC for storing files per WP but that isn't the case for the MVP. \[WL\])_
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 (probably not necessary when using NC's OIDC), 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 (Cronjob?).
6. File picker (to access the Nextcloud folder hierarchy via the split screen)
1. Pick a file in Nextclouds file structure to link it to the work package. One option could be to use
7. Delete a link between a
## 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 "Watchers" and left to Github. Clicking on it with display an empty screen with two buttons:
* Link file(s)
* Settings
_Note that this split screen view is naturally also available in split screen view accessed via a work package list._
**Link file(s)**
Clicking on this button has two possible behaviors:
* If the user is not logged in to Nextcloud, then a login dialogue is displayed (with the username/email field; a password field; a "forgot password?" link and the "Log in to Nextcloud" button)
* 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 "OpenProject" folder under home that was created at the moment the two accounts _("accounts"? 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't we allow access to everything the current Nextcloud user has access to? \[WL\])_
The user is then free to navigate through the folder hierarchy to locate files to link. They may either select a single file or multiple files to link by clicking on the corresponding checkbox(es) next to the file name(s) and then clicking on the primary "Link Selected" button. This button remains disabled until at least one file is selected.
The linked files then show up in the file list below where the "Link file(s)" and Settings buttons are.
**File list**
The upper half of the area below the buttons represents the file list. The file list contains a list of all files that are linked with a work package, displayed in alphabetical order.
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 icon)
* The file 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
**Activity stream**
_**(I believe that that the Activity stream is not part of the MVP, right? \[WL\])**_
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.
**Settings button**
_A description of the behavior of the Settings button will subsequently be added._
## 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
* Linking of folders.
_(I am not convinced anymore that excluding folders is a good idea. They could be very handy if you want to share the location for files of a work package, while the files in the location are shared more restrictively. For example, somebody could create a folder "On boarding of Michael" in NC for a work package "On boarding of Michael" in OP and share the folder it pretty openly in NC. Then some confidential files, i.e. a labor contract, could be shared with just the managers in NC and other, less confidential files could get shared with more people, such as a profile picture. In OP every user would only see the folder but not its contents. Thus the confidential files get never leaked. \[WL\])_
* Setting file access permissions in Nextcloud.
* Direct file upload in OpenProject _(Are we sure about this? For a MVP we could leave that out here, I believe, but it makes a lot of sense to have the upload feature. It creates a lot UX value \[WL\])_
* _(I need to know if we plan to support multiple NC instances (or even Google Drive) per OP instance. And actually the other way around, too. Do we plan to allow multiple OP instances to use one NC instance? \[WL\])_
* **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" src="/api/v3/attachments/23998/content"></div></figure>
_A dialogue inviting the user to log in to Nextcloud to be able to access the file picker_
<figure class="image op-uc-figure"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/23999/content"></div></figure>
_The file picker allows the user to traverse the folder hierarchy to locate files to link with the current work package_
<figure class="image op-uc-figure"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/24000/content"></div></figure>
_Each file in the file list has action buttons to download or view in Nextcloud, and a more button_
<figure class="image op-uc-figure"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/24001/content"></div></figure>
## 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 "Nextcloud in OP Integration (basic)" page is selected in the top-left page list)_
_(based on our exchange on 20 December at 14h)_
* [ ] Only link files or also folders?
**Decision:** Link both files and
* [ ] Replace OP attachments with NC file links? Or join them? Or keep them separate?
**Decision**:
* [ ] 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
* [ ] 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
* [ ] 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
## 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)
Name
* File Type (and corresponding icon, if possible)
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 file(s) as links
2. Remove each link (manually)
3. Download the file locally
4. Access the file in Nextcloud (in a new tab)
5. Log in to Nextcloud if the user is not connected
4. Make these linked files visible under the "Files" section of a work package full screen view
_(I am not convinced of that idea. I see the intention here to reduce the risk of confusing attachment files with Nextcloud files. But I am not sure about mixing the two. For example, it makes things more complex if a user has to chose a location in Nextcloud where she wants to store the file. Also attached images can be shown inline in description and comments. Will that work when stored on Nextcloud? What would be the link? How do we ensure that the link is visible to everybody who has access to the WP? Also imagine you want to support more than one file storage instance per project, i.e. a second Nextcloud instance and a Google drive, how do you communicate in which place attachments are stored? I think the situation would be different if we had dedicated places in NC for storing files per WP but that isn't the case for the MVP. \[WL\])_
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 (probably not necessary when using NC's OIDC), 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 (Cronjob?).
6. File picker (to access the Nextcloud folder hierarchy via the split screen)
1. Pick a file in Nextclouds file structure to link it to the work package. One option could be to use
7. Delete a link between a
## 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 "Watchers" and left to Github. Clicking on it with display an empty screen with two buttons:
* Link file(s)
* Settings
_Note that this split screen view is naturally also available in split screen view accessed via a work package list._
**Link file(s)**
Clicking on this button has two possible behaviors:
* If the user is not logged in to Nextcloud, then a login dialogue is displayed (with the username/email field; a password field; a "forgot password?" link and the "Log in to Nextcloud" button)
* 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 "OpenProject" folder under home that was created at the moment the two accounts _("accounts"? 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't we allow access to everything the current Nextcloud user has access to? \[WL\])_
The user is then free to navigate through the folder hierarchy to locate files to link. They may either select a single file or multiple files to link by clicking on the corresponding checkbox(es) next to the file name(s) and then clicking on the primary "Link Selected" button. This button remains disabled until at least one file is selected.
The linked files then show up in the file list below where the "Link file(s)" and Settings buttons are.
**File list**
The upper half of the area below the buttons represents the file list. The file list contains a list of all files that are linked with a work package, displayed in alphabetical order.
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 icon)
* The file 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
_**(I believe that that the Activity stream is not part of the MVP, right? \[WL\])**_
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.
_A description of the behavior of the Settings button will subsequently be added._
## 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
* Linking of folders.
_(I am not convinced anymore that excluding folders is a good idea. They could be very handy if you want to share the location for files of a work package, while the files in the location are shared more restrictively. For example, somebody could create a folder "On boarding of Michael" in NC for a work package "On boarding of Michael" in OP and share the folder it pretty openly in NC. Then some confidential files, i.e. a labor contract, could be shared with just the managers in NC and other, less confidential files could get shared with more people, such as a profile picture. In OP every user would only see the folder but not its contents. Thus the confidential files get never leaked. \[WL\])_
* Setting file access permissions in Nextcloud.
* Direct file upload in OpenProject _(Are we sure about this? For a MVP we could leave that out here, I believe, but it makes a lot of sense to have the upload feature. It creates a lot UX value \[WL\])_
* _(I need to know if we plan to support multiple NC instances (or even Google Drive) per OP instance. And actually the other way around, too. Do we plan to allow multiple OP instances to use one NC instance? \[WL\])_
* **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" src="/api/v3/attachments/23998/content"></div></figure>
_A dialogue inviting the user to log in to Nextcloud to be able to access the file picker_
<figure class="image op-uc-figure"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/23999/content"></div></figure>
_The file picker allows the user to traverse the folder hierarchy to locate files to link with the current work package_
<figure class="image op-uc-figure"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/24000/content"></div></figure>
_Each file in the file list has action buttons to download or view in Nextcloud, and a more button_
<figure class="image op-uc-figure"><div class="op-uc-figure--content"><img class="op-uc-image" src="/api/v3/attachments/24001/content"></div></figure>
## 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 "Nextcloud in OP Integration (basic)" page is selected in the top-left page list)_