====== Account management (ACM) ======
{{tag> account management uid identity ACM}}


The aim of the account management is to create accounts in the IdM internal warehouse (AccAccount entity) in such a form in which they should be created (according to the IdM settings) on end systems.
The account management therefore does not do the provisioning itself but it is its indicator in most cases. 

<note tip>The account management defines how the account should look like (according to IdM) on end systems</note>
===== Basic account management =====
The **basic** account management is using for all entities supports the **provisioning**. Identity have more complex account management using the **roles** assignments.

If the entity supports basic account management, then is executed method **ProvisioningService.accountManagement** after it is created/updated.

Method **ProvisioningService.accountManagement** ensure:
  - Finds all systems with the provisioning mapping for this entity type.
  - Generats account identifier `uid` for this entity.
  - For all found systems check if account with same `uid` already exists. If yes, then this method ends.
  - For all found systems check if his mapping has the script '**Can be account created?**'. If is script filled, then is executed. If script returns `Boolean.FALSE`, then account on this system will be not created (this method ends).
  - Account on the system is created (AccAccount).
  - Relation between created account and entity are created too.  

<note important>Basic account management does not provide **delete** of accounts for now. Only allows their **creation**.</note>

==== Script - Can be account created? ====
  * This script can be defined on the system provisioning mapping.
  * Is executed before any IdM account (AccAccount) is created (for identity type are executed too).
  * Ensure if will be some IdM account on the system created. 
  * This script returns `Boolean.TRUE` (for create the account) or `Boolean.FALSE` (for not create the account).

=== Script example - role catalogue===
We will now show how we can use the script.
Situation: 
  * We have system configured for provisioning IdM role (IdmRole) to the target system.
  * Now we want to allow create accounts only for role wich are in the specific role catalogue.

Solution:
    - We need to know how check if is role in the specific catalogue. For this we can use script **Is role in the catalogue?** defines in the file [[https://github.com/bcvsolutions/CzechIdMng/blob/develop/Realization/backend/core/core-impl/src/main/resources/eu/bcvsolutions/idm/scripts/CoreIsRoleInCatalogue.xml|CoreIsRoleInCatalogue.xml]].
    - Fill out the script in the system mapping. You can use insert script button. Result scirpt should looks something like this:

    return scriptEvaluator.evaluate(
    scriptEvaluator.newBuilder()
        .setScriptCode('IsRoleInCatalogue')
        .addParameter('scriptEvaluator', scriptEvaluator)
        .addParameter('catalogueCode', 'SYSTEM-A')
        .addParameter('role', entity).build());

    
Where:
  * '**role**' defines IdM role which we testing. 
  * '**catalogueCode**' defines code of role catalogue for which we allow create the account.

<note tip>Only for role which will be in the catalogue with code 'SYSTEM-A' will be created the account in IdM.</note>

{{ :devel:dev:acm-role-system.png |}}


===== Identity account management =====
The account management is run depending on the event that can have an impact on the change of the account on the end system:
  * The event of the creation/modification/deletion of an identity.
  * The event for creating/modifying/deleting the assigned role to a given identity.
  * The event for creating/modifying the definition of mapping the attributes for a role.

The identity account management is ensured by the service [[https://github.com/bcvsolutions/CzechIdMng/blob/develop/Realization/backend/acc/src/main/java/eu/bcvsolutions/idm/acc/service/api/AccAccountManagementService.java|AccAccountManagementService]] with the following methods:
  * boolean **resolveIdentityAccounts**(IdmIdentityDto identity) - will evaluate the account for this identity depending on the roles that are currently assigned to it. Returns true if it is requested to do provisioning.
  * **deleteIdentityAccount**(IdmIdentityRoleDto identityRole) - will delete the accounts created within the assignment of this role.
  * String **generateUID**(AbstractDto dto, SysRoleSystem roleSystem) - will generate a UID for the identity and the system. If there are overloaded attributes for UID, they are used, if not, the default attribute for UID is used.

<note tip>Identity account management uses script '**Can be the account created?**' too.</note>

==== Forward identity account management ====

**By default**, if we have a contract that is valid in the future, and I assign a role to this contract (assigning a system), this assigned role will be discarded (not currently valid) during account management. That is, no accounts will be created on the end systems. This behavior is the default and the correct one.

In some cases, however, we need to create an account on the end system before the given contract is valid (for example when a new employee enters). As a solution to this requirement **forward identity account management** was created.

<note>This can be activated by checkbox '**Forward account management**' on detail of mapping system to a role. **If is checked**, then an **account on this system is created** even though the assignment of this role to the user will be valid in the future.</note>

{{ :devel:documentation:accounts:dev:forwardacm.png |}}


===== Example of account life cycle =====

We have a provisioning mapping system and a primary attribute (marks as **Is identifier**). In this attribute, we will have a transformation into the system, the output of which will be the **username** with the postfix **@idm.eu**.

  - Assign a role to this system to, for example, user **john-doe**.
  - An internal account (AccAccount) will be created in IDM, where the value of this account (UID) will be **john-doe@idm.eu**.
  - After an internal account is created, provisioning will be made on the end system. This creates a new account **john-doe@idm.eu** on the end system.
  - If there is a change in the way the IDM of the account ID is being created. For example, the script will change so that postfix will be new **@czechidm.eu**, then ** john-doe@czechidm.eu** will be returned during the provisioning from the primary attribute. This new value will also be stored in your account ID (AccAccount.uid).

 <note important> Some systems (** LDAP **) can generate own the ** primary account ID **. If the system returns a different identifier than the one in the IDM account (AccAccoutn.uid), then this value is stored in ** SysSystemEntity.uid **. When communicating with the system, this ** identifier **! is always used</note>


<note tip> If the output from primary attribute is **null**, then the ** SysSystemEntity.uid ** as account ID (UID) is automatically used. </note>

=====Name of account in IDM=====
Name of account is in IDM stored in the entity **AccAccount** (field **UID**). 
This name is an internal account name and is particularly important when account management is executed but provisioning has not yet. At this point, the account name is the only account identifier.
After a end system is called (provisioning), SysSystemEntity is created (updating) and contains the account identifier returned by the system. This identifier may be different from the one stored in ** AccAccount.uid **, and it always takes precedence over communication with the end system.

<note important> If the name of account generated by IDM is changed (during the Account management), then it will be updated. </note>

During synchronization from the end system to IDM, an internal IDM account (AccAccount) is also created. In this case, an attribute identified as an identifier is used to generate the account name. A transformation from the system is called for this.

<note important>If the account name in AccAccount.uid differs from the generated one during synchronization, it will update it.</note>

=====Incremental account management and provisioning=====
{{tag>incremental account management ACM provisioning}}

<note tip>Supported since version **9.6.0**.</note>

For optimization reasons, **incremental account management** has been implemented. This allows assign or modify roles to the identity so that the necessary calculations are performed **only for the assigned/modified roles** of that identity. 

**Incremental provisioning** is closely related to incremental account management. This ensures that **provisioning is made only for the accounts touched**. This means that if a user has multiple different accounts (**A**, **B**) and an additional role is assigned (that assigns the same **A** account), then account management and provisioning is performed only for **A** (not **B**).

<note>If the identity is saved, provisioning is still made **for all assigned accounts**.</note>

<note important>**Differently from previous versions**, editing / adding / removing a single assigned role does **not recalculate all assigned roles** and related accounts of a identity! If you need to perform account management for the entire identity, then use the bulk operation **Recalculate accounts and provision**. This operation is available on the table of all users.</note>