New Workflow Engine

IdStory IDM version 15+ includes a proprietary workflow implementation for use in approval processes. The goal is to enable administrators to configure approval processes easily and flexibly, with full control over the sequence and conditions of approval steps. Auditability and robustness of the entire process are ensured.

The main user benefits of the new workflow engine are:

• Configurable approval workflows for all entities in IdM (core ones are already implemented and can be extended through development)
• Centralized approval management in one place within IdM
• Bulk approval or rejection capabilities
• Notes available at each step to ensure full audit transparency
• Summary notifications for new tasks and reminders for current ones instead of dozens of individual emails
• User-friendly filtering and organization of tasks awaiting my approval or tasks I am waiting for others to approve
• Gradual transition from legacy approval processes
• Clear and centralized configuration of approvals for easy administration
• Built-in safeguard to prevent unintended “self-approval” even in case of misconfiguration of approvers

There are the following 3 new agendas

• Tasks (WF)
• Settings > Workflows
• Settings > Approval Processes

The workflow agenda serves to create definitions for individual workflows. A workflow defines a sequence of steps in the approval process using visual programming nodes, where each node represents one step of the approval process by a specific group (or individual) of approvers. The sequence of steps is visually displayed in the workflow definition and edited directly in the IDM editor.

Each node in the approval process has a specific type, and depending on the type, may have additional attributes. The result of each node’s evaluation is an output state (e.g., “approved” or “rejected”), which leads to the next node in the approval process.

The screenshot of the worklfow editor in IdM shows a sample workflow usable for role assignemnt, where the first step is approving by the manager. The next step depends on the criticality of the role being assigned. If the criticality is 1 or 0, there is no further approval step. If the criticality is 2 or higher, there is a second step approved by the role guarantor.

Nodes are the basic "steps" that you can combine to create a workflow. This section describes the available types and their uses.

Control nodes are not approval steps themselves but govern the evaluation of the approval process:

• Start - The workflow begins here; no approval step is defined.
• End - The workflow ends here with successful approval; no further approvable step is defined.
• Condition - Defines a condition in the approval process that evaluates to TRUE or FALSE, allowing for branching. It contains attributes:
  • Condition Type
  • Left Operand
  • Right Operand
  • Operator

• Role Attribute
• Guarantor Type Existence - compares the existence (or non-existence) of a role guarantor of the specified type.
• Role Criticality - compares the criticality value of the role with a numeric value.

Approval nodes define a specific approval step with a set of approvers (could be a single approver). If the WF engine does not find anyone in the set of approvers (e.g., because no one has an assigned role), the approval task is automatically created for the administrator (login: admin).

• Approval by Identity - The node defines a specific identity that approves in the given step.
• Approval by Role - The node defines a specific role representing the approvers in this step, considering role hierarchy (e.g., if the role is assigned as subordinate). Only valid/active users are considered.
• Approval by Role Guarantor - For role change/removal/addition approval, the set of approvers corresponds to the guarantor of the specified role.
  • Includes an attribute to select only a guarantor of a particular type (guarantee-type).
• Approval by Script - The set of approvers is calculated by a Groovy script, which must return a list of identities.
• Approval by Supervisor/Guarantor of Identity - The set of approvers is the supervisor or guarantor of the identity requested for approval.
• Approval by Superior Role Guarantor - For business role change (subrole addition or removal), the set of approvers is the set of guarantors of the superior role.
  • Includes an attribute to select only a guarantor of a particular type (guarantee-type).
• Approval by Sub Role Guarantor - For business role change (subrole addition or removal), the set of approvers is the set of guarantors of the subrole.
  • Includes an attribute to select only a guarantor of a particular type (guarantee-type).

An approval process assigns a workflow to a specific event in IdM that requires approval. The system allows the same workflow to be used repeatedly for multiple events; however, some types of approval nodes (e.g., approval by role guarantor) can only be used with specific approval processes (e.g., those concerning role assignments).

Each approval process includes:

• Name - A human-readable name identifying the approval process.
• Code - A machine-readable and unique identifier for the approval process.
• Event - The event to which the approval process is applicable. See the Approvable Events section for which events are supported.
• Selected Workflow - Specifies the predefined workflow used for an event that meets the filter condition.
• Order - Approval processes are evaluated based on this order (from lowest to highest), always using the first approval process that matches the event (event and condition).
• Condition - An approval process may contain a condition that restricts the events for which it applies; currently, only a condition on identity type (projection) is supported.

Approval processes can be managed by an admin (controlled by IdM permissions) in the approval process agenda where:

• All active approval processes are visible.
• Approval processes can be deleted, created, or edited.

The example below sets up a process to approve role assignment with a workflow called "Security workflow".

In the current IdM version, approval processes can be configured using both old workflows and the new system. In such cases, users will see two task agendas (Tasks and Tasks WF), each handling tasks from the respective approval processes.

Properties that enable showing both agendas are idm.pub.core.workflows.legacy.enabled and idm.pub.core.workflows.wfengine.enabled (by default true for IdM 15)

A role change request can include multiple different changes - removal, addition, modification of individual roles. Each change creates its own instance of an approval workflow = process, according to the applicable approval process rules.

In the approval process, individual users approve or reject tasks. The request is executed = roles are assigned in IdM only after all approval processes are completed (approved or rejected). After the request is executed, provisioning to systems follows, and only approved changes are implemented.

When an event happens, that has approval process defined for it, the IdM proceeds as follows:

1. IdM takes a snapshot of the workflow definition, that will be used for all approval steps for this event. This prevents workflow changing mid-approval having hard to predict consequences.
2. IdM evaluates the first step in the workflow and calculates a list of identities for approvers of the first step.
3. If the list of approvers is empty, IdM assigns superAdmin identity as the approver
4. If the applicant is one of the approvers, IdM marks the step as "autoapproved" with corresponding comment.
5. IdM waits for the task to be approved/rejected by user input
6. IdM moves to next step based on the result - if there is no step to continue into, the approval process ends with REJECTED. If IdM reached the end, approval process ends with APPROVED.

It is possible to aggregate notifications for new approval tasks, so that instead of getting one notification per new approval task, the users now get a regular notification (with configurable frequency) that lists all approval tasks on their person. The notification only comes if they recerived new approval tasks since the last notification.

To configure the notification, you need to:

• Disable the individual notification by disabling the topic core:wfAssignedTaskNotificationMessage
• Plan the scheduled task NewApprovalTaskBulkNotificationTaskExecutor
• Ensure that you have the topic core:wfAssignedTaskBulkNotificationMessage active and that you have a template for it
  • The default template looks like so:

<html>
  <body>
    Dobrý den,<br />
    <br />
    #if($tasks.size() == 1)
      byl Vám přiřazen nový schvalovací úkol:
    #else
      byly Vám přiřazeny nové schvalovací úkoly:
    #end
    <br />

      <table style="border-collapse: collapse; border: 1px solid #dddddd; margin: 15px 0;">
          <tr><th style="font-weight: bold; border: 1px solid #dddddd; padding: 5px 10px;">Schvalovací úkol</th></tr>
          #foreach( $task in $tasks )
              <tr><td style="border: 1px solid #dddddd; padding: 5px 10px;"><a href='$task.getUrl()'>$esc.xml($task.getTaskNameCs())</a></td></tr>
          #end
          #if($restCount> 0)
        #if($restCount <5)
                <tr><td>a $restCount další</td></tr>
            #else
              <tr><td style="border: 1px solid #dddddd; padding: 5px 10px;">a $restCount dalších</td></tr>
            #end
          #end
      </table>

    Celkově máte $totalCount
    #if($totalCount == 1)
      úkol
    #elseif($totalCount <5)
      úkoly
    #else
      úkolů
    #end
    ke schválení, dokončete
    #if($tasks.size() == 1)
      ho,
    #else
      je,
    #end
    prosím, v systému CzechIdM. Zobrazit
    #if($tasks.size() == 1)
      ho
    #else
      je
    #end
    můžete <b><a href='$url'>zde</a></b>.
    <br />
    <br />
    S pozdravem BCV Solutions s.r.o.
    <br />
    <br />
    -------------------------------------------------------------------------------------<br />
    Hello,<br />
    <br />
    You have been assigned new
    #if($tasks.size() == 1)
      task
    #else
      tasks
    #end
    for approval:
    <br />

      <table style="border-collapse: collapse; border: 1px solid #dddddd; margin: 15px 0;">
          <tr><th style="font-weight: bold; border: 1px solid #dddddd; padding: 5px 10px;">Task for approval</th></tr>
          #foreach( $task in $tasks )
              <tr><td style="border: 1px solid #dddddd; padding: 5px 10px;"><a href='$task.getUrl()'>$esc.xml($task.getTaskNameEn())</a></td></tr>
          #end
          #if($restCount> 0)
            <tr><td style="border: 1px solid #dddddd; padding: 5px 10px;">and $restCount more</td></tr>
          #end
      </table>

    You have a total of $totalCount
    #if($totalCount == 1)
      task
    #else
      tasks
    #end
    for approval. Please complete
    #if($totalCount == 1)
      it
    #else
      them
    #end
    in the CzechIdM system. You can access
    #if($totalCount == 1)
      it
    #else
      them
    #end
    <b><a href='$url'>here</a></b>.
    <br />
    <br />
    Regards BCV Solutions Ltd.
    <br />
    <br />
  </body>
</html>

Use this evaluator if you want to grant the user permission to all role requests for which they have been the approver of at least one approval task created by the given role request.

The main use case for this evaluator is to allow the approver to go from the detail of their approval task to the detail of its associated role request.

The assignment of READ permission for role requests via this evaluator is configured within the user role initialization, so the main use case is covered automatically.

Please note that the RoleRequestByWfInvolvedIdentityEvaluator (without the "new") does not work properly for the new workflow engine.

It is possible to create a regularly scheduled long running task to remind people about their assigned and still running approval tasks.

The long running task can send the notifications either to the approvers themselves or to their managers - the topics for those two notifications can be set independently.

The long running task sends one (or two - if configured to send it both to approvers and their managers) notifications for every user that has at least one running approval task with age between the minimum number of days and maximum number of days (both boundaries are inclusive). Inside this notification, at most [tasksToSend] of those tasks are listed.

- minimum days open: how long at least an approval task has to be open to be included in the notification.

- maximum days open: how long at most can an approval task be open to be included in the notification.

- tasks to send: how many tasks are listed in the notification itself (the rest are only mentioned as "and X more")

- notify approvers: whether or not the notification should be sent to the approvers

- notify managers: whether or not the notification should be sent to the managers of the approvers

- topic for approvers: topic for the approver notification, the task will expect a notification configuration with this topic and level INFO

- topic for managers: topic for the manager notification, the task will expect a notification configuration with this topic and level INFO

- tasks: list of running tasks with age within minimum days and maximum days - contains at most [tasksToSend] items

- url - url to the list of the user's tasks - in approver notification only

- taskCount - count of all running tasks within the specified timespan

- restCount - count of running tasks within the specified timespan not included in 'tasks' (taskCount - numberOfTasksInNotification)

- totalCount - count of all running tasks (regardless of age) assigned to the user

- approver - the approver assigned to the tasks in this notification

- min days - how long at least an approval task has to be open to be included in the notification

- max days - how long at most can an approval task be open to be included in the notification

If you want to configure a way to notify the approvers with increasing level of urgency, it is possible to set up multiple non-overlapping reminder tasks such as:

- First long running reminder task with minimum days open 7, maximum days open 13 and a custom topic for low urgency reminder that only notifies the approver.

- Second long running task with minimum days open 14, maximum days open 20 and a custom topic for medium urgency reminder that only notifies the approver but the notification mentions that next week the manager will be notified.

- Third long running task with minimum days open 21, no maximum days open and two custom topics for high urgency reminders - one for the approver and one for their manager.

Note that for this to work there have to be notifications configurations for all of the topics with the NotificationLevel INFO. There doesn't have to be any notification configuration for the 'none' topic - any value in the topic field for which the checkbox is left unchecked will be ignored as no notification is sent with that topic.