Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
devel:documentation:systems:dev:system-mapping [2019/07/02 09:17] – [System scheme] svandavdevel:documentation:systems:dev:system-mapping [2025/03/13 00:35] (current) – [Mapping priority (since 14.7.0, 15.1.0)] koulaj
Line 1: Line 1:
 ====== Connector configuration and attribute mapping ====== ====== Connector configuration and attribute mapping ======
-{{tag>connector mapping system configuration }}+ 
 +{{tag>connector mapping system configuration merge authoritative skip excluded }}
  
 ===== Connector configuration ===== ===== Connector configuration =====
-Creation of a newly connected system will be demonstrated on a database connector (ConnIdDBBundle). 
-Firstly, we will create a new system named **Table** and choose the database connector. 
-All settings for this connector are available in the **Configuration** tab. 
-In the picture below is an example of the configuration: 
-<note tip>The configuration below is only an example.The system in its default state doesn't contain the mapped table "system-users" </note> 
-{{ :navrh:workflow:selection_047.png?800 |}} 
  
 +{{tag>connector configuration}}
 +
 +Creation of a newly connected system will be demonstrated on a database connector (ConnIdDBBundle). Firstly, we will create a new system named **Table** and choose the database connector. All settings for this connector are available in the **Configuration** tab. In the picture below is an example of the configuration: <note tip>The configuration below is only an example.The system in its default state doesn't contain the mapped table "system-users" </note> {{  :navrh:workflow:selection_047.png?800  }}
  
 ==== Connector pool configuration ==== ==== Connector pool configuration ====
 +
 +{{tag>connector pool}}
  
 **The connector pool** is a very useful feature that avoids unnecessarily creating a new connector instance each time a connector is called. Typically, each connector instance also creates a connection to that target system. It is effective to maintain these connections for **longer periods and for multiple calls**. **The connector pool** is a very useful feature that avoids unnecessarily creating a new connector instance each time a connector is called. Typically, each connector instance also creates a connection to that target system. It is effective to maintain these connections for **longer periods and for multiple calls**.
Line 18: Line 18:
  
 The last advantage is the ability to use **multiple connections** to one target system, which is especially advantageous during parallel processing. The last advantage is the ability to use **multiple connections** to one target system, which is especially advantageous during parallel processing.
- 
 === Pool configurations: === === Pool configurations: ===
-  * **Pooling supported** - Enable / disable entire pool+ 
 +  * **Pooling supported**  - Enable / disable entire pool
   * **Max idle objects**   * **Max idle objects**
   * **Minimum number of idle objects**   * **Minimum number of idle objects**
-  * **Max objects** - Max number of objects in the pool. +  * **Max objects**  - Max number of objects in the pool. 
-  * **Max time to wait** - Max time to wait for free object in the pool. +  * **Max time to wait**  - Max time to wait for free object in the pool. 
-  * **Minimum time to wait before evicting** - Minimum time to wait befor evicting idle object. +  * **Minimum time to wait before evicting**  - Minimum time to wait befor evicting idle object.
 <note important>By default is pool **disabled**!</note> <note important>By default is pool **disabled**!</note>
  
 <note tip>Pool configuration is persisted in EAV attributes and use form definition with code "pooling-connector-configuration".</note> <note tip>Pool configuration is persisted in EAV attributes and use form definition with code "pooling-connector-configuration".</note>
  
 +{{  .:pool-config.png?800  }}
  
-{{ :devel:documentation:systems:dev:pool-config.png?800 |}}+==== Additional connector configuration ====
  
- +{{tag>operation options}} 
 + 
 +The additional connector configuration tab lets you configure so called operation options for each type of connector. These options are then passed to each invocation of given connector. This enables us to further tweak connection paramters for each system, such as list of attributes, which should be returned from target system. 
 + 
 +Each system has its own set of operation options. By default, only PAGE_SIZE and ATTRS_TO_GET is available for each connector, but you can easily add other options using corresponding form definition. 
 + 
 +=== Example operation options: === 
 + 
 +  * **PAGE\_SIZE**  - Number of records returned in paged search operation. This option is used for example in LDAP/AD connector 
 +  * **ATTRS\_TO\_GET**  - List of attributes, which should be returned from system 
 +<note tip>Operation options are persisted in EAV attributes and use form definition with code "operation-options-connector-configuration-CONNECTOR_FULL_NAME_AND_VERSION".</note> 
 + 
 +{{  .:operation_options.png  }}
  
 ===== System scheme ===== ===== System scheme =====
 +
 {{tag>system scheme}} {{tag>system scheme}}
-When the connector is configured correctly, we can move on to the **System scheme** tab. There, we will create the scheme either manually or we will use the scheme which will be returned by the connector itself (according to the filled-in configuration).+ 
 +When the connector is configured correctly, we can move on to the **System scheme**  tab. There, we will create the scheme either manually or we will use the scheme which will be returned by the connector itself (according to the filled-in configuration).
  
 The scheme will be automatically created by pressing **Generate scheme**. The scheme will be automatically created by pressing **Generate scheme**.
  
 +{{  .:schema-config.png?800  }}
  
-{{ :devel:documentation:systems:dev:schema-config.png?800 |}} +After a successful generation, there should be a new entry (object class) **\__ACCOUNT\__**  in the object types table. This entry will contain available attributes in the system (for object ACCOUNT). In our case, it will contain an attribute for each column in the mapped table and the semantic attributes:
- +
- +
-After a successful generation, there should be a new entry (object class) **\__ACCOUNT\__** in the object types table. +
-This entry will contain available attributes in the system (for object ACCOUNT). In our case, it will contain an attribute for each column in the mapped table and the semantic attributes: +
-  * **\__NAME\__** - attribute identifying the account in the system (user name). +
-  * **\__PASSWORD\__** - attribute for password mapping for the given account. +
-  * **\__ENABLE\__** - attribute for mapping the indication whether the account is enabled or disabled.+
  
 +  * **\__NAME\__**  - attribute identifying the account in the system (user name).
 +  * **\__PASSWORD\__**  - attribute for password mapping for the given account.
 +  * **\__ENABLE\__**  - attribute for mapping the indication whether the account is enabled or disabled.
 ===== Attribute mapping ===== ===== Attribute mapping =====
 +
 {{tag>attribute mapping}} {{tag>attribute mapping}}
  
-When the system scheme is created, we can move on to attribute mapping in the **Attribute mapping** tab. Mapping serves two basic purposes:+When the system scheme is created, we can move on to attribute mapping in the **Attribute mapping**  tab. Mapping serves two basic purposes: 
   - **Making the scheme attributes accessible in the IdM system**. Only mapped attributes can be used in IdM for active operations (provisioning/synchronization). Mapping is always tied to the operation type and entity type (identity, group).   - **Making the scheme attributes accessible in the IdM system**. Only mapped attributes can be used in IdM for active operations (provisioning/synchronization). Mapping is always tied to the operation type and entity type (identity, group).
-  - **It defines which value will the attribute be mapped into in the IdM system.** (identity, group, extended attribute, hidden attribute). +  - **It defines which value will the attribute be mapped into in the IdM system.**  (identity, group, extended attribute, hidden attribute). 
- +Firstly, we will create a group (operation type and entity type) which we would like to map. We will select **Provisioning**  and **Identity**. Then we will start creating the individual mappings. It is very important to create a mapping for the account identifier in the system and connect it correctly to the IdM identity. This is done by adding a new attribute.
-Firstly, we will create a group (operation type and entity type) which we would like to map. We will select **Provisioning** and **Identity**. Then we will start creating the individual mappings. +
-It is very important to create a mapping for the account identifier in the system and connect it correctly to the IdM identity. This is done by adding a new attribute.+
  
 **In the attribute mapping details we will fill in**: **In the attribute mapping details we will fill in**:
-  * The attribute from the system scheme which identifies the account, i.e. **\__NAME\__**.+ 
 +  * The attribute from the system scheme which identifies the account, i.e. **\__NAME\__** .
   * Fill in the name of the mapped attribute. It is pre-filled with the scheme attribute name but any other name can be used.   * Fill in the name of the mapped attribute. It is pre-filled with the scheme attribute name but any other name can be used.
   * Tick **Is identifier**.   * Tick **Is identifier**.
   * Tick **Entity attribute**. The attribute will be tied to the user name of the identity in IdM.   * Tick **Entity attribute**. The attribute will be tied to the user name of the identity in IdM.
-  * Fill in **username** as the **IdM key**.+  * Fill in **username**  as the **IdM key**.
  
-{{ :devel:documentation:systems:dev:attribute-detail.png?800 |}}+{{  .:attribute-detail.png?800  }}
  
 <note tip>Create mapping for the other attributes in the same way. Below you can find a table with the resulting mapping:</note> <note tip>Create mapping for the other attributes in the same way. Below you can find a table with the resulting mapping:</note>
- 
- 
  
 ===== Attribute cache ===== ===== Attribute cache =====
 +
 For optimalization, the attribut can be cached. New mapping attribute is marked as 'cached' by default. For optimalization, the attribut can be cached. New mapping attribute is marked as 'cached' by default.
-  * The cache **key** is a mapped attribute and attributes from the end system. 
-  * The **value** is the transformed value from the system. 
  
-<note important>At this point, caching is only used in sync. This cache is cleared on start and end every sync.</note> +  * The cache **key**  is a mapped attribute and attributes from the end system. 
-<note warning>If the attribute generates a value independent of the input parameters (random identifier, ...), it is necessary to disable caching on such an attribute.</note>+  * The **value**  is the transformed value from the system. 
 + 
 +<note important>At this point, caching is only used in sync. This cache is cleared on start and end every sync.</note> <note warning>If the attribute generates a value independent of the input parameters (random identifier, …), it is necessary to disable caching on such an attribute.</note> 
 ==== Send additional attributes with password ==== ==== Send additional attributes with password ====
  
-It's possible to send additional attributes to provisioning, when password is changed (e.g. password expiration in extended attribute). New flag ''sendOnPasswordChange'' was added to system attribute mapping - attribute with this flag checked will be send together with changed password to provisioning. Two ways for provisioning additional attributes are implemented:+It's possible to send additional attributes to provisioning, when password is changed (e.g. password expiration in extended attribute). New flag ''sendOnPasswordChange''  was added to system attribute mapping - attribute with this flag checked will be send together with changed password to provisioning. Two ways for provisioning additional attributes are implemented: 
   - send additional attributes together with new password in one provisioning operation   - send additional attributes together with new password in one provisioning operation
-  - send additional attributes after password is changed in another provisioning operation +  - send additional attributes after password is changed in another provisioning operation 
 Two ways are be configurable by application configuration ''idm.sec.acc.provisioning.sendPasswordAttributesTogether'': Two ways are be configurable by application configuration ''idm.sec.acc.provisioning.sendPasswordAttributesTogether'':
-    * ''true'': additional password attributes will be send in one provisioning operation together with password 
-    * ''false'': additional password attributes will be send in new provisioning operation, after password change operation (some systems doesn't support to change other attributes in the same request with password) 
  
 +  * ''true'': additional password attributes will be send in one provisioning operation together with password
 +  * ''false'': additional password attributes will be send in new provisioning operation, after password change operation (some systems doesn't support to change other attributes in the same request with password)
 <note tip>Configuration is effective for all target systems. All target system will be using one configured way (configuration per-system is not implemented, coming soon).</note> <note tip>Configuration is effective for all target systems. All target system will be using one configured way (configuration per-system is not implemented, coming soon).</note>
  
 +=== Send attribute only on password change ===
 +
 +Since version **11.0.0**  a new flag **Send only on password change**  was added to the attribute detail.
 +
 +If is this flag checked, then the attribute will be send to the system only during change of password operation. It means that this attribute will be ignored in standard provisioning operations (create/update). <note important>This checkbox can be use only if attribute has checked flag **Send additional attributes with password**.</note>
  
 ===== Linking a role ===== ===== Linking a role =====
 +
 {{tag>role}} {{tag>role}}
-In the previous paragraphs, we created a system which contains a scheme and mapped attributes for an identity and provisioning. 
-In order to create an account for a specific user in the end system, we have to create a role which will be assigning this system and, at the same time, we have to assign this role to the user. 
- 
-  * We will create a new role **Table role**.  
-  * In the **Connected systems** tab, we will create a new connection to our system **Table** for the entity **Identity**. 
-  * We will assign this role to a user. We will do this in the user details in the **Assigned roles** tab. 
-  * After successfully assigning the valid role, a corresponding account in the system should be created. We can check this in the "System  accounts" tab, where a link to the account should have been created. 
-  * We can also check the account creation in the **Table** system. A link to the user account should have been created in the **System entities** tab. 
-  * **System identifier**, which is an identifier returned by the system after the creation of the account. 
  
 +In the previous paragraphs, we created a system which contains a scheme and mapped attributes for an identity and provisioning. In order to create an account for a specific user in the end system, we have to create a role which will be assigning this system and, at the same time, we have to assign this role to the user.
  
 +  * We will create a new role **Table role**.
 +  * In the **Connected systems**  tab, we will create a new connection to our system **Table**  for the entity **Identity**.
 +  * We will assign this role to a user. We will do this in the user details in the **Assigned roles**  tab.
 +  * After successfully assigning the valid role, a corresponding account in the system should be created. We can check this in the "System accounts" tab, where a link to the account should have been created.
 +  * We can also check the account creation in the **Table**  system. A link to the user account should have been created in the **System entities**  tab.
 +  * **System identifier**, which is an identifier returned by the system after the creation of the account.
 ===== Linking a role - attribute overload ===== ===== Linking a role - attribute overload =====
  
 In the previous chapter we explained how to assign a role tied to a system. By doing this, we created an account which corresponds precisely to the mapping in the system. That was a default mapping. However, if want to create a role which will affect only a specific attribute, we will need to adjust the behavior (mapping) of the attribute, i.e. we will need to overload the attribute mapping. In the previous chapter we explained how to assign a role tied to a system. By doing this, we created an account which corresponds precisely to the mapping in the system. That was a default mapping. However, if want to create a role which will affect only a specific attribute, we will need to adjust the behavior (mapping) of the attribute, i.e. we will need to overload the attribute mapping.
  
-<note tip> We need to create a role where, after it has been assigned, the linked accounts will contain first name + the "overloaded attribute" invariable in the **firstname** attribute.</note>+<note tip> We need to create a role where, after it has been assigned, the linked accounts will contain first name + the "overloaded attribute" invariable in the **firstname**  attribute.</note>
  
   * We will create a new role **Table role - first name**.   * We will create a new role **Table role - first name**.
   * Add the same system mapping as with the *Table role* role.   * Add the same system mapping as with the *Table role* role.
-  * In the **Attributes mapped within this role** table, we will add a new attribute which will overload the default attribute **firstname**. +  * In the **Attributes mapped within this role**  table, we will add a new attribute which will overload the default attribute **firstname**. 
-    * **Fill in the name** - for example "firstname - overloaded attribute (adds the "overloaded value" suffix)". +      * **Fill in the name**  - for example "firstname - overloaded attribute (adds the "overloaded value" suffix)". 
-    * Tick **Entity attribute**. +      * Tick **Entity attribute**. 
-    * Fill in **firstName** as the **IdM key**. +      * Fill in **firstName**  as the **IdM key**. 
-    * Insert "return attributeValue + "overloaded value";"" in the script for transformation into the system. +      * Insert "return attributeValue + "overloaded value";"" in the script for transformation into the system. 
-    * Now, if the role is assigned to a user, the account on the end system **Table** will contain the **overloaded value** suffix in the **firstname** attribute. +      * Now, if the role is assigned to a user, the account on the end system **Table**  will contain the **overloaded value**  suffix in the **firstname**  attribute.
  
 ====== Mapped attribute strategy ====== ====== Mapped attribute strategy ======
 +
 {{tag>attribute strategy}} {{tag>attribute strategy}}
  
Line 133: Line 152:
 The default strategy which sends the acquired value to the end system as IdM calculates it. If the value is the same on the end system, the attribute isn't sent. The default strategy which sends the acquired value to the end system as IdM calculates it. If the value is the same on the end system, the attribute isn't sent.
  
-This strategy is applied both to account **editing** and its **creation**. +This strategy is applied both to account **editing**  and its **creation**.
  
 ==== WRITE-IF-NULL (Set only if the value on the system is null) ==== ==== WRITE-IF-NULL (Set only if the value on the system is null) ====
  
-The attribute value which is calculated by IdM is sent to the end system only if the end system value is calculated as equal to **null**. +The attribute value which is calculated by IdM is sent to the end system only if the end system value is calculated as equal to **null**. Before the final comparison whether the value is non-existent, **transformation from the system**  is applied to the attribute value from the end system. The transformation is defined in the mapping of the attribute.
-Before the final comparison whether the value is non-existent, **transformation from the system** is applied to the attribute value from the end system. The transformation is defined in the mapping of the attribute.+
  
-This strategy is applied both to account **editing** and its **creation**. +This strategy is applied both to account **editing**  and its **creation**.
  
-<note note>This strategy is also implemented in the case of **synchronization**. The function is similar to that of provisioning. The opposite is only the source and destination. In the case of synchronization, it is the source **account** on the end system and the goal is synchronized **entity**. Before comparing, a **transformation to the system** is applied.</note>+<note note>This strategy is also implemented in the case of **synchronization**. The function is similar to that of provisioning. The opposite is only the source and destination. In the case of synchronization, it is the source **account**  on the end system and the goal is synchronized **entity**. Before comparing, a **transformation to the system**  is applied.</note>
  
-<note tip>The **WRITE-IF-NULL** strategy has a lower priority than **SET**, **MERGE** and **AUTHORITATIVE_MERGE**. Therefore, if we define one attribute with the **SET** strategy and another with the **WRITE-IF-NULL** strategy in the default mapping on the system, then the value of the **WRITE-IF-NULL** attribute will never be used. In this case, it will be necessary to define only the attribute with the **WRITE-IF-NULL** strategy in the default mapping. The other attribute with the **SET** strategy will have to be defined in the role as an overload of the default attribute.</note>+<note tip>The **WRITE-IF-NULL**  strategy has a lower priority than **SET**, **MERGE**  and **AUTHORITATIVE_MERGE**. Therefore, if we define one attribute with the **SET**  strategy and another with the **WRITE-IF-NULL**  strategy in the default mapping on the system, then the value of the **WRITE-IF-NULL**  attribute will never be used. In this case, it will be necessary to define only the attribute with the **WRITE-IF-NULL**  strategy in the default mapping. The other attribute with the **SET**  strategy will have to be defined in the role as an overload of the default attribute.</note>
  
 ==== CREATE (Set only when creating) ==== ==== CREATE (Set only when creating) ====
Line 150: Line 168:
 The attribute value which is calculated by IdM is sent to the end system only when creating a new account on the end system. The attribute value which is calculated by IdM is sent to the end system only when creating a new account on the end system.
  
-<note note>This strategy is also implemented in the case of **synchronization**. The function is similar to that of provisioning. The opposite is only the **source** and **destination**. The value of the attribute from the system is set to the entity only when it is creating.</note>+<note note>This strategy is also implemented in the case of **synchronization**. The function is similar to that of provisioning. The opposite is only the **source**  and **destination**. The value of the attribute from the system is set to the entity only when it is creating.</note>
  
-The **CREATE** strategy has a lower priority than **WRITE-IF-NULL**, **SET**, **MERGE** and **AUTHORITATIVE-MERGE**.+The **CREATE**  strategy has a lower priority than **WRITE-IF-NULL**, **SET**, **MERGE**  and **AUTHORITATIVE-MERGE**.
  
 ==== AUTHORITATIVE_MERGE (Authoritative merge) ==== ==== AUTHORITATIVE_MERGE (Authoritative merge) ====
 +
 {{tag>authoritative merge}} {{tag>authoritative merge}}
  
Line 161: Line 180:
 <note important>Both the MERGE and AUTHORITATIVE_MERGE strategies, can be linked only to a multi-value scheme attribute!</note> <note important>Both the MERGE and AUTHORITATIVE_MERGE strategies, can be linked only to a multi-value scheme attribute!</note>
  
-The **MERGE** strategies are different, however. If there are more attributes overloading the same default attribute, all the values are merged into one. This resulting value (list) is sent to the IdM system as a "wish" of how the value should look like on the end system.+The **MERGE**  strategies are different, however. If there are more attributes overloading the same default attribute, all the values are merged into one. This resulting value (list) is sent to the IdM system as a "wish" of how the value should look like on the end system.
  
-<note important>A situation where there are two overloaded attributes for the same default attribute, one having the **AUTHORITATIVE_MERGE** strategy and the other the **SET** or **MERGE** strategy, will not be valid. **Such a situation is collisional and will result in an exception during provisioning!**</note>+<note important>A situation where there are two overloaded attributes for the same default attribute, one having the **AUTHORITATIVE_MERGE**  strategy and the other the **SET**  or **MERGE**  strategy, will not be valid. **Such a situation is collisional and will result in an exception during provisioning!**</note>
  
 With authoritative merge, the original values of the attribute on the end system are not taken into account (i.e. if some other system or administrator had put a different value to the attribute, it would be ignored by IdM). With authoritative merge, the original values of the attribute on the end system are not taken into account (i.e. if some other system or administrator had put a different value to the attribute, it would be ignored by IdM).
  
-Therefore, in a situation where the resulting value of the merged attribute from **IdM** is **[A,B]** and the value of the same attribute on the end system is **[C,D]**, then the end system attribute will gain the value of **[A,B]** after provisioning.+Therefore, in a situation where the resulting value of the merged attribute from **IdM**  is **[A,B]**  and the value of the same attribute on the end system is **[C,D]**, then the end system attribute will gain the value of **[A,B]**  after provisioning.
  
 ==== MERGE (Merge) ==== ==== MERGE (Merge) ====
-{{tag>merge}} 
  
-<note warning>Since version **9.3.0** was provisioning merge completely reimplemented!</note>+{{tag>merge controlled}} 
 + 
 +<note warning>Since version **9.3.0**  was provisioning merge completely reimplemented!</note>
  
 This strategy follows the same pattern as authoritative merge up until the phase of creating a "wish" for IdM. This strategy follows the same pattern as authoritative merge up until the phase of creating a "wish" for IdM.
Line 178: Line 198:
 A procedure different from authoritative merge occurs at the moment of provisioning. The goal is to ensure that the attribute on the end system can be shared by more systems (it means IdM is not authority for all values in the attribute). A procedure different from authoritative merge occurs at the moment of provisioning. The goal is to ensure that the attribute on the end system can be shared by more systems (it means IdM is not authority for all values in the attribute).
  
-<note important>A situation where there are two overloaded attributes for the same default attribute, one having the **MERGE** strategy and the other the **SET** or **AUTHORITATIVE_MERGE** strategy, will not be valid. **Such a situation is collisional and will result in an exception during provisioning!**</note>+<note important>A situation where there are two overloaded attributes for the same default attribute, one having the **MERGE**  strategy and the other the **SET**  or **AUTHORITATIVE_MERGE**  strategy, will not be valid. **Such a situation is collisional and will result in an exception during provisioning!**</note>
  
-Another goal is to ensure the correct **removing** of the managed values.+Another goal is to ensure the correct **removing**  of the managed values.
  
 For identify what values are controlled by the IdM, we get it based on the settings of the roles mapping the system and overloaded this attribute (this 'calculation of the definition' approach is used since version 9.3.0. The previous approach, where the values ​​from the provisioning archive were used no longer used). For identify what values are controlled by the IdM, we get it based on the settings of the roles mapping the system and overloaded this attribute (this 'calculation of the definition' approach is used since version 9.3.0. The previous approach, where the values ​​from the provisioning archive were used no longer used).
  
-<note tip>The **controlled values** ​​are **currently valid** values ​​(based on roles values) and values **valid in the past**. </note>+<note tip>The **controlled values**  ​​are **currently valid**  values ​​(based on roles values) and values **valid in the past**. </note>
  
 The controlled values ​​are currently valid values ​​(based on roles values) and values valid in the past. Such a "historical" value arises at the time of the definition of role change, typically in the following cases: The controlled values ​​are currently valid values ​​(based on roles values) and values valid in the past. Such a "historical" value arises at the time of the definition of role change, typically in the following cases:
  
-* **Change the script defining the controlled value**. For example, if we change the assigned value 'A' (in transformation to the system) to 'Z', then the currently contolled value will be 'Z' and the new historical value 'A'. +* **Change the script defining the controlled value**. For example, if we change the assigned value 'A' (in transformation to the system) to 'Z', then the currently contolled value will be 'Z' and the new historical value 'A'. * **By disabling the attribute**  - if we disable the attribute assigning the value 'A', then a new historical value 'A' will be created. The 'A' value will no longer be part of the currently controlled values ​​that are calculated based on the definition. * **Change the attribute strategy**  - if we change the strategy from 'Merge' to another, the value 'A' will again be only historical.
-* **By disabling the attribute** - if we disable the attribute assigning the value 'A', then a new historical value 'A' will be created. The 'A' value will no longer be part of the currently controlled values ​​that are calculated based on the definition. +
-* **Change the attribute strategy** - if we change the strategy from 'Merge' to another, the value 'A' will again be only historical.+
  
-{{ :devel:documentation:systems:dev:controlledvalues.png |}}+{{  .:controlledvalues.png  }}
  
-Because the calculation of which values are currently controlled could be time expensive operation, are that values cached in entity **SysAttributeControlledValue** which is mapped on system mapping attribute. +Because the calculation of which values are currently controlled could be time expensive operation, are that values cached in entity **SysAttributeControlledValue**  which is mapped on system mapping attribute. That persisted 'cache' is evicted when definiton for that attribut is changed on the role (SysRoleSystemAttribute).
-That persisted 'cache' is evicted when definiton for that attribut is changed on the role (SysRoleSystemAttribute).+
  
-The evicted cache is **recalculated** by using the **AttributeControlledValuesRecalculationTaskExecutor** task, which is run after each save of attribute mapping on a role. In this case, this task recalculates the cache for all evicted attributes of the provisioning mapping.+The evicted cache is **recalculated**  by using the **AttributeControlledValuesRecalculationTaskExecutor**  task. This task recalculates the cache for all evicted attributes of the provisioning mapping.
  
-{{ :devel:documentation:systems:dev:controlledvaluestask.png |}}+<note important>Since version **9.7.5**  is recalculation of evicted attribute **not starts on save a attribute**  (SysRoleSystemAttribute)! Attribute on the system is **marked as evicted only**. Recalculation will be processed during first using of controlled values. This is typically on first **update provisioning**. **Beware**  if new account is created and create provisioning is executed, then recalculation is not executed, because in this situation are controlled values not needed!</note>
  
-**Cache recalculation with this task can be started manually**. At this startup, you must specify the system identifier and entity type (the 'IDENTITY' is filled in as default). It is also possible to deselect **onlyEvicted**. In this case, all attributes for that mapping will be recalculated even if their cache is not marked as evicted. +<note important>The merge attribute value must be a **constant**. For performance reasons, all system merge values are cached and this cache is recalculated only if the corresponding **role attribute changes**! **If the value is dynamic, the cache will not contain the correct data!**</note>
-Second situation when is cache recalculated is during provisioning. If the attribute is still marked as evicted.+
  
-Therefore, in a situation where the resulting value of the merged attribute from **IdM** is **[A,B]** and the value of the same attribute on the end system is **[C,D]**, then the end system attribute will gain the value of **[A,B,C,D]** after provisioning.+{{  .:controlledvaluestask.png  }}
  
-Let us continue with the previous case, where the value **[A,B,C,D]** is on the end system. If we remove the role which was defining value **B** in IdM, then the value on the end system must be **[A,C,D]** after provisioning. We will then remove only the value which we are managing.+**Cache recalculation with this task can be started manually**. At this startup, you must specify the system identifier and entity type (the 'IDENTITY' is filled in as default). It is also possible to deselect **onlyEvicted**. In this case, all attributes for that mapping will be recalculated even if their cache is not marked as evicted. Second situation when is cache recalculated is during provisioning. If the attribute is still marked as evicted. 
 + 
 +Therefore, in a situation where the resulting value of the merged attribute from **IdM**  is **[A,B]**  and the value of the same attribute on the end system is **[C,D]**, then the end system attribute will gain the value of **[A,B,C,D]**  after provisioning. 
 + 
 +Let us continue with the previous case, where the value **[A,B,C,D]**  is on the end system. If we remove the role which was defining value **B**  in IdM, then the value on the end system must be **[A,C,D]**  after provisioning. We will then remove only the value which we are managing.
  
 **In our case we have the following information at our disposal:** **In our case we have the following information at our disposal:**
Line 216: Line 236:
 By comparing these values, we can deduce that we have to remove value **B**, so that the result is value **[A,C,D]**. By comparing these values, we can deduce that we have to remove value **B**, so that the result is value **[A,C,D]**.
  
-An advantage of this approach is the ability of detecting **dynamic changes** as well. This means that if we don't remove the role which assigned value **B**, but instead we change the calculation definition of this value, so that the result is **X**, then it follows from the above mentioned that we are able to correctly identify that we want to send value **[A,X,C,D]** to the end system.+An advantage of this approach is the ability of detecting **dynamic changes**  as well. This means that if we don't remove the role which assigned value **B**, but instead we change the calculation definition of this value, so that the result is **X**, then it follows from the above mentioned that we are able to correctly identify that we want to send value **[A,X,C,D]**  to the end system.
  
-<note tip>**A simple way** of how to verify which attributes (values) were "wishes" in IdM and which were actually sent to the end system can be seen in the provisioning archive (**Audit / Provisioning / Archive**)</note>+<note tip>**A simple way**  of how to verify which attributes (values) were "wishes" in IdM and which were actually sent to the end system can be seen in the provisioning archive (**Audit / Provisioning / Archive**)</note>
  
 <note important>Final values merge from roles is set, **all duplicates will be removed**. For example: if you have two roles with merge mapping for same attribute and value for this attribute is same, to end system will be send only one.</note> <note important>Final values merge from roles is set, **all duplicates will be removed**. For example: if you have two roles with merge mapping for same attribute and value for this attribute is same, to end system will be send only one.</note>
Line 226: Line 246:
 {{tag>merge skip exclude contract}} {{tag>merge skip exclude contract}}
  
-Since version **9.7.0** was added new feature enabling skip of value defined in merge attribute, if contract (on witch is role assigned) will be excluded.+Since version **9.7.0**  was added new feature enabling skip of value defined in merge attribute, if contract (on witch is role assigned) will be excluded.
  
 For enable this feature you need to check the option **'Skip value when contract is excluded'**. For enable this feature you need to check the option **'Skip value when contract is excluded'**.
  
 **Value will be skipped only if**: **Value will be skipped only if**:
-  - Attribute has strategy type sets to **MERGE** or **AUTHORITATIVE_MERGE** (only for this options will checkbox shows). + 
-  - Feature is **enabled** on the role mapping. +  - Attribute has strategy type sets to **MERGE**  or **AUTHORITATIVE_MERGE**  (only for this options will checkbox shows). 
-  - Identity has assigned this role/s to the **excluded contract/s**. If identity has assigned more same roles on different contracts, then for skipping of the value must be **all** connected contracts excluded.+  - Feature is **enabled**  on the role mapping. 
 +  - Identity has assigned this role/s to the **excluded contract/s**. If identity has assigned more same roles on different contracts, then for skipping of the value must be **all**  connected contracts excluded.
  
 <note important>**If all roles which defines the account will have skipped values, then account will not be deleted!**</note> <note important>**If all roles which defines the account will have skipped values, then account will not be deleted!**</note>
  
-{{ :devel:documentation:systems:dev:skip_m.png |}}+{{  .:skip_m.png  }}
  
 ==== Additional characteristics of strategies ==== ==== Additional characteristics of strategies ====
  
-Aside from a strategy, every attribute can also have the indications **Always send** and **Send only if IdM value exists**. These indications can be combined with all strategies.+Aside from a strategy, every attribute can also have the indications **Always send**  and **Send only if IdM value exists**. These indications can be combined with all strategies. 
 + 
 +  * **Always send**  - Ensures that the attribute will be sent to the end system even when it has been assessed that its value hasn't changed. 
 +  * **Send only if IdM value exists**  - Ensures that the attribute will be sent only when the calculated IdM value has some value (if it is a String type value, it cannot be blank). This setting ensures that the IdM system doesn't delete attribute values on the end system when it can't calculate them. 
 +==== Mapping priority (since 14.7.0, 15.1.0) ==== 
 + 
 +By default, during provisioning, a schema attribute can only be mapped once. However, in some cases, it would be useful to define multiple different mappings that would be used in various scenarios (e.g., we want to send 'pwdLastSet' always when the password is changed, but also during provisioning outside of a password change if the password is expired). 
 + 
 +The solution to this need is the introduction of a '**Mapping priority**' attribute. It is possible to create multiple mappings for the same schema attribute, provided they differ in priority. If multiple mappings satisfy the other conditions, the one with the lowest priority will be used. In the case of 'pwdLastSet', the configuration would be as follows: 
 + 
 +   - A mapping with priority 0, which has both 'Include on password change' and 'Include only when password is changed' checked. In the transformation script to the system, 'pwdLastSet' will always be set – this ensures provisioning of this attribute whenever the password is changed. 
 +  - A mapping with priority 1, which is not limited to password changes. In the transformation script to the system, 'pwdLastSet' will be set if the password is expired, otherwise, it will return null – this ensures provisioning in case of an expired password. When the password is changed, this mapping will not be used (and therefore, the password expiration will not be considered), because the mapping with priority 0 will be used.
  
-  * **Always send** - Ensures that the attribute will be sent to the end system even when it has been assessed that its value hasn't changed. 
-  * **Send only if IdM value exists** - Ensures that the attribute will be sent only when the calculated IdM value has some value (if it is a String type value, it cannot be blank). This setting ensures that the IdM system doesn't delete attribute values on the end system when it can't calculate them. 
  
-  
-   
  • by svandav