This agenda contains all requests (wishes) for requested changes of authorized identities. The main idea is that all changes in identities' permission must go through this agenda. Therefore, it is not intended only for end users' requests but for automatic operations (synchronization, automatic roles, etc.) as well.

The standard scenario of a permission change is as follows:

1. A user requests a change in their set of permissions.
2. They presse the "Change permission" button in the "Assigned roles" tab.
3. A new request (in "CONCEPT" state) is created automatically. The detail of this new request is shown to the user.
4. All the assigned roles which the user has are displayed in the table of concepts "Currently assigned roles (including requested changes)". The user can make the changes over this table (see more in Concept table)
5. All the requested changes of permission are displayed in the table "Requested permission changes".
6. The user presses the button "Make a request".
7. If the request is not evaluated as duplicate, its execution is performed (the state is set to "IN_PROGRESS").
8. Subsequently, the event "RoleRequestEventType.EXCECUTE" is called out.
9. Ordinarily, this event is firstly captured by the processor "role-request-approval-processor", which starts the approval workflow (calls the method IdmRoleRequestService.startApprovalProcess). In the default state, the workflow with the definition "approve-identity-change-permissions" is started. The key of the definition which is to be started can be changed in the application configuration by adding the key "idm.sec.core.processor.role-request-approval-processor.wf", (the value will be the key of the requested definition).
10. After a successful approval, the workflow process calls out the event "RoleRequestEventType.EXCECUTE" again (it continues with the event with which it has been started).
11. Ordinarily, the event is then captured by the processor "role-request-realization-processor", which provides the realization of the event itself. The processor calls the method IdmRoleRequestService.executeRequest(requestId), which performs the application of all role concepts which are in the "APPROVED" or "CONCEPT" states (the concept state is realized due to the situation when the realization processor is called out immediately after making the request, i.e. approval is disabled).
12. The user is assigned roles according to the requested changes.

There are two ways of how to make a change in permissions without approval.

As mentioned above, after submitting a request, an event is called out which is captured by the "role-request-approval-processor". If we disable this processor, all submitted requests will be realized immediately without any approval.

A request for permission change contains attribute "executeImmediately". If this attribute is set to "true", the request will be executed immediately after submitting it. A submission without approval can be executed only by users having permission "ROLEREQUEST_EXECUTEIMMEDIATELY". If an event marked in this way is executed by a user without this permission, an exception will be called out.

During the process of submitting a request, it is verified if there is another duplicate request of the new request (in state "IN_PROGRESS", "APPROVED"). If a duplicate request is found, the executed request is labelled as duplicated (state "DUPLICATED") and its attribute "duplicatedToRequest" is filled with the identifier of the duplicate request (a record is made in the request log). The submission (execution) of the request is thus suspended.

A duplicate request is such a request with equivalent:

• applicants.
• individual role concepts (identical role type, identical validity from/to, identical link IdentityRole).
• a request note (the user can define their request only in this note).

A request can be removed completely only in "CONCEPT" state. If it is in "EXECUTED" state, every attempt to remove it ends in exception "ROLE_REQUEST_EXECUTED_CANNOT_DELETE". If it is in "APPROVED, IN_PROGRESS, EXCEPTION, DUPLICATED" states, the request is set to "CANCELED" state. If a process is tied to the request, the process is terminated (subsequently a record about this is made in the request log).

A situation when the end user creates a request for permission change from their profile has been described above. For administrators, it is convenient to use the "Role requests" agenda, which provides an overview of all requests in the system. All requests in all states are displayed in this agenda (including those already executed).

The agenda allows a direct request submission from a list of requests. The agenda also allows creating a new request, where the administrator must first choose the user who the request is being created for.

In addition, the request detail in this agenda contains (compared to the end user request detail) a possibility of ticking that the request is not to be approved. The request detail also contains a log. This log contains all crucial information which occur during the life cycle of the request (errors, duplicates, request cancellation due to integrity, executed operations, etc.).

When role or contract (using in the some concept) is deleted and workflow process for that concept is not ended, the must be that process terminated. We cannot use standard 'cancel' of subprocess, because this operation does not triggered the main process.

For prevent this situation is concept's subprocess not cancelled, but disapproved ( on delete role or contract).

Role requests can be initiated automatically by IdM, most commonly by LRT. Before IdM 15.6.0, the Requester field of such system-initiated requests remained empty.

Starting with IdM 15.6.0, it is possible to configure a System Requester – an identity that will be automatically assigned as the Requester for role requests created by the system (e.g., by LRT) when no explicit user is associated with the request.

This behavior is controlled by the configuration property: idm.sec.core.roleRequest.systemUser

• If this property contains a valid UUID of an identity, IdM uses that identity as the Requester for all automatically triggered role requests.
• If the property is empty, contains an invalid UUID, or the identity does not exist, IdM falls back to selecting the administrator (an identity with the super admin role) as the Requester.

If the request-permission-change-without-approval mode is not used, process "approve-identity-change-permissions" will be started. This process ensures the approval of the request as a whole and its base implementation is composed of these parts:

1. Process name generating (the applicant's name will also be stated in the name)
2. Approval by the helpdesk department.
3. Approval by the manager of the applicant.
4. Approval by the user administration department.
5. Execution of subprocesses for each requested role.
6. Approval of role incompatibilities
7. Approval by the security department.
8. Sending the notification.
9. Realization of the request - the realization itself is not carried out by the process, but by the service for managing requests for permission change.

The role request has a status item that identifies whether the request has already been executed. The Executed state in this case means that the request has been approved and the changes have been executed in IdM. This state only reflects the state in IdM.

This status does not cover a situation where some of the assigned roles create an account on a system. In this case, it may be important for the user to know the exact time the account was successfully created. Alternatively, if there is an error on the system, it is good to know this information in the role request itself.

Some of the provisioning operations is not completed.

This is typically a situation where the connector (target system) is waiting to process the operation.

Second situation when could be request in running state is if role assign the virtual system.

If the request assign or changes an account on the virtual system, then the virtual system creates a request by default, pending implementation by the appropriate implementer. Our request to change roles will be in a running state until all possible requests on virtual systems are resolved. The purpose of this wait is to ensure that the final notification of the completion of the request is sent after the real implementation of the requirements on the systems representing the virtual systems.

In this situation has system state RUNNING orange color and show message: Some requests on this vritual systems [Name of vritual systems] are not resloved!.

If the request contains pending virtual system requests, the 'status on the systems' will be set to executed only if all virtual system requests will be resolved. This means that they will either be successfully approved or will be rejected by implementer. If the virtual system request is rejected, the status on the request item will be set to CANCELED.

Some of the provisioning operations failed.

This is typically a situation where the connector throw an exception. If you click on the status, you will see information on which systems have failed.

If the request contains an error, the status on the systems will be set to executed only if all errors are resolved. This means that they will either be successfully executed (for example by retry mechanism) or will be canceled. If the operation is canceled, the status on the request item will also be set to CANCELED.

On the detail of a request that has provisioning errors, the roles that connect the system to which the error occurred are marked with a specific error.

If one role assigns more than one system and an error occurs on both, error for only one system will be displayed.

If the entire request contains only one provisioning error, the log of that error is displayed on the request detail (Error log from a systems).

Some of the provisioning operations were blocked.

This is typically a situation where some system has blocked write operations. The behavior in this case is very similar to the case when the provisioning operation is in the error. If you click on the status, you will see information which systems are blocked.

If the request contains a blocked operations, the status on the systems will be set to executed only if all blocked operations will be resolved. This means that they will either be successfully executed or will be canceled. If the operation is canceled, the status on the request item will also be set to CANCELED.

This state is very similar to the case when the provisioning operation is blocked. Occures where system is seta to read only mode.

Role is allowed to be deleted only if it is not assigned to any identity. This requirement is checked during prevalidation process and user is informed about this. Another provided information pertains to the number of role request concepts from which a reference to the deleted role needs to be removed. This additional information is for user useful because deletion of even single role which was previously assigned to many (assume hundreds) identities may take long time. This warning is currently displayed if number of request concepts to modify exceeds 100 items. Images below are only for illustration and don't take this into account.

Results of actions connected with the process of role removal are still possible to see in Audit tab. We can see here that role deletion was accompanied with role removal from 4 role request concepts.

In the provisioning operations agenda, all operations that were created under a given request have a link to that request (key icon).

Similarly in the agenda of virtual system's requests, all requests that were created under a given role request have a link to that request (key icon).

These notifications are sent when the application is fully completed.

Two notifications are sent, one to the author of the request and the other to whom the request changes permissions. The notification contains a list of all directly changed roles (ie does not include business roles). Roles are displayed in three tables according to the type of operation they performed with the role (assignment, modification, deletion).

The notification also contains a column "Problems on systems". This column is filled only if there is a problem on the system that assigns the role. Typically, this column may contain a value of "Canceled" to indicate that the provisioning operation has been canceled or the request has been rejected on the virtual system.

Name of email templates:

• ``changeIdentityRoleImplementer``
• ``changeIdentityRole``

Name of topics:

• ``core:roleRequestRealizedApplicant``
• ``core:roleRequestRealizedImplementer``

Role requests use two distinct state enums that should not be confused:

• Status in IdM – represented by RoleRequestState, describes the lifecycle of the request as a whole inside IdM (creation, approval, execution in IdM).
• Status on systems – represented by OperationState (stored in the systemState attribute), describes the outcome of the provisioning operations triggered by the request on the target systems (AD, LDAP, virtual systems, etc.).

A request can be EXECUTED in IdM while its system state is still RUNNING, EXCEPTION or BLOCKED – the realization in IdM was successful, but provisioning on the systems is not yet finished. See System state section above for details on how Status on systems behaves.

This is the overall state of the role request inside IdM. Some states are terminated – the request lifecycle has reached its end and the request cannot be processed any further (it can only be removed if it is in CONCEPT state, otherwise it stays as a historical record).

This is the aggregated state of all provisioning operations created by the request on target systems. The value is stored in the systemState attribute of the role request and is only relevant when the request actually changes a role that assigns an account on some system. If the request does not touch any system, Status on systems stays empty.

For implementers, OperationState provides two utility methods:

• isRunnable() – returns true for CREATED and RUNNING (the operation can still run or is currently running).
• isSuccessful() – returns true only for EXECUTED.

Both are also available as static variants: OperationState.isRunnable(state) and OperationState.isSuccessful(state).