diff --git a/admin_manual/groupware/circles/app_overview.rst b/admin_manual/groupware/circles/app_overview.rst new file mode 100644 index 000000000..b32f18648 --- /dev/null +++ b/admin_manual/groupware/circles/app_overview.rst @@ -0,0 +1,152 @@ +======== +Overview +======== + +Circles is a Nextcloud App that allow Nextcloud users to generate their own grouping of users and contacts. + + + +Types of Circles +^^^^^^^^^^^^^^^^ + +.. note:: + Once the Circles app is enabled, your users can creates 2 types of Circles: `Circle` and `Personal Circle`. + There is no way to switch from `Circle` to `Personal Circle` and vice versa. + `Personal Circle` are really specific and will be treated separately. + + +When creating a Circle, its default configuration makes it 'Closed' and `Hidden`, meaning than no one +can see it or join it but the Circle can already be used as an entity to share files and content. +The user that created the Circle is the first and only Member and will have Owner rights that allows him/her to: + +- add/remove Members, +- edit their Level, +- change the settings of the Circle, +- change its configuration + +.. _app_overview_type_circles: + +The configuration is done by enabling/disabling some flag that define the way other people view and join the Circle: + + - **Visible** (8): Visible to everyone, if not visible, people have to know its name to be able to find + it. + + - **Open** (16): Circle is open, people can join it. + + - **Invite** (32): Adding a Member generate an invitation that needs to be accepted. + + - **Request** (64): A request to join the Circle needs to be validated by a Moderator. + + - **Friend** (128): Members of the Circle can invite their friends. + + - **Password Protected** (256): a Password is required to join or request to join the Circle. + + - **Federated** (8192): Circle is Federated. (cf. :doc:`federated_overview`) + +Mixed, those flags can generate some interesting configurations: + + - **Open** + **Request**: Anyone can initiate a request to join the circle, Moderator can add Members + + - **Open** + **Invite**: Everyone can enter, Moderators must send invitation. + + - **Open** + **Invite** + **Request**: Everyone send a request, Moderator must send Invitation. + + - **Request** + **Friend**: No one can join the Circle, but all members can request a moderator to accept + new members. + + - **Friend** + **Invite**: No one can join the Circle, but all members can add new member. An invitation + will be generated. + + - **Friend** + **Invite** + **Request**: No one can join the Circle, but all members can request a moderator + to accept new Member. An invitation will be generated. + + +Personal Circles +^^^^^^^^^^^^^^^^ + +A Personal Circle is a Circle that can only be managed, **and used**, by the Owner of the Circle. No one +else, beside its creator, will have access to the Circle or be able to share any files and content to it. + +There is no possible configuration of a Personal Circle. + + +System Circles +^^^^^^^^^^^^^^ + + +- **Single** (1): Circle that only contains a single Member. This circle have no configuration option available + and it is only managed by the Circles App itself. It is used to generate a SingleId to identify a Member + as FederatedUser. + (cf. `FederatedUser `) + [TODO: generate a link to the page related to circles developer manual] + +The Circles Apps provide a large variety of tools to Nextcloud Apps to generate and manage a group of users. +With those tools comes also more types of Circles that are not directly available to users: + + - **No Owner** (512): Circle have no owner (Not yet implemented) + + - **Hidden** (1024): The generated Circle is not displayed in the listing of existing Circles, even to the + Owner of the Circle. However, the Circle will appears in the list of available entities when sharing a + files or any content. + + - **Backend** (2048): Completely hidden, Circle will not appears in any 'Shares to' dropdown. + + - **Root** (4096): Circle cannot be a member of another Circle. + + + + +.. _app_overview_level_members: + +Members Level +^^^^^^^^^^^^^ + +- **Member**: Lowest Level, user is a Member of the Circle. +- **Moderator**: Can `add`, `invite`, `accept`, `reject`, `remove` Members from/to the Circle. +- **Admin**: Same as **Moderator**, can edit Circle's configuration and also give or revoke Moderator + rights to a Member. +- **Owner**: Same as **Admin**, can edit any Level and have the ability to destroy the Circle. Only one + Owner per Circle. + +.. note:: Ownership can be transferred to any other member of the Circle. Current Owner will end up Admin + of the Circle at the end of the procedure. + + When a Nextcloud account is destroyed, and the user had the status of Owner in one of multiple Circle, + a new Owner will be put in place for each Circle. The selection of the new Owner will be based on the + Level of the Member (Admin first, Moderator if no Admin, Member of no Moderator), and the longevity of + its membership (Older member first) + + + +.. _app_overview_type_members: + +Types of members +^^^^^^^^^^^^^^^^ + +Beside others **Nextcloud Users**, a Member of the Circle can also come from different sources: + +- **Mail Address**: When adding a mail address as Member of a Circle, any file shared to this Member will + generate a link and send it in a mail to the recipient. + +- **Contact**: Working like a **Mail Address**. The Id of the contact is stored, meaning that changing the mail + address of a contact will be taken into account when a mail needs to be send to this Member. + +- **Circle**: A Circle can be a Member of an other Circle. Every Members of the Circle-as-Member will have the + same Level as the Circle-as-Member itself. + + + +SingleID, CircleID & MemberID +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In this documentation, we will often refer to 3 different of unique Ids, all generated the same way: a case +sensitive 15 character alphanumeric string. + +- **SingleID** represents a single user, based on the account name, its type and eventually its source. +- **CircleID** represents a Circle, as a group of members. + +**SingleID** and **CircleID** are mainly used to identify the entity set as the recipient of a share. + +- **MemberID** identify a specific Member of a Circle. This ID is only used to manage/remove the rights of + a member inside a Circle + diff --git a/admin_manual/groupware/circles/configuration.rst b/admin_manual/groupware/circles/configuration.rst new file mode 100644 index 000000000..55e551b15 --- /dev/null +++ b/admin_manual/groupware/circles/configuration.rst @@ -0,0 +1,80 @@ +============= +Configuration +============= + + + + +Async process +^^^^^^^^^^^^^ + +.. note:: + In this paragraph, we will call `Process` the execution of a request from the front-end to the back-end + until the back-end returns a result to the front-end and close the request. + We will call `Thread` a process initialized by a `Process` to run a background task. + +When managing a Circle some operation can be too heavy to be handle by the `Process` and takes multiple +seconds, affecting the User Experience with an unresponsive interface during this delay. + +As an example, when adding a new Member to a Circle, the back-end will also: + - manage new memberships rights about this new Member, + - if the member is a contact or a mail address, retrieve a list of all shared file to the current Circle + to generate a mail and send it. + +Unfortunately, PHP does not allow to create multiple `Thread`. +The solution we are providing is done by: + - opening a local request to Nextcloud, this will generate a `Thread` at the level of the httpd, + - manually closing the local request, freeing the `Process` while keeping the `Thread` running. + +.. note:: To keep the code clean and the whole procedure consistent between a request from the front-end + and a command run using the ``occ`` command. We create a new request instead of manually closing the initial + request from the front-end. + + +By default, the local request is done on the address of Nextcloud configured in `config/config.php`: +`overwrite.cli.url`. While this is working fine on most of the setup of Nextcloud, some issues can be found +when using a Proxy. + +[TODO] WRITE DOCUMENTATION ON HOW TO CONFIGURE FORCE_NC_BASE AND TEST IT LOCALLY USING THE OCC COMMAND + + +Types of Circles +^^^^^^^^^^^^^^^^ + +As we already saw in :doc:`app_overview`, different types of members can be added to a Circle. You can +enable/disable those types from the `Admin Settings Page`. + +[TODO] SCREENSHOT OF THE ADMIN SETTINGS PAGE + +If disabled, an Admin can re-enable types for a specific Circle from the `Configuration Panel` of the Circle. + +[TODO] SCREENSHOT OF THE CONFIGURATION PANEL + + + + + +Size of Circles +^^^^^^^^^^^^^^^ + +You can set a global limit to the size of a Circle from the `Admin Settings Page` + +[TODO] SCREENSHOT OF THE ADMIN SETTINGS PAGE + +This limit can be bypassed by an admin for a specific Circle using the `Configuration Panel` of the Circle. + +[TODO] SCREENSHOT OF THE CONFIGURATION PANEL + + + +Sources of members +^^^^^^^^^^^^^^^^^^ + +As we already saw in :doc:`app_overview`, different sources of members can be added to a Circle. You can +enable/disable those sources from the `Admin Settings Page`. + +[TODO] SCREENSHOT OF THE ADMIN SETTINGS PAGE + +If disabled, an Admin can re-enable types for a specific Circle from the `Configuration Panel` of the Circle. + +[TODO] SCREENSHOT OF THE CONFIGURATION PANEL diff --git a/admin_manual/groupware/circles/federated_advanced.rst b/admin_manual/groupware/circles/federated_advanced.rst new file mode 100644 index 000000000..aeaa1e0a9 --- /dev/null +++ b/admin_manual/groupware/circles/federated_advanced.rst @@ -0,0 +1,9 @@ +.. _federated_advanced: + +============================ +Federated Circles (Advanced) +============================ + + + +dd diff --git a/admin_manual/groupware/circles/federated_overview.rst b/admin_manual/groupware/circles/federated_overview.rst new file mode 100644 index 000000000..ceccd970e --- /dev/null +++ b/admin_manual/groupware/circles/federated_overview.rst @@ -0,0 +1,141 @@ +================================ +Global Scale & Federated Circles +================================ + +We saw that the purpose of the Circles App is to generate groups of Nextcloud users. Now, we will have a +look to another feature of the App, which is to regroups users from multiple instances of Nextcloud. + +This feature is called Federated Circles, it can be used with: + +- remote instances, hosted in an other place by an other administrator, +- local instances, in a Global Scale setup. + +Regardless of the way you are using this feature, we will use the same name to describe any other instances +of Nextcloud: Remote Instance + + + + +.. _federated_overview_trust_level: + +Trust Level +^^^^^^^^^^^ + + +As an administrator you can add and remove any Remote Instance, and assign a Trust Level to each one of them. +This is a list of those levels, in order of decreasing credibility: + +- **GlobalScale**: Information related to all Circles from your instance and their Members will be shared to the + Remote Instance. While this should only be used in a Global Scale environement, there is no limitation to + use this with any Remote Instance of your choice. Please note that when using the GlobalSiteSelector App + and a Lookup Server, the Remote Instance of your Global Scale setup will be added automatically. + +- **Trusted**: Only information about Circles configured as 'Federated', and their Members, will be shared to + the Remote Instance. + +- **External**: like **Trusted**, but for the Remote Instance to get access to the list of its Members, the local + Circle must: + + - contains a member that belongs to the Remote Instance, + - one Circle from the Remote Instance is a Member of the local Circle. + +- **Passive**: like **External**, but only Members that belongs to the Remote Instance are shown to the Remote + Instance. + + +Instance Identification +^^^^^^^^^^^^^^^^^^^^^^^ + +While the exchange of data about Federated Circles between 2 instances of Nextcloud is done using its +own protocol, the discovery of information relative to the configuration of each instances is done using the +**Webfinger** protocol:: + + + $ curl -X GET https://cloud.example.net/.well-known/webfinger?resource=http://nextcloud.com/ + { + "subject": "http://nextcloud.com/", + "links": [ + { + "rel": "https://apps.nextcloud.com/apps/circles", + "type": "application/json", + "href": "https://cloud.example.net/apps/circles/", + "properties": { + "app": "circles", + "name": "Circles", + "version": "22.0.0", + "api": 1 + } + } + ] + } + + +The URL defined in ``href`` will be used to obtain more details on the endpoints used to exchanging data with this Remote Instance:: + + $ curl -X GET https://cloud.example.net/apps/circles/ -H "Accept: application/json" + { + "uid": "5ca2dfd7fc0a29296d", + "event": "https://cloud.example.net/apps/circles/event/", + "incoming": "https://cloud.example.net/apps/circles/incoming/", + "test": "https://cloud.example.net/apps/circles/test/", + "circles": "https://cloud.example.net/apps/circles/circles/", + "circle": "https://cloud.example.net/apps/circles/circle/{circleId}/", + "members": "https://cloud.example.net/apps/circles/members/{circleId}/", + "member": "https://cloud.example.net/apps/circles/member/{type}/{userId}/", + "id": "https://cloud.example.net/apps/circles/", + "publicKey": { + "id": "https://cloud.example.net/apps/circles/#main-key", + "owner": "https://cloud.example.net/apps/circles/", + "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA7RZSMjCZO0BTo0ZYHhUO\nhIxs3ku94ZcR1GyhHKaVX2m+ZlDjea+q+UNiLHcUE4XM+wEIQPxIwxUhlBybOd7o\nfcbA1t0LQgX+ENeZcqQd2ZDQp0JA6m1V/GxHGb1l9izJS2zZuGPKmgbZli+G7rFt\n/1K8mo+91FYYrczRC7dfz0SWz1RyXw3Xes5uROgSBVsoEPFcFEaJyXFTc7PmoEiD\nTpgW48NsPjAgaCfkE8Sp+VEOe0z3Vb9/ZaxNRN7UK2o53HrA24DvCdFPGZYD/VPo\nesIgEB0K4FPHjCeB4jND6gOCJSVjMPY2QyrbqZm3qh/QspQLjBXlJs4bWZT8PUco\nHwIDAQAB\n-----END PUBLIC KEY-----\n" + } + } + + +Alike with Fediverse, the authentication of the sender is done using the PublicKey available to the public +as the sender uses its PrivateKey to sign any request. + +However, a security check have been added to also confirm the identity of the recipient. The request can +implement a string that will be signed by the Remote Instance to prove the ownership of the right PrivateKey +using the PublicKey, the original string and the value of ``auth-signed``:: + + $ curl -X GET https://cloud.example.net/apps/circles/?auth=qwertyuiop -H "Accept: application/json" + { + "uid": "5ca2dfd7fc0a29296d", + [...] + "auth-signed": "sha256:dCtIfNBvfO1voLdvWAHPVLVNE+lHwuKFSJMCvCGELEAUf05+hemusjjXQ8Bk2NzpXP0LRN2czJWDazXHtb0ytflGigl8CIObxtkjKWiGcD3YamBZL4apSbVhMcP2W0RBpgpfn0REv/LNuakAIivdckFmhveqbAXbs3oMwwHy4pYt+S3nKkjMi/JGt/duuJpjiNBcShei3b9vomZ+0j9VhU6Srr0tpLYq12AmVRQ2vVD3C/D4PwuN1zOM6b6ao7HrYOKU+Ij+d1lVgGmd0nKc7ZJZYndOgr0naBhkRlfu2BDbQoFK/ue7OKACexJLgti9sHbA2etoC1eNy7NJetCSHQ==", + "id": "https://documentation.local/index.php/apps/circles/", + "publicKey": { + "id": "https://documentation.local/index.php/apps/circles/#main-key", + "owner": "https://documentation.local/index.php/apps/circles/", + [...] + } + } + + + +``uid`` is generated by hashing the PublicKey and will be used to identify this Remote Instance. + +.. note:: The conclusion of this technical aside, is that even if the same Nextcloud is running on the same domain + name, loosing your PrivateKey will revoke your rights on any other Remote Instance. + + This work in both side: + if a Remote Instance loose its domain name, no data from your Nextcloud will be exchanged with it anymore. + + +Configuration +^^^^^^^^^^^^^ + +While the ``webfinger`` helps a lot to automatize discovery, the URL returned in ``href`` still need to be +configured. + +By default, the Circles App will use URL defined in ``config/config.php``: ``overwrite.cli.url``. This is +efficient in most of installation of Nextcloud. However, it might not works if the Nextcloud is behind a Proxy. + +[TODO] DEFINE PROCESS TO CONFIGURE AND TEST + + + + + + + diff --git a/admin_manual/groupware/circles/index.rst b/admin_manual/groupware/circles/index.rst new file mode 100644 index 000000000..d8b586366 --- /dev/null +++ b/admin_manual/groupware/circles/index.rst @@ -0,0 +1,16 @@ +============== +Circles +============== + + +Circles is a Nextcloud App that allow Nextcloud users to generate their own grouping of users and contacts. + + +.. toctree:: + :maxdepth: 2 + + app_overview + configuration + federated_overview + occ_commands + federated_advanced diff --git a/admin_manual/groupware/circles/occ_commands.rst b/admin_manual/groupware/circles/occ_commands.rst new file mode 100644 index 000000000..b9c66a2da --- /dev/null +++ b/admin_manual/groupware/circles/occ_commands.rst @@ -0,0 +1,539 @@ +============ +occ commands +============ + + +Using **--initiator** +^^^^^^^^^^^^^^^^^^^^^ + +While each command used to manage the Circles of your Nextcloud comes with its own list of arguments and +options, one option is availble to almost all of them: **--initiator** + +This option allows you to run the command from the point of view of another user. This is useful if you +want to verify if a user have access to a Circle and its Members, or to a specific operation within a +Circle (add.remove a member, edit its configuration) + +The syntax is ``--initiator ``, with userId the account of the user you need to emulate. + + +Commands related to Circles +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +occ circles:manage:create +------------------------- + +The first command you need to know; how to create a new Circle! +The command is followed by the local Nextcloud user account that will be the owner of the Circle, and the +name of the Circle itself:: + + $ occ circles:manage:create cult "Each one teach one" + { + "reading": { + "message": "Circle '%s' have been created", + "params": { + "circleName": "Each one teach one" + }, + "fail": false, + "translated": "Circle 'Each one teach one' have been created" + }, + "data": { + "circle": { + "id": "MKGmspLrYoXCx81", + "name": "Each one teach one", + "owner": { + "id": "KImB12zJpFW4Eff", + "circle_id": "MKGmspLrYoXCx81", + "single_id": "NkdMRgx64n2qAWp", + "user_id": "cult", + "user_type": 1, + "instance": "cloud.example.net", + "level": 9, + "status": "Member" + }, + "initiator": { + "id": "KImB12zJpFW4Eff", + "circle_id": "MKGmspLrYoXCx81", + "single_id": "NkdMRgx64n2qAWp", + "user_id": "cult", + "user_type": 1, + "instance": "cloud.example.net", + "level": 9, + "status": "Member" + } + } + } + } + + + + + +occ circles:manage:list +----------------------- + +Once a first Circle is created, you can display the list of available Circles on your instance of Nextcloud:: + + $ occ circles:manage:list + +-----------------+--------------------+------+-------+----------+-------+-------------+ + | ID | Name | Type | Owner | Instance | Limit | Description | + +-----------------+--------------------+------+-------+----------+-------+-------------+ + | MKGmspLrYoXCx81 | Each one teach one | [] | cult | | -1 | | + +-----------------+--------------------+------+-------+----------+-------+-------------+ + +.. note :: The ID of the Circle (**MKGmspLrYoXCx81** in this example) is unique and will be used in other `occ commands` + in this documentation when referring to this Circle. + +By default, the Circle is not marked as VISIBLE. Meaning that while you can see it when running the occ +command, it should not be available to a user that is not a member of the Circle. + +Let's try this, using the ``--initiator`` option:: + + $ occ circles:manage:list --initiator user1 + +----+------+------+-------+----------+-------+-------------+ + | ID | Name | Type | Owner | Instance | Limit | Description | + +----+------+------+-------+----------+-------+-------------+ + +occ circles:manage:config +------------------------- + +This command will helps you to change the :ref:`types of a Circle `. + +As can be seen in the list above, the Circle have been created with its default configuration: No one can +join it, but new member can be added by a Moderator. +We will edit this configuration so that: +- anyone knowing the name of the Circle (or its ID) can send a Request to join the Circle, +- adding a member will generate an Invitation that needs to be approved by the recipient. + +The command is followed by ID of the Circle, and the list of configuration we want to enable:: + + $ occ circles:manage:config MKGmspLrYoXCx81 OPEN JOINREQUEST INVITE + { + "reading": { + "message": "Configuration have been updated", + "params": [], + "fail": false, + "translated": "Configuration have been updated" + }, + "data": { + "circle": { + "id": "MKGmspLrYoXCx81", + "name": "Each one teach one", + "creation": 1613828553, + "owner": { + "id": "KImB12zJpFW4Eff", + "circle_id": "MKGmspLrYoXCx81", + "single_id": "NkdMRgx64n2qAWp", + "user_id": "cult", + "user_type": 1, + "instance": "cloud.example.net", + "level": 9, + "status": "Member", + "cached_update": 1613828553, + "joined": 1613828553 + }, + "initiator": { + "id": "KImB12zJpFW4Eff", + "circle_id": "MKGmspLrYoXCx81", + "single_id": "NkdMRgx64n2qAWp", + "user_id": "cult", + "user_type": 1, + "instance": "cloud.example.net", + "level": 9, + "status": "Member", + "cached_update": 1613828553, + "joined": 1613828553 + } + } + } + } + + +If no type is specified during the execution of the command, the current configuration will be returned:: + + $ occ circles:manage:config MKGmspLrYoXCx81 + [ + "Open", + "Invite", + "Join Request" + ] + +We will now change the configuration of a Circle that `that generate an Invitation when a new member is +directly added by a moderator, and open to everyone that knows the name of the Circle and is willing to +send a Request` to a `Circle that is freely accessible and visible to everyone`:: + + $ occ circles:manage:config MKGmspLrYoXCx81 _INVITE _JOINREQUEST VISIBLE + { + "reading": { + "message": "Configuration have been updated", + "params": [], + "fail": false, + "translated": "Configuration have been updated" + }, + "data": { + "circle": { + "id": "MKGmspLrYoXCx81", + "name": "Each one teach one", + "config": 24, + "creation": 1613828553, + "owner": { + [...] + }, + "initiator": { + [...] + } + } + } + } + + +.. note:: You can set a list of multiple types to add, or to remove by using an underscore as a first character. + This is the list of available types that can be used with this command: + + - VISIBLE + - OPEN + - INVITE + - JOINREQUEST + - FRIENDS + - PASSWORDPROTECTED + - FEDERATED + +.. note:: Some important information about the FEDERATED type: + + - A Federated Circles cannot be a member of another Circle, + - When a Circle is a member of another Circle and is set to FEDERATED, all its memberships will be definitively reset, + - When removing the type FEDERATED to a Federated Circle, All remote members are definitively removed from the Circle. + + +Now that the Circle is set to be VISIBLE, we can try again to use the ``--inititator`` option to emulate +the point of view of a non-member:: + + $ occ circles:manage:list --initiator user1 + +-----------------+--------------------+-----------+-------+----------+-------+-------------+ + | ID | Name | Type | Owner | Instance | Limit | Description | + +-----------------+--------------------+-----------+-------+----------+-------+-------------+ + | MKGmspLrYoXCx81 | Each one teach one | ["V","O"] | cult | | -1 | | + +-----------------+--------------------+-----------+-------+----------+-------+-------------+ + +As it can be seen, the Circle is now available in the listing even for non-member. + + +occ circles:manage:details +-------------------------- + +[TODO: DOCUMENTATION ABOUT THIS COMMAND] + +Commands related to Members +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + +occ circles:members:add +----------------------- + +Let's add a member to our Circle with this first command related to Members management! + +This command require the ID of the Circle and the username of the future member:: + + $ occ circles:members:add MKGmspLrYoXCx81 user1 + { + "reading": { + "message": "User '%s' have been added to Circle", + "params": { + "userId": "user1" + }, + "fail": false, + "translated": "User 'user1' have been added to Circle" + }, + "data": { + "member": { + "id": "af186f8eb7844e9", + "circle_id": "MKGmspLrYoXCx81", + "single_id": "rJveWMecFCxR6dh", + "user_id": "user1", + "user_type": 1, + "instance": "cloud.example.net", + "level": 1, + "status": "Member" + } + } + } + + +.. note :: The :ref:`type of the Member ` can be specified using the + option ``--type``:: + $ occ circles:members:add MKGmspLrYoXCx81 test@example.net --type mail + + List of available types: + + - USER + - CIRCLE + - SINGLE + - MAIL + - CONTACT + + +.. note :: The SingleID that locally identify the account, the type of account and the instance of the account + can be used as a username in the command:: + $ occ circles:members:add MKGmspLrYoXCx81 rJveWMecFCxR6dh + + While it is better to specify the type with ``--type`` please note that, if the option is not used, the App + will first check if the username is a local Nextcloud userId, then check if the username is a valid SingleId + + + +occ circles:members:list +------------------------ + +This command will returns the list of current members to a circle:: + + $ occ circles:members:list MKGmspLrYoXCx81 + +-----------------+-----------------+------+----------+----------+--------+ + | ID | Single ID | Type | Username | Instance | Level | + +-----------------+-----------------+------+----------+----------+--------+ + | KImB12zJpFW4Eff | NkdMRgx64n2qAWp | user | cult | | Owner | + | af186f8eb7844e9 | rJveWMecFCxR6dh | user | user1 | | Member | + +-----------------+-----------------+------+----------+----------+--------+ + +The column ``ID`` shows the **MemberId** for each member. They will be used to manage members' level or to +remove a member of the Circle. + + +We saw previously that a Circle can be a member of another Circle. +In case you want a resume of all the members with access to content shared to a Circle, you +can have a nice display of indirect access using the ``--tree`` option:: + + $ ./occ circles:members:list MKGmspLrYoXCx81 --tree + Name: Each one teach one + Owner: cult@cloud.example.net + Config: Visible, Open + + MKGmspLrYoXCx81 + │ + ├── cult (Owner) + ├── 9V5NUTLdeBtXgMO (Member) Name: This is a test + │ Owner: user2 Config: Visible, Open, Password Protected + │ │ + │ ├── user2 (Owner) + │ ├── VCGzH5x9LCalArV (Member) Name: Admins + │ │ Owner: cult@cloud.example.net + │ │ │ + │ │ ├── cult (Owner) + │ │ ├── admin1 (Member) + │ │ ├── admin2 (Member) + │ │ └── admin3 (Member) + │ ├── user4 (Member) + │ ├── user8 (Member) + │ └── user9 (Member) + ├── admin1 (Member) + ├── gh6AcMgmUGB5cjh (Member) Name: Another Circle + │ Owner: user2 Config: Open, Join Request + │ │ + │ ├── user2 (Owner) + │ ├── user6 (Member) + │ ├── user7 (Member) + │ └── user8 (Member) + ├── user1 (Member) + ├── user3 (Member) + ├── user4 (Member) + └── user5 (Member) + +.. note :: The example above have been generated by temporary adding more members to more circles, and + adding circles as members. This is not the current state of the Circle **MKGmspLrYoXCx81** we are + using as an example since the beginning of this documentation. + + +occ circles:members:level +------------------------- + +To change the :ref:`level for a member `, the command must be followed by the +**MemberId** and the desired level to assign to the member:: + + + $ ./occ circles:members:level af186f8eb7844e9 moderator + { + "reading": { + "message": "Level for member '%s' have been updated", + "params": [ + "userId": "user1" + ], + "fail": false, + "translated": "Level for member 'user1' have been updated" + }, + "data": { + "member": { + "id": "af186f8eb7844e9", + "circle_id": "MKGmspLrYoXCx81", + "single_id": "rJveWMecFCxR6dh", + "user_id": "user1", + "user_type": 1, + "instance": "cloud.example.net", + "level": 4, + "status": "Member", + "circle": { + "id": "MKGmspLrYoXCx81", + "name": "Each one teach one", + "config": 24, + "creation": 1613828553, + "owner": { + [...] + }, + "initiator": { + [...] + } + } + } + } + } + + +Now that ``user1`` is a moderator of the Circle, we will emulate this account to add a new member:: + + $ ./occ circles:members:add MKGmspLrYoXCx81 user2 --initiator user1 + { + "reading": { + "message": "User '%s' have been added to Circle", + "params": { + "userId": "user2" + }, + "fail": false, + "translated": "User 'user2' have been added to Circle" + }, + "data": { + "member": { + "id": "d6a99b673f314e1", + "circle_id": "MKGmspLrYoXCx81", + "single_id": "JNGDIDFgkSbQAYE", + "user_id": "user2", + "user_type": 1, + "instance": "documentation.local", + "level": 1, + "status": "Member" + } + } + } + +.. note :: This is only doable because ``user1`` is a moderator, if we emulate the account of ``user2`` + (which is now a member) to add another member, the command would returns an error message '`Insufficient + rights`' + + +occ circles:members:remove +-------------------------- + +This is the current state of our Circle:: + + $ occ circles:members:list MKGmspLrYoXCx81 + +-----------------+-----------------+------+----------+----------+-----------+ + | ID | Single ID | Type | Username | Instance | Level | + +-----------------+-----------------+------+----------+----------+-----------+ + | KImB12zJpFW4Eff | NkdMRgx64n2qAWp | user | cult | | Owner | + | af186f8eb7844e9 | rJveWMecFCxR6dh | user | user1 | | Moderator | + | d6a99b673f314e1 | JNGDIDFgkSbQAYE | user | user2 | | Member | + +-----------------+-----------------+------+----------+----------+-----------+ + +To remove the member ``user2``, we will use its **MemberId**:: + + $ ./occ circles:members:remove d6a99b673f314e1 + { + "reading": { + "message": "Member '%s' have been removed", + "params": [ + 'userId' => 'user2' + ], + "fail": false, + "translated": "Member 'user2' have been removed" + }, + "data": [] + } + + +.. note :: While this is not used in our example, we could have use `--initiator` to emulate the account + of a Moderator like ``user1`` for this command + + +occ circles:memberships +----------------------- + +It is always nice to have a resume of all memberships of a user: who belongs to which Circle ? +Even more when you start to have a lot of Circles, some of which members of other Circles:: + + $ ./occ circles:memberships user8 + Id: user8 + Instance: cloud.example.net + Type: user + SingleId: Wtu4WVrYjLpiOzW + + Memberships: + (database not updated) + - 9V5NUTLdeBtXgMO (Member) + - MKGmspLrYoXCx81 (Member) + - gh6AcMgmUGB5cjh (Member) + + Wtu4WVrYjLpiOzW + │ + ├── 9V5NUTLdeBtXgMO (This is a test) Level: Member + │ Owner: user2 Config: Visible, Open, Password Protected + │ │ + │ └── MKGmspLrYoXCx81 (Each one teach one) Level: Member + │ Owner: cult Config: Visible, Open + │ + └── gh6AcMgmUGB5cjh (Another Circle) Level: Member + Owner: user2 Config: Open, Join Request + │ + └── MKGmspLrYoXCx81 (Each one teach one) Level: Member + Owner: cult Config: Visible, Open + +.. note :: The example above have been generated by temporary adding more members to more circles, and + adding circles as members. This is not the current state of the Circle **MKGmspLrYoXCx81** we are + using as an example since the beginning of this documentation. + + +Commands related to Federated Circles +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +occ circles:remote +------------------ + +Run this command to add a Remote Instance that can be used later to add member belonging to this Remote +Instance to a Federated Circle. + +The command can be completed by the option ``--type`` to assign a :ref:`Trust Level ` +to the Remote Instance:: + + $ ./occ circles:remote other.example.net --type PASSIVE + [...] + + The remote instance other.example.net looks good. + Would you like to identify this remote instance as 'Passive' ? (y/N) + + +.. note :: The command will check the validity of the identity of the Remote Instance. + Your terminal will be flooded with (a lot of) data that can be used to debug in case of problem. + At the end, you should only needs to confirm that you really wants to add the Remote Instance to your database. + + You can find more details about this in our :ref:`Advanced documentation about Federated Circles `. + +.. note :: List of available types: + + - UNKNOWN + - PASSIVE + - EXTERNAL + - TRUSTED + - GLOBALSCALE + + +occ circles:manage:sync +----------------------- + +[TODO: DOCUMENTATION ABOUT THE SYNC COMMAND] + + +Miscellaneous +^^^^^^^^^^^^^ + +occ circles:clean +----------------- + +[TODO: DOCUMENTATION ABOUT THE CLEAN COMMAND] + + diff --git a/admin_manual/groupware/index.rst b/admin_manual/groupware/index.rst index 1670736e1..757da970f 100644 --- a/admin_manual/groupware/index.rst +++ b/admin_manual/groupware/index.rst @@ -6,4 +6,5 @@ Groupware .. toctree:: :maxdepth: 2 - calendar \ No newline at end of file + calendar + circles/index diff --git a/developer_manual/circles/federated_event.rst b/developer_manual/circles/federated_event.rst new file mode 100644 index 000000000..ba555b604 --- /dev/null +++ b/developer_manual/circles/federated_event.rst @@ -0,0 +1,7 @@ +============== +FederatedEvent +============== + + + + diff --git a/developer_manual/circles/federated_overview.rst b/developer_manual/circles/federated_overview.rst new file mode 100644 index 000000000..ca92463c1 --- /dev/null +++ b/developer_manual/circles/federated_overview.rst @@ -0,0 +1,7 @@ +================= +Federated Circles +================= + + + + diff --git a/developer_manual/circles/ifederated_item.rst b/developer_manual/circles/ifederated_item.rst new file mode 100644 index 000000000..f72c2c979 --- /dev/null +++ b/developer_manual/circles/ifederated_item.rst @@ -0,0 +1,16 @@ +============== +IFederatedItem +============== + + + + +IFederatedItem.php +IFederatedItemAsync.php +IFederatedItemCircleCheckNotRequired.php +IFederatedItemInitiatorCheckNotRequired.php +IFederatedItemLocalOnly.php +IFederatedItemMemberCheckNotRequired.php +IFederatedItemMemberEmpty.php +IFederatedItemMemberOptional.php +IFederatedItemMemberRequired.php diff --git a/developer_manual/circles/index.rst b/developer_manual/circles/index.rst new file mode 100644 index 000000000..189310c2b --- /dev/null +++ b/developer_manual/circles/index.rst @@ -0,0 +1,14 @@ +======= +Circles +======= + + +Descriptive document about the Circles App, and how any app can be compatible with its Federated feature. + + +.. toctree:: + :maxdepth: 2 + + federated_overview + federated_event + ifederated_item