View source for Users - Groups

==Related sub-modules==
<specification module="USERS" submodule="USERS"/>, <specification module="USERS" submodule="PRODUCTS"/>, <specification module="SYSTEM" submodule="CONFIGURATIONS"/>

==Description==
Groups are used to organize all users in Cyclos. Users can be organized in groups and groups can be organized in groupsets. [[Users_-_Products|Products]] can be added to a member group and in this way the admin can control which permissions the members of this group have. Also a [[System_-_Configurations|configuration]] can be assigned to a group, determining how Cyclos looks, feels and behaves for member from this group. The permissions of the admin groups can be set in the group itself.

==Business rules==
* Every user in Cyclos must belong to a certain group. 
* Groups can belong to a groupset, but this is not obliged.
* There are two types of groups: member and administrator groups (the two special administrator groups are explained below).
* Only one configuration can be assigned to a group.
* To user groups (multiple) broker and / or member products can be added making them a broker and / or member. 
* The administrator's permissions can be set in the group directly. Technically only one product is assigned to administrators and this product is unique for this group.
* A group's groupset can only be unassigned from the group if the group set has no products directly connected to it.
* Rules for group change are described on the [[Users#Group_change | user's page]].


'''Network Administrator''' 
* When a new network is created, this group will automatically be created for this network. This group always has the permissions listed below. In this way there is always a group that can configure the system and the control of the network system cannot be lost by deleting products.
** <permission id="SYSTEM_CONFIGURATION_VIEW"/>
** <permission id="SYSTEM_CONFIGURATION_MANAGE"/>
** <permission id="ACCOUNT_CONFIGURATION_VIEW"/>
** <permission id="ACCOUNT_CONFIGURATION_MANAGE"/>
** <permission id="USER_CONFIGURATION_VIEW"/>
** <permission id="USER_CONFIGURATION_MANAGE"/>


'''Global Administrator''' 
* This is also a build-in group for Cyclos. This group has the permission to create new networks. When switched between a network this group will inherit the permissions from the network administrator group.


'''Disabling groups'''
* Groups have a property '''"enabled"''', which can be set to false or true, when set to true the group is enabled, when set to false the group is disabled. 
* In most cases a group is disabled, because you want to hide it and cannot delete it.
* Groups can only be disabled if not containing any members.
* Disabled groups are never shown in the list, except when explicitly requested via the search options of a group filter.
* When a group is disabled, the following actions are taken:
** The group is removed from the accessibleBasicGroups property of any user group. It is kept in the accessibleBasicGroups property of admin groups, because admins must be able to view this group.
** The group is removed from any configuration, that is:
*** Remove it from possibleInitialGroups
*** Remove it from visibleGroups
** The group is removed from possibleInitialGroups of BrokerProducts.


'''Deleting groups'''
* Only groups can be deleted that do not have any members.
* Only groups can be deleted that never had a member in it (when the group history log is empty).


'''Deleting groupsets'''
* Groupsets cannot be disabled, they don't have an enabled property like groups do. 
* Groupsets can only be deleted when it has not groups under it anymore: 
** This means that an admin who wishes to delete a groupset, must first go by all the groups in the groupset to set the groupset property of these groups to some other groupset, or to null. 
** In this way no members can be deleted.

==Notifications==
N/a.

==Page: Groups list==

===Security===
'''Roles:'''
* Admin.

'''View permission:'''
* <permission id="USER_CONFIGURATION_VIEW"/>

'''Other permissions:'''
* <permission id="USER_CONFIGURATION_MANAGE"/>

===Page sections===

====Search page (filters)====

{| border="1" cellpadding="3" cellspacing="0"
|-
| bgcolor="#FFFF8F" width="300pt" | '''Fields''' 
| bgcolor="#FFFF8F" width="200pt" | '''Type''' 
| bgcolor="#FFFF8F" width="900pt"| '''Rules''' 

|- 
| Type
| Single selection
| Used to filter the groups by their user types. Options are:
* All;
* Group set;
* Administrator group;
* User group.

|- 
| Group name
| Text
| Allows the admin to search groups by there name.

|- 
| Group set
| Single selection
| Used to filter the groups by their group sets. 
* Should be hidden if type is "Administrator" or "Groupset".
* Shows all group sets and the default value "All".

|- 
| Network list
| Single select (same as switcher)
| Global admin groups mode only

|- 
| Show disabled groups
| Boolean
| When this checkbox is selected also the disabled groups are shown in the list. 
* Not selected by default.

|-
| New
| Multi action button
| Opens a details page for inserting a new group.
* Has the options for group type: Administrator and User. 
* Aligned to the left.

|-
| Search
| Action button
| Executes the search, shows all groups with the selected roles. 
* All groups are sorted by type (admins first), then alphabetically.
* Aligned to the right.
|}
<br>

====Search result (list *)====
''* When disabled groups are selected to be shown in the search filter, the disabled groups are shown striped trough in the search results list.''

{| border="1" cellpadding="3" cellspacing="0"
|-
| bgcolor="#FFFF8F" width="300pt" | '''Fields''' 
| bgcolor="#FFFF8F" width="200pt" | '''Type''' 
| bgcolor="#FFFF8F" width="900pt"| '''Rules''' 

|-
| Group
| Text (read only)
| The name of the group. 
* The name is 'striped through' if the group is disabled.
* The name has an arrow icon displayed before it when the group belongs to a groupset which is displayed above it. If the groupset to which it belongs is NOT displayed, the arrow icon is NOT shown. 

|-
| Type
| Text (read only)
| The group type (adminstrator or user).

|- 
| Remove
| Icon
| Removes the group (see business rules): 
* The group must have no members, otherwise an error is displayed;
* If the group ever had members it will be disabled (set enabled to false);
* If the group never had members it will be physically deleted;
* Groupsets can be deleted if it has no groups assigned to it.
|}
<br>

==Page: Group details==

'''Tabs:'''
* [[#Details (tab)]]
* [[#Products (tab *)]]
* [[#Configuration (tab)]]

===Security===
'''Roles:'''
* Admin.

'''View permission:'''
* <permission id="USER_CONFIGURATION_VIEW"/>

'''Other permissions:'''
* <permission id="USER_CONFIGURATION_MANAGE"/>
* <permission id="PRODUCTS_ASSIGN_TO_USER"/> (to assign the products selected in the admins product to the individual user).

===Details (tab)===

====Details page====

{| border="1" cellpadding="3" cellspacing="0"
|-
| bgcolor="#FFFF8F" width="300pt" | '''Fields''' 
| bgcolor="#FFFF8F" width="200pt" | '''Type''' 
| bgcolor="#FFFF8F" width="900pt"| '''Rules''' 

|-
| Type
| Text (read only)
| 
* "User group" or "Administrator group". 
* Defined at group creation (multi action button) and can thus not be changed.
* The roles are determined by the product the group has: 
** For administrator, only administrator products can be added and thus have always the role admin.
** To user, both member and broker products can be added. The member role is always present. Also, if there are at least one broker product, the broker role is present too.

|-
| Name
| Text
| The name of the group.
* Required.
* Max. length: 100 characters.

|-
| Description
| Text area
| The description of the group.
* Max. length: 2000 characters.

|-
| Enabled
| Boolean
| Allows the administrator to disable the group.
* Checked by default; 
* Can only be disabled if group no members, see business rules above.
* Only visible for type "Member".

|-
| Group set
| Single selection / read only text
| Here you can select the Group Set the group is part of.
* Only visible for type "Member".
* A new GroupSet can be assigned to this group if (and only if) one of the following conditions applies: 
** No GroupSet is assigned yet to the group.
** The existing GroupSet which is assigned to the group has no products directly assigned to itself.
* If a new groupset can be assigned, it is shown in a single selection field. Otherwise readonly text is shown.

|-
| Managed admins
| Multi selection
| Gives the admin the permission to manage administrators in the selected groups (see also managed users).
* Only visible if "Administrator" is selected under type.
* Should list all groups of type "Administrator"

|-
| Manage networks
| Multi selection
| Gives the admin the permission to manage specific networks
* Only for global restricted admin groups

|-
| Can create networks
| Select
| Gives the admin the permission to create new networks (and manage them)
* Only for global restricted admin groups

|-
| Possible configurations for new networks
| Multi select
| Shows configurations the multi admins can extend when creating a new network. 
* Only for global restricted admin groups

|-
| Max amount networks
| Integer
| The maximum amount of networks that can be managed by users of this group
* Only for global restricted admin groups

|-
| Managed users
| Multi selection
| Gives the administrator the permission to manage users in the selected groups. The admin can only see the users he can manage to avoid confusion. All actions that an admin can perform directly on a user can be found in the [[User_actions]]. In most cases he needs this permission to manage a user group together with another permission. E.g. to manage a user record of a certain user the admin needs the permissoin <permission id="USER_RECORDS_MANAGE"/> and he needs to be able to manage the group the user is in. The specific permission the admin needs in combination with the permission to manage the group are indicated in the product with the following icon. [[File:manage.png|right|The admin/broker only has this permission over users he can manage.]]
* Only visible for type "Administrator".
* Contains an hierarchical view of all group sets / groups (of type "User") in the system.

|-
| User visibility
| Multi selection
| Give the users permission to other users in the selected groups.
* Only visible for type "Member".
* Contains an hierarchical view of all group sets / groups (of type "User" and status "Active") in the system.

|-
| Configurations
| Single selection / Link
| The configuration of the group:
* When the group is created this field is a single selection field in which the configuration for the group can be selected.
** The default value is the configuration of the groupset, if this is not available it will be the network default configuration. 
* When the group is edited this field is a link. 
** The link shows the active configuration of this group preceded with all higher level configurations.
** Example: "System default> England > England guests".
* Links to [[#Configuration_tab|configuration tab]].

|-
| Products
| Link
| The products assigned to the group.
* Only visible for type "Member".
* Only visible after the group is created (when editing the group).
* A list of products assigned to the group is shown, sorted by the level "Group set" and "Group". In the format:
** Group set: <product 1>, <product 2>, <etc>.
** Group: <product 3>, <product 4>, <etc>.
** If there are no products in one of these levels, the line is not shown. 
* Links to [[#Products_tab |Active products tab]].

|-
| colspan="3" bgcolor="#ffffcc" | '''Registration settings section'''
* Only visible for groups with type "Member".

|- 
| Initial user status
| Single selection
| Status for newly registered users under this group. Only affects new users - existing users moved to this group won't be affected.
* Required.
* Available options: Active, Blocked and Disabled.

|- 
| Name in registration
| Text
| When this group is used for public registration (set in the configuration) this name will be shown at the page the client can decide which group to register for.
* Max length: 100 characters.

|- 
| Description in registration
| Textarea
| When this group is used for public registration (set in the configuration) this description will be shown at the page the client can decide which group to register for.
* Max length: 4000 characters.

|- 
| Move users automatically
| Checkbox
| Enables the option to move users automatically to another group after they have been registered in this group for a certain period of time.

|- 
| Move users after
| Time interval
| Determines the period after the registration when user are moved to another group.
* Only visible if "Move users automatically" is checked. 
* Required when visible. 
* The amount must be between 1 and 9999.

|- 
| Move users to group
| Single select
| The group where the user are moved into.
* Only visible if "Move users automatically" is checked. 
* Required when visible. 
* Shows all user groups. 

|}
<br>

===Products (tab *)===
''* Not visible for administrator groups!''

====Search page (filters)====
{| border="1" cellpadding="3" cellspacing="0"
|-
| bgcolor="#FFFF8F" width="300pt" | '''Fields''' 
| bgcolor="#FFFF8F" width="200pt" | '''Type''' 
| bgcolor="#FFFF8F" width="900pt"| '''Rules''' 

|-
| colspan="3" bgcolor="#ffffcc" | '''Products'''

|-
| Add
| Multi action button
| Adds a new product to the group / user (depending the subject of the page).
* The button shows all available products that are not added already. 
* Only products of the relevant type (admin/user) are shown.
* Behind the name of the product is shown if it is an admin/broker/member/????operator???? product (e.g. "advertisements (member)").
* For user:
** Only visible if the admin has the <permission id="PRODUCTS_ASSIGN_TO_USER"/>.
** Only shows the products that can be add individually.
* For groups:
** Only visible if the admin has the <permission id="USER_CONFIGURATION_MANAGE"/>.
* If there is only one available product to add, show the product name at the button label: Add  product: <product name>
|}
<br>

====Search result (list *)====
''* Automatically shows all products assigned to the subject and its group and group set (if applicable), sorted alphabetically. First the lowest level is shown. ''

{| border="1" cellpadding="3" cellspacing="0"
|-
| bgcolor="#FFFF8F" width="300pt" | '''Fields''' 
| bgcolor="#FFFF8F" width="200pt" | '''Type''' 
| bgcolor="#FFFF8F" width="900pt"| '''Rules''' 

|-
| colspan="3" bgcolor="#ffffcc" | '''Products added to user'''
* Only shown if applicable (so: if subject is a user)
* If no individually assigned products: display text ''this user does not have any individually assigned products''

|-
| Product name
| Text (read only)
| The name of the product.

|-
| Role
| Text (read only)
| The role of the product: admin, broker or member.

|-
| Remove
| Icon
| Removes the product from the user.
* For user:
** Only visible if the admin has the <permission id="PRODUCTS_ASSIGN_TO_USER"/>.
** Only shows the products that can be add individually.
* For groups:
** Only visible if the admin has the <permission id="USER_CONFIGURATION_MANAGE"/>.
* Rules for product unassignment apply, see business rules.

|-
| colspan="3" bgcolor="#ffffcc" | '''Products added to (user's) group'''
* Only shown if applicable (so: if subject is a user, or a group)
* if subject is user: text is ''Products added to user's group''
* if subject is group: text is ''Products added to group''
* If no products: display text ''this group does not have any individually assigned products''
* Same columns apply as above
* Remove icon is only visible if this is the subject's level. So if the subject is a user, the products of the group or groupset cannot be removed here, hence the remove icon is not shown.

|-
| colspan="3" bgcolor="#ffffcc" | '''Products attached to group set this group belongs to'''
* if subject is user or group: text is ''Products added to group's group set''
* if subject is group set: text is ''Products added to group set''
* If no products: display text ''this group set does not have any individually assigned products''
* Same columns apply as above
* Remove icon is only visible if this is the subject's level; so if the subject of the page is a group set. 
|}
<br>

====Details page====
* This shows a merge of all products for the subject, according to the specifications given in [[Products]].
<br>

===Permissions (tab)===
* Only visible for administrator groups!
* See [[Users_-_Products#Page:_Administrator_product_details]].
<br>

===Configuration (tab)===

====Details page====
{| border="1" cellpadding="3" cellspacing="0"
|-
| bgcolor="#FFFF8F" width="300pt" | '''Fields''' 
| bgcolor="#FFFF8F" width="200pt" | '''Type''' 
| bgcolor="#FFFF8F" width="900pt"| '''Rules''' 

|-
| Set configuration / Set default configuration for groups
| Single Selection
| Displays the tree of the active configuration.
Rules: 
* only visible if loggedUser has <permission id="SYSTEM_CONFIGURATION_MANAGE"/> permission.
* only visible if the subject is a group or groupset. 
* if the subject is a group the label is ''Set configuration''
* if the subject is a groupset the label is ''Set default configuration for groups''
* The elements of the singleSelectionField are shown with indentation, reflecting the hierarchy of the options: an option which is a sub-configuration of another configuration is shown below that other configuration, and the name is indented with two extra spaces in front of it. 
* The present selected option of the single selection field is the actual configuration of the subject. This option, and all super-configurations of this option, are shown in bold font. 

|-
| Apply
| Action button
| rules: 
* only visible if previous item is visible.
* assigns the configuration to the group(set).
* refreshes / updates the page. 

|-
| Active configuration
| heading
| 

|-
| Active configuration
| Text (read only)
| Shows the configuration hierarchy in a text on one single line. 
* First the global level
* each level separated by a > sign. 
* Example: '''System default > England > England users'''.

|-
| colspan="3" |

The section below it shows a (not editable, read only) form which looks like [[System_-_Configurations#Page:_Configuration_details | Configuration details]], but shows all actual values for the fields (read only) of the configuration.
|}
<br>

==Page: Group set details==

'''Tabs:'''
* [[#Details (tab) 2]]
* [[#Products (tab) 2]]
* [[#Configuration (tab) 2]]

===Security===
'''Roles:'''
* Admin.

'''View permission:'''
* <permission id="USER_CONFIGURATION_VIEW"/>

'''Other permissions:'''
* <permission id="USER_CONFIGURATION_MANAGE"/>

===Details (tab)===
====Details page====

{| border="1" cellpadding="3" cellspacing="0"
|-
| bgcolor="#FFFF8F" width="300pt" | '''Fields''' 
| bgcolor="#FFFF8F" width="200pt" | '''Type''' 
| bgcolor="#FFFF8F" width="900pt"| '''Rules''' 

|-
| Type
| Text (read only)
| Displays "Group set".

|-
| Name
| Text
| The name of the group set.
* Required.
* Max. length: 100 characters.

|-
| Description
| Text
| The description of the group set.
* Required.
* Max. length: 2000 characters.

|-
| Configurations
| Single selection / Link
| The configuration of the groupset:
* When the groupset is created this field is a single selection field in which the configuration for the groupset can be selected.
** The default value is the network default configuration. 
* When the groupset is edited this field is a link. 
** The link shows the active configuration of this groupset preceded with all higher level configurations.
** Example: "System default > England > England guests".
* Links to [[#Configuration_tab | Active configuration tab]].

|-
| Products
| Link
| The products assigned to the groupset.
* Only visible after the groupset is created (when editing the groupset).
* A comma separated list of products assigned to the groupset is shown.
* A list of products assigned to the groupset is shown. In the format:
** Group set: <product 1>, <product 2>, <etc>.
** If there are no products assigned to the groupset the text "Group set" is hidden.
* Links to [[#Products_tab | products tab]].
|}
<br>

===Products (tab)===
* See [[#Products (tab *)]].
<br>

===Configuration (tab)===
* See [[#Configuration (tab)]].
<br>