Nextcloud supports several techniques as an auth provider:

• OAuth2
• OpenID connect
• SAML
• LDAP
• App passwords

For our current purpose we should focus on OAuth2/OIDC, as we want our OpenProject backend to work as a client to the nextcloud server. Besides tunneled requests from the browser with the OP frontend, we also want to make server to server request to e.g. fetch meta data of our file references.

The following BASH script contains a number of "curl" calls to the Nextcloud API in order to validate a basic synchronization algorithm.

#!/usr/bin/bash


# OpenProject -> Nextcloud Sync Algorithm:
#
# We represent OpenProject project membership by sharing the project folder
# with the respective users or groups in Nextcloud:
#
# Go through the list of OpenProject Projects:
#	Identify the project folder below the OpenProject root in Nextcloud
#	Create a project folder (using WebDAV Folder API) if it doesn't exist yet
#	Go through the list of OpenProject project members (groups an users from LDAP)
#	and their permissions and compare with Nextcloud shares
#		Create a new Nextcloud share for the user or group if necessary
#		Delete an old NC share if not in OpenProject
#
# Synchroneous operation (as part of the GUI):
#	New project: Sync the new project
#	New project member: Just sync the specific share
#
# Special cases:
#	New group member in LDAP:
#	This could be an issue in the case of a new employee
#	because both systems need to be synced with LDAP.


# Implement getting/setting of "Advanced Permissions" (ACL) via OCS API #1256
# https://github.com/nextcloud/groupfolders/issues/1256
# - Managing

# -------------------------------------------------------
# Run Nextcloud OCC CLI commands

# Taken from nextcloud-link - Node.js interface for Nextcloud including Group Folders
# From: https://github.com/tentwentyfour/nextcloud-link/blob/master/tests/groupfolders-jest.ts
#
# docker exec -u 33 -it integration_openproject_nc bash -c 'php occ list'
# docker exec -u 33 -it integration_openproject_nc bash -c 'php occ app:install groupfolders'


# -------------------------------------------------------
# Get the list of users:
curl -u admin:admin -H "OCS-APIRequest: true" -H 'Accept: application/json' -X GET 'http://localhost/ocs/v1.php/cloud/users'
# {"ocs":{...},"data":{"users":["admin","user1","user2","user3"]}}}

# Get detailed information about one user:
curl -u admin:admin -H "OCS-APIRequest: true" -H 'Accept: application/json' -X GET 'http://localhost/ocs/v1.php/cloud/users/admin'
# {"ocs":{...},"data":{"enabled":true,"storageLocation":"\/var\/www\/html\/data\/admin","id":"admin","email":"admin@example.com","displayname":"admin","groups":["admin"],"language":"en", ...}}}


# -------------------------------------------------------
# Capabilities API:
curl -u admin:admin -X GET  -H "OCS-APIRequest: true" -H 'Accept: application/json' 'http://localhost/ocs/v1.php/cloud/capabilities'
# {"ocs":{"meta":{"status":"ok","statuscode":100,"message":"OK","totalitems":"","itemsperpage":""},"data":{"version":{"major":23,"minor":0,"micro":2,"string":"23.0.2","edition":"","extendedSupport":false}, ...}


# -------------------------------------------------------
# Group Folders API:

# Not working:
# curl -u admin:admin -H "OCS-APIRequest: true" -H 'Accept: application/json' -X GET 'http://localhost/ocs/v2.php/apps/groupfolders/folders'

# Not working:
# curl -u admin:admin -H "OCS-APIRequest: true" -H 'Accept: application/json' -X GET 'http://localhost/ocs/v2.php/apps/groupfolders/folders/1'

# Working:
# curl -u admin:admin -H "OCS-APIRequest: true" -H 'Accept: application/json' -X GET 'http://localhost/ocs/v2.php/apps/activity/api/v2/activity'

# Get the list of group folders (working):
# curl -u admin:admin -H "OCS-APIRequest: true" -H 'Accept: application/json' -X GET 'http://localhost/index.php/apps/groupfolders/folders'
# {"ocs":{"meta":{...},"data":{"1":{"id":1,"mount_point":"My Group Folder","groups":{"Test Group":31,"admin":31},"quota":-3,"size":0,"acl":true,"manage":[{"type":"group","id":"admin","displayname":"admin"}]}}}}

# Get details for one folder (working):
curl -u admin:admin -H "OCS-APIRequest: true" -H 'Accept: application/json' -X GET 'http://localhost/index.php/apps/groupfolders/folders/1'
# {"ocs":{"meta":{...},"data":{"id":1,"mount_point":"My Group Folder","groups":{"Test Group":31,"admin":31},"quota":-3,"size":0,"acl":true}}}

# Not Working (error page):
curl -u admin:admin -H "OCS-APIRequest: true" -H 'Accept: application/json' -H "Content-Type: application/json" \
# -X POST 'http://localhost/index.php/apps/groupfolders/folders' --data-raw '{"mount_point":"My Group Folder 2"}'

# Group Folders set ACL (not working):
curl -u admin:admin -X POST -H "OCS-APIRequest: true" -H 'Accept: application/json' 'http://localhost/index.php/apps/groupfolders/folders/1/acs' --data-raw '{"acl":0}'
curl -u admin:admin -X POST -H "OCS-APIRequest: true" -H 'Accept: application/json' 'http://localhost/index.php/apps/groupfolders/folders/1/acs' --data-raw '{"acl":"0"}'
curl -u admin:admin -X POST -H "OCS-APIRequest: true" -H 'Accept: application/json' 'http://localhost/index.php/apps/groupfolders/folders/1/acs' --data-raw '{"acl":"false"}'
curl -u admin:admin -X POST -H "OCS-APIRequest: true" -H 'Accept: application/json' 'http://localhost/index.php/apps/groupfolders/folders/1/acs' --data-raw '{"acl":false}'

# Check if acs:true still set in folder info
curl -u admin:admin -H "OCS-APIRequest: true" -H 'Accept: application/json' -X GET 'http://localhost/index.php/apps/groupfolders/folders/1'


# -------------------------------------------------------
# WebDAV Protocol for Nextcloud:
# https://docs.nextcloud.com/server/latest/developer_manual/client_apis/WebDAV/basic.html
# Get the list of files for user admin in user's home directory
curl -u admin:admin -X PROPFIND 'http://localhost/remote.php/dav/files/admin/' | xml_pp

# Get the list only for Depth=1
curl -u admin:admin -X PROPFIND -H "Depth: 1" 'http://localhost/remote.php/dav/files/admin/' | xml_pp


# List directory with specific attributes with proper XML namespaces
curl -u admin:admin -X PROPFIND \
-d '<?xml version="1.0"?><d:propfind xmlns:d="DAV:" xmlns:oc="http://owncloud.org/ns" xmlns:nc="http://nextcloud.org/ns"><d:prop><d:getlastmodified />' \
'http://localhost/remote.php/dav/files/admin/' 


# List directory with specific attributes with abbreviated namespaces
curl -u admin:admin -X PROPFIND \
	-d '<d:propfind xmlns:d="DAV:"><d:prop><d:getlastmodified /></d:prop></d:propfind>' \
	'http://localhost/remote.php/dav/files/admin/' | xml_pp 

# Download a file
curl -u admin:admin -X GET 'http://localhost/remote.php/dav/files/admin/Nextcloud.png' --output Nextcloud.png

# Create a new folder
curl -u admin:admin -X MKCOL 'http://localhost/remote.php/dav/files/admin/TestFolder'

# Upload same file with different name
curl -u admin:admin -X PUT 'http://localhost/remote.php/dav/files/admin/TestFolder/Nextcloud2.png' --upload-file Nextcloud.png


# -------------------------------------------------------
# Nextcloud Shares API:

# https://docs.nextcloud.com/server/latest/developer_manual/client_apis/OCS/ocs-share-api.html

# Get the list of all shares for a given user:
curl -u admin:admin -H 'Accept: application/json' -H 'OCS-APIRequest: true' http://localhost/ocs/v2.php/apps/files_sharing/api/v1/shares
# {"ocs":{"meta":{"status":"ok","statuscode":200,"message":"OK"},"data":[
# {"id":"2","share_type":0,"uid_owner":"admin","displayname_owner":"admin","permissions":19,"can_edit":true,"can_delete":true,"stime":1646926576,"parent":null,"expiration":null,"token":null,"uid_file_owner":"admin","note":"","label":null,"displayname_file_owner":"admin","path":"\/test.txt","item_type":"file","mimetype":"text\/plain","has_preview":true,"storage_id":"home::admin","storage":2,"item_source":348,"file_source":348,"file_parent":6,"file_target":"\/test-user1.txt","share_with":"user1","share_with_displayname":"User1","share_with_displayname_unique":"user1@example.com","status":{"status":"offline","message":null,"icon":null,"clearAt":null},"mail_send":0,"hide_download":0},
# {"id":"1","share_type":3,"uid_owner":"admin","displayname_owner":"admin","permissions":17,"can_edit":true,"can_delete":true,"stime":1646923228,"parent":null,"expiration":null,"token":"KDSfefYx8cycGoG","uid_file_owner":"admin","note":"","label":"","displayname_file_owner":"admin","path":"\/Photos\/Readme.md","item_type":"file","mimetype":"text\/markdown","has_preview":true,"storage_id":"home::admin","storage":2,"item_source":29,"file_source":29,"file_parent":28,"file_target":"\/Readme.md","share_with":null,"share_with_displayname":"(Shared link)","password":null,"send_password_by_talk":false,"url":"http:\/\/localhost\/s\/KDSfefYx8cycGoG","mail_send":0,"hide_download":0}
# ]}}

This pagee contains some usefule information about the development process in this project.

Considerations about files and fileIds in Nextcloud to keep in mind
item here means files or folder

• items don't have a creator or modifier attribute, only owner
• items ownership is changed (but not the id) when a user receives a folder as a share and moves an item out of the share to an other location
• if a user is deleted all items that are owned by the user are deleted
• a received shared item can be renamed and that name will not be propagated to the owner or other share receivers
• a rename of an item in a received folder share will be propagated to the owner and other share receivers
• multiple names can be associated with the same fileId. e.g. :
  1. James has a folder called "Documents" with a file called "important.doc"
  2. James shares folder "Documents" with Peter
  3. James shares separately "Documents/important.doc" with Peter
  4. Peter will have receiver "important.doc" twice but both "location" of the file will have the same fileId
  5. when Peter takes the fileId and queries for its name OCP\Filles\Folder::getById() he will receive two objects and in case he renamed one of the representations of the file both of the objects will show different names

Julien approves all above statements.

Summarizes the work that was done to create a working hypothesis and some technical background for the Nextcloud integration.

1. When to start - entry criteria?

   1. When is the next release?

   2. Stable process for Nextcloud version bumps

2. Release preparation

   1. What steps are taken, who is doing what?

   2. Timelines and Timeframes

3. QA process

   1. How is giving the green light?

   2. How is doing and communicating with whom?

4. Release - exit criteria

   1. When is the final release?

   2. Have a checklist to know what conditions need to be met.

5. After release

   1. Handing over process

   2. Communication, who to ping

1. When to start a release - entry criteria?

   1. External reasons

      1. Nextcloud Major version release

         1. Have it released between 4 to 2 weeks before Nextcloud release

         2. Have version bump released with other Bugs or Features id possible

         3. If not a NC version bump in the release is a patch release

      2. Dependencies change or break

         1. Release only if really needed, but as soon as possible

      3. Security issues

         1. Do not create a work package in the a public accessible project

         2. Release as soon as possible

   2. Internal reasons

      1. Features is finished

         1. No hard rules and based on strategy.

         2. Normally features/epics should be released within 2 weeks.

      2. Bugs are fixed

         1. Soonish, if Bugs are merged they should be released within 4 weeks
         
         

2. Release preparation

   1. What steps are taken, who is doing what?

      • Version should have been already created in OpenProject before, if not create one (Dominic)

      • Query should have been already created in OpenProject in the Nextcloud project beforehand and mark it as favorite, if not create one (Dominic)

      • Mage sure all work package are assigned to the version (Dominic)

      • Announce planned release to team (Product owner - Dominic)

      • Create work package for release. (Or template project for release) (Dominic)

      • Create branch if needed in GitHub (Sajan)

      • Change deployment target if needed on QA deployment script (DevOps)

      • Add change logs (Sajan)

      • Tag version in Github (Sajan)

      • Ping QA (Cécile) that release is ready for testing (Sajan)

   2. Timelines and Timeframes

      1. Needs to be defined

3. QA process

   1. How is giving the green light?

      1. Project owner - Dominic

   2. How is doing and communicating with whom?

      1. By default between Sajan and Dominic

4. Release - exit criteria

   1. When is the final release?

      1. Have checklist that needs to be defined like in OpenProject template release project

5. After release

   1. Handing over process

OpenProject -> Nextcloud integration sequence diagram:

This diagram shows the control flow starting off with a user visiting a OpenProject page with an embedded WebDAV client to actually showing the results, for example a directly list via WebDAV.

This is the Wiki for the Nextcloud integration project.