====== Copying assigned roles ======
Copying roles from a user is a useful feature for copying/sharing permissions between users. The main purpose is to make it easier to add manually assigned roles to another user.


===== How the feature works =====
The feature is available on the role request detail as a new button.

{{ :devel:documentation:add_role.png |}}

To be able to view this button and create a new role request you need to have permissions to change user permissions, create request, etc. For more information, see [[devel:documentation:security:dev:authorization|authorization dokuwiki page]].

===== Steps to copy roles =====

==== Select the user ====
Copying roles is done by means of a pop-up window. In this window, you can select the user from whom you would like to copy their roles, by filling the select box labelled ''Select a user''. 

{{ :devel:documentation:roles:dev:add_role_002.png |}}

==== Select a contract from the selected user ====

Once you have selected the user, you can also select one of their contracts to see a respective set of assigned roles for that selected user, as there can be more than one contract.

{{ :devel:documentation:roles:dev:add_role_003.png |}}
<note tip>Roles that are then displayed had been assigned only for the selected contract. If the contract field stays unselected (i.e. blank), then **all assigned roles** across all the user's contracts are listed.</note>

==== Choose a contract and date for adding new roles ====

At this stage, you have to select a contract to have new roles assigned. This field is mandatory.

{{ :devel:documentation:roles:dev:add_role_004.png |}}

Next, you may specify validity dates for these requested roles.

<note tip>For manually assigned roles it is possible to change validity. In contrast,  automatically assigned roles uphold the **validity from the contract**.</note>

==== Copy role parameters with/without values ====

If any of the assigned roles includes role parameters, you can also choose to copy the parameters with or without these values. By default this option is disabled, you can activate it by checking the checkbox.

{{ :devel:documentation:roles:dev:add_role_005.png |}}

==== Select desired roles ====

In the lowest part of the pop-up window there is a component for selecting assigned roles and copying them.

{{ :devel:documentation:roles:dev:add_role_006.png |}}

The buttons in between the ''Roles select from a user'' and ''Selected roles'' tables let you do the following actions: 
  * {{:devel:documentation:roles:dev:add_role_007.png|}} add **all** roles that are listed in the ''Roles selected from a user'' table to the ''Selected roles'' table,
  * {{:devel:documentation:roles:dev:add_role_008.png|}} add **only selected** roles that are listed in the ''Roles select from user'' table to ''Selected roles'' table,
  * {{:devel:documentation:roles:dev:add_role_009.png|}} remove **only selected** roles that are listed in the ''Selected roles'' table,
  * {{:devel:documentation:roles:dev:add_role_010.png|}} remove **all** roles that are listed in the ''Selected roles'' table.

**Example:**

{{ :devel:documentation:roles:dev:add_role_011.png |}}

==== Directly assigned roles / Subroles ====

There may be some business roles among the desired selection of roles. These roles most likely consist of some subroles. Subroles are assigned to a user automatically once the top (parent or business) or upper role within the business role composition has been assigned to them.

In default settings of the pop-up window (for copying roles from a user), only directly assigned roles are displayed. This option can be changed by checking the checkbox ''Show only roles assigned directly''.

{{ :devel:documentation:roles:dev:add_role_012.png |}}

<note important>Be careful: if you assign a business role along with all of its subroles DIRECTLY, the user ends up having duplicate, or possibly triplicate roles. In other words, **its subroles will be assigned twice**.</note>

==== Icons and description of roles ====

  * {{:devel:documentation:roles:dev:manually.png|}} - directly assigned application role,
  * {{:devel:documentation:roles:dev:automatic.png|}} - role assigned by automatic role configuration (by tree structure or attribute),
  * {{:devel:documentation:roles:dev:business.png|}} - directly assigned business role. Defined subroles are to be assigned together with this role,
  * {{:devel:documentation:roles:dev:subrole.png|}} - role assigned by a business role (or one of its subroles).

More about roles can be found [[devel:documentation:roles|here]]