====== Automatic roles by attribute ======

Automatic role by attribute is similar to automatic role by organization structure, both entities and dto's has same parent ''IdmAutomaticRole'' for entities and ''AbstractIdmAutomaticRoleDto'' for dto's. Both parent defined **role** and **name** attribute. Name attribute is only for better readability.


===== Definition =====
For automatic role by attribute exists two entities (and also dto's) ''IdmAutomaticRoleAttributeDto'' and ''IdmAutomaticRoleAttributeRuleDto'' these entities are in one-to-many (1:M) relation (automatic role by attribute has more definition of rules).

==== Attribute ====
Automatic role by attribute (dto ''IdmAutomaticRoleAttributeDto'') has defined all attributes from his parent (''AbstractIdmAutomaticRoleDto'') and plus attribute **concept** see //Inconsistent state//. For automatic role by attribute isn't possible update role and name attribute.
  * **name** - name of the automatic role by attribute (required),
  * **role** - role that will be assigned after pass rules (required),
  * **concept** - flag that sign that automatic role by attribute is not recalculate for users.

==== Rules ====
Individual rules for automatic roles by attribute, now is possible connect rules only with **AND** operator.

  * **automaticRoleAttribute** - for what automatic role by attribute is this rule defined,
  * **formAttribute** - for what EAV attribute is rule defined, only if rule is for EAV attributes (all form definitions for identity and contract are supported),
  * **attributeName** - for what entity attribute is rule defined, only if rule is for entity attributes,
  * **type** - enumeration ''AutomaticRoleAttributeRuleType'' defined for with type is this rule (e.q. identity, contract, identity eav and contract eav),
  * **value** - value for comparison entity value,
  * **comparison** - enum ''AutomaticRoleAttributeRuleComparison'' contains all available comparison.
    * EQUALS,
    * NOT\_EQUALS,
    * START\_WITH,
    * NOT\_START\_WITH,
    * END\_WITH,
    * NOT\_END\_WITH,
    * IS\_EMPTY,
    * IS\_NOT\_EMPTY,
    * CONTAINS,
    * NOT\_CONTAINS,
    * LESS\_THAN\_OR\_EQUAL,
    * GREATER\_THAN\_OR\_EQUAL.

<note important>Object value is type String and max size is 2000 chars. In DB: value character varying(2000).</note>

{{ :devel:dev:new_rule.png |}}

=== Comparison ===
Some comparison has limitation for attributes which can be used. For example:

Comparison ''LESS\_THAN\_OR\_EQUAL'' and ''GREATER\_THAN\_OR\_EQUAL'' can be used only with numeric attributes. **Dont** use it with another types.

For **multivalued** attributes (now only extended attributes - EAV) is available comparisons ''EQUALS'', ''IS\_EMPTY'' and ''IS\_NOT\_EMPTY''. Comparison ''EQUALS'' search **first** equals value in all values. For example if exists rule //equals=10// that exists for multivalued attribute that contains values 10, 20, 30 and 40. The rule **will pass** because equals search **first** value **not all**.
All another comparison is **unavailable** for multivalued attributes.

Comparison ''NOT\_EQUALS'', ''NOT\_START\_WITH'', ''NOT\_END\_WITH'' and NOT\_CONTAINS check **null** values **empty strings** "" (for entity attributes only). For EAVs doesn't exist value (entity IdmFormValue) when is empty or just doesn't exist. All these comparison **pass** when value doesn't exist.


Comparison ''CONTAINS'' and ''NOT\_CONTAINS'' use classic like statement. We recommend use another type of comparison because with combination with another rules is possible that some performance problem appears. About performance and automatic roles see section [[devel:documentation:roles:dev:automatic-roles-by-attribute-performance|performance]].

<note info>With more rules grow up query cost, but not constantly. [[devel:documentation:roles:dev:automatic-roles-by-attribute-performance|]]. For more information see the performance section.</note>


===== Inconsistent state =====
After add, delete or update rule for automatic role by attribute is this automatic role in inconsistent state. Inconsistent state mean that is possible that some user has or hasn't assigned this automatic role event if it should be assigned or removed.

Inconsistent state we can repair by recalculate roles for this automatic role. Recalculation is done by long running task ''ProcessAutomaticRoleByAttributeTaskExecutor'', this task need only id of automatic role by attribute. LRT assign role for all new users that pass rules and remove role for all users that already didn't passed.

{{ :devel:dev:inc_warning.png |}}


===== Recalculation =====
Recalculation is process that recalculate automatic role for all users. In two db query is get all new users that pass the automatic role by attribute and all users that already din't pass. For these two set is create requests.


==== After save identity or contract values ====
For automatic role by attribute was created two new processor ''IdentityAutomaticRoleProcessor'' and ''IdentityContractAutomaticRoleProcessor'' both these processors catch event for UPDATE, CREATE and EAV_SAVE. After catch event is done recalculate all automatic roles only for identity that is save.

==== After add, remove or update rule ====
After update, delete or add rule for automatic role by attribute is this automatic role in inconsistent state (see //Inconsistent state//). User that update, delete or add rule is ask for immediate recalculation by modal window.  

{{ :devel:dev:recalculation_warning.png |}}

==== LRT ====
Long running task ''ProcessAutomaticRoleByAttributeTaskExecutor'' process automatic role (given in attribute), this task process all users. Long running task ''ProcessAllAutomaticRoleByAttributeTaskExecutor'' executes same process as ''ProcessAutomaticRoleByAttributeTaskExecutor'' but synchronously for all automatic roles by attribute. Is also useful recalculate all automatic roles once per day. For example contract/slice synchronization executes ''ProcessAllAutomaticRoleByAttributeTaskExecutor'' with HR process.