admin manual about Circles 22

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 <https://docs.nextcloud.com/server/latest/go.php?to=developer-manual>`)
+  [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
+

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

admin_manual/groupware/circles/federated_advanced.rst

@@ -0,0 +1,9 @@
+.. _federated_advanced:
+
+============================
+Federated Circles (Advanced)
+============================
+
+
+
+dd

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
+
+
+
+
+
+
+

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

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 <userId>``, 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 <app_overview_type_circles>`.
+
+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 <app_overview_type_members>` 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 <app_overview_level_members>`, 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 <federated_overview_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 <federated_advanced>`.
+
+.. 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]
+
+

admin_manual/groupware/index.rst

@@ -6,4 +6,5 @@ Groupware
 .. toctree::
     :maxdepth: 2
 
-    calendar
+    calendar
+    circles/index

developer_manual/circles/federated_event.rst

@@ -0,0 +1,7 @@
+==============
+FederatedEvent
+==============
+
+
+
+

developer_manual/circles/federated_overview.rst

@@ -0,0 +1,7 @@
+=================
+Federated Circles
+=================
+
+
+
+

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

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