Automatic Role Guarantor Transfer

When a role guarantor stops being able to act as a guarantor (the identity is deleted or blocked, or one of its contracts is deleted, deactivated or expires), the roles they guaranteed could be left without any active guarantor. This feature detects such situations and, before the destructive change is persisted, transfers the affected guarantees to a substitute (typically the original guarantor's manager / superior), so that every role keeps an active guarantor. Each new guarantor is then notified about the roles they became a guarantor of and why.

The transfer covers both kinds of role guarantee in CzechIdM:

• direct guarantee (IdmRoleGuarantee) - an identity is set directly as a guarantor of a role,
• guarantee role (IdmRoleGuaranteeRole) - the guarantors of a role are all holders of a configured guarantee role.

Examples:

• A team lead who is the sole guarantor of several application roles leaves the company and their identity is deleted - the guarantees move to their manager.
• An external consultant's contract expires; they were the only holder of a guarantee role used by ten business roles - the guarantee role is reassigned to the manager reachable through that contract.

A substitute is added only when removing the original guarantor would actually leave the role unguarded - i.e. the original guarantor is the last active one. (A direct guarantee is additionally always removed from an identity that becomes inactive, even when it was not the last guarantee - see Direct guarantees.) The "is there still someone else?" check considers only effective holders/guarantees:

• Direct guarantee - another guarantee counts only if its identity is valid (state VALID and not disabled).
• Guarantee role - another holder counts only if all of the following hold: the role assignment is currently valid (validFrom/validTill), it is held through a valid contract (state is null and the contract is valid by validFrom/validTill), and the holding identity is valid (state VALID and not disabled).

A contract is considered effectively active when it has no special state (not EXCLUDED / DISABLED) and is valid now (validFrom/validTill). This is the same rule the exclusivity detection uses for "valid holder", and it drives the contract-level triggers.

The identity (or identities) the guarantee is transferred to. Substitutes are resolved through a configurable system script (managers by default), with a robust fallback chain - see How a substitute is resolved.

The transfer always runs in the BEFORE phase of the triggering event (processor order CoreEvent.DEFAULT_ORDER - 100), so the live data needed to detect the last guarantor and to resolve managers still exists. Five event processors cover the situations in which a guarantor becomes inactive:

When the identity becomes inactive it is removed as a direct guarantee from every role it directly guarantees - an inactive identity must not remain a direct guarantor. This mirrors guarantee roles, which an inactive identity loses together with its role assignments.

For the subset of roles where the identity was the last active direct guarantee, a substitute is added first so the role keeps an active guarantor:

1. the substitute(s) are added as a direct guarantee of the role (if not already a guarantee), then
2. the original identity's direct guarantee is removed.

For roles that still have another active direct guarantee, the identity is simply removed - no replacement is needed.

For every guarantee role exclusively held by the original identity (resp. through the affected contract):

1. the guarantee role is assigned to the substitute(s) on the substitute's prime valid contract, via an internal role request executed immediately (without approval),
2. by gaining the guarantee role, the substitute becomes a guarantor of all owner roles that use it,
3. the original holding is removed when removeSource applies (see the table above) - direct holdings only; sub-roles are removed together with their direct role.

Substitutes for a guarantee role are resolved per source contract (the contract through which the original identity held the guarantee role) and cached, so the DB-heavy resolution runs once per source contract rather than once per guarantee role.

Substitutes are resolved by a robust fallback chain (RoleGuaranteeTransferManager.resolveSubstitutes):

1. Configured system script - run the script configured by idm.sec.core.role.guarantee.transferScript (default roleGuaranteeTransferTargets), keep only the results that are IdmIdentityDto and active (state VALID, not disabled), and never the identity being removed. If this yields a non-empty list, those are the substitutes.
2. Fallback role holders - otherwise (empty result, wrong-typed result or a script failure), use the active holders of the fallback role configured by idm.sec.core.role.guarantee.transferFallbackRole (the admin role when not configured).
3. Admin identity - if there are still none, fall back to the single admin identity.

If not even the admin identity is available, the affected roles are left without an active guarantor and an error is logged.

Contracts that elapse by date (their validTill passes without any user action) are de-provisioned by the nightly scheduled tasks. To let the transfer react before the contract's role assignments are removed, these tasks publish the EXPIRED event for each genuinely date-expired contract (state is null) right before removing its roles. IdentityContractGuaranteeTransferExpiredProcessor reacts to that event.

Two tasks must cover this, because they reach de-provisioning differently and run at different times:

After a transfer, one consolidated e-mail per new guarantor is sent, listing every role they became a guarantor of and the reason.

Template parameters:

Both properties are exposed on the role configuration agenda (RoleConfiguration).

A SYSTEM-category Groovy script that resolves the managers / superiors to whom a guarantee should be transferred.

Returns List<IdmIdentityDto> (never null). It uses IdmIdentityFilter#setManagersFor (all managers) and, when a contract is given, IdmIdentityFilter#setManagersByContract (managers through that contract).

import eu.bcvsolutions.idm.core.api.dto.filter.IdmIdentityFilter;
 
if (identity == null) {
    return java.util.Collections.emptyList();
}
 
IdmIdentityFilter filter = new IdmIdentityFilter();
filter.setManagersFor(identity.getId());
if (contract != null) {
    filter.setManagersByContract(contract.getId());
}
 
return identityService.find(filter, null).getContent();

A custom script can be configured instead (e.g. to return a fixed support team). The contract returned for an inactive contract still resolves managers, because DefaultManagersFilter enforces "valid contract managers" only when explicitly requested.

• BEFORE phase, negative order (DEFAULT_ORDER - 100) - guarantees, contracts and role assignments still exist, so the last guarantor can be detected and managers resolved.
• REQUIRES_NEW transaction - the public methods of RoleGuaranteeTransferManager run in their own transaction. Together with the try/catch in each processor this makes the transfer best-effort: it cannot mark the parent (delete / block / expiration) transaction rollback-only.
• Idempotent - assigning a guarantee/guarantee role that already exists is detected and skipped, so repeated events for the same situation do not duplicate guarantees.

Integration tests (core-impl, JUnit 4 + TestHelper):

Available since 15.15.5.