====== Automatic roles - adding a role to the organization structure ======

To add a role to a tree structure use **Roles -> Role detail -> Automatic roles**.

{{ :devel:adm:test_role_list.png?600 | Automatic roles list}}

The tab **Automatic roles** allows integrating a given role into an organizational tree. This means that the role will be assigned to and removed from users based on adding/removing of a user to/from the organizational tree structure. The automatic roles agenda displays the current list of tree structure elements (organizations) in which the currently edited role is set as an automatic role.

{{ :devel:adm:automatic_roles_add.png?600 | Automatic role add}}

<note important>In the current version of CzechIdM, automatic roles can only be created and removed.</note>

A new automatic role can be created by clicking the Add button. The following parameters of automatic roles can be set:

  * **Role (read-only)** – role name
  * **Tree structure element** – it defines a point in the organizational structure where the role will be placed
  * **Recursion type** – denotes the ability to assign the role in the tree:
    * **Without recursion** – the role will be given only to the users whose contract is situated on the same element of the organization as the role.
    * **Down by structure** - the role will be given to all the users whose contract is situated on the same element of organization + of all structure elements below. For example: Assigning a role to the highest point of the organizational structure (to the “top”) will result in assigning of the role to all users in the whole organization structure.
    * **Up by structure** - the role will be given to all the users whose contract is situated on the same element of organization + of all structure elements above it.

The validity of user's contract is checked when integrating the user into the organization structure. If the user’s contract is not valid (according to the contract's attributes Valid from and Valid till), then

  * **the role is assigned if the validity of the contract starts in future**. In fact, the "role to user" validity (other validity then contract validity) applies the same time the contract starts. In other words, if the role e.g. gives the user account in MS AD, the account is not created until the contract the role is assigned to starts.
  * The role is not assigned, if Valid to of the contract is in the past, i.e. **automatic roles are not assigned if the contract has already ended**.

If the validity of the user’s contract, for which he has been assigned an automatic role, changes, then the validity of "role to user" relation changes as well. This ensures that, at the beginning or the end of the contract, the role will always be removed or added regardless of how the validity has been changing in course of time.

If a role is added as automatic into a structure where there is already a user, the user will be assigned this role immediately. On the contrary, if an automatic role is removed from a structure where there is already a user, it will be removed from these users immediately.

<note tip>When tree structure is changed, for example one element is moved in tree structure under different parent, then defined automatic roles are recounted by the new tree structure.</note>

===== Video Guide =====
[[https://www.youtube.com/watch?v=xgcyTqTjgdQ&list=PLBeAQt3pe3EcdVE8QpCDEJcDsi_jtNQUb&index=3|How to add automatic role]] - czech language