This app makes for an enhanced federated sharing user experience.
Through a simple one-time invitation by email to a person known to have an account on another Owncloud instance some selected user information (including cloud ID) is automatically exchanged and saved on each other's systems. From thereon both users can easily issue federated shares between each other via the regular file sharing dialog, because the system will also search for and display invited remote users along with local users.
Fig.1 Sharing a photo with invited remote user Lex.
- Implements an Invitation Workflow
- Implements searchable invited (remote) users
Depends on the following Owncloud apps: Federated File Sharing, Notifications
Clone the project. The app runs in Owncloud so have a local Owncloud instance running. To deploy the app in your local Owncloud instance build it by first running composer from the project root folder as you would for any php project. This will create the vendor dependencies folder.
Next build the project by executing the command: make version={version_number} buildapp
This will create the collaboration_version_number.tar.gz file in the build/artifacts/app folder. After extracting you must place the resulting collaboration folder in the apps folder of your local Owncloud instance. This should make Owncloud aware of the app.
Now you can activate it and start experimenting. For a full experience you should setup 2 instances between which you can send invitations and create federated shares.
Use one of the official releases or build your own compressed archive as explained here.
Deploy the app by copying the extracted collaboration folder of the official release or your own custom build to the Owncloud apps folder.
Finally the admin should activate the app. It should than be present as a menu entrance for all users.
To activate enhanced federated sharing (search and display invited remote users in the share dialog) the following configuration must be added to the config.php file of the Owncloud instance:
'sharing.remoteShareesSearch' => '\\OCA\\Collaboration\\Service\\RemoteUserService'
To be able to send invitations between Owncloud instances the app must be installed on each one of them.
Also you must configure the other (remote) instances you want to be able to send invitations to. This is done on the admin settings section of the app (Settings page -> Admin Sharing page -> Invitation Service section).
Fig.2 Invitation Service settings page.
- Enabling this option prevents owncloud from showing the label of an uninvited remote user when typing in a cloud ID in the share dialog. Only invited remote users' labels will be displayed to you (as shown in figure 1).
* Note that this option does not actually disable federated sharing functionality with uninvited remote users but just does not show the label of an uninvited remote user.
- Here you should specify the endpoint and name of this instance's Invitation Service Provider.
The endpoint structure is as follows:https://[host]/[path]/apps/collaboration
- Here you should specify all Invitation Service Providers you want to enable exchanging cloud IDs via invitations with.
Click the 'Add Provider' button, fill in the remote provider's endpoint and click 'Save'. The availablity of the remote provider will be verified before it will be added.
To remove a remote provider click the thrashbin icon of the relevant provider. This will disable invitation functionality with that Owncloud instance.
When contributing please perform the following checks locally before pushing code to the repo. Github workflows will do these checks too:
-
Run
make php-codesniffer-errorsfrom the project root folder and fix the errors before pushing to the repo.
For your conveniencemake php-codesniffer-errors-fixwill take care of most errors.
The PSR-12 code formatting style is followed. -
Run the integrations tests from the
tests/dockerfolder with the following command:
docker compose --verbose --progress=plain -f docker-compose-local.yaml run --build --entrypoint /bin/sh --rm integration-tests -- ./tmp/tests/tests.sh
Check the outcome of the tests and fix any issue.
*Note: you should remove at least the volumes before running the tests again because those are not removed after running locally. Thedocker-cleanup.shscript specifically created for that can be found here.
- Upon pushing commits a workflow doing some codechecking is executed. You should prepare for that.
- Building a release .tar.gz file
- To display the generated invite link upon the creation of an invite:
Add the key/value set to the dbappconfigtable to display the invite link after an invitation has been created:
| appid | configkey | configvalue |
|---|---|---|
| collaboration | deploy_mode | deploy_mode_test |
The Invitation Workflow has been designed with sync-and-share systems in mind. It implements a controlled exchange of user information between sync-and-share systems. This can be particularly usefull in the case of federated sharing were some knowledge (eg. user id) of the remote user is required.
The workflow starts off by sending an invitation via email to the remote counterpart with the request to exchange user information (see figure 2 below).
The actual exchange of user information takes place in the final step of the invitation workflow. This step (HTTP POST request /invite-accepted) is part of the Open Cloud Mesh specification.
Handling of the invitation is regulated by a Mesh Registry Service that has knowledge of all systems between which user information may be exchanged this way.
Fig.3 - The invitation workflow as implemented in the Invitation app.