IdStory IdM 16.0 - Full version overview

Target audience for this page: administrators and advanced users of the application. Technical details of the upgrade (libraries, deployment) are covered by separate technical documentation.

IdM 16 completes the transition to the new approval engine, which was introduced in IdM 15 alongside the original workflow system (Activiti). The original system has been completely removed in IdM 16 - all approvals now run exclusively on the new engine and are configured in the graphical interface of the application, not by deploying BPMN files and setting configuration properties. The second fundamental change is that IdM 16 supports PostgreSQL only.

Before you start the upgrade - mandatory steps

1. Settle all running approvals of the old (Activiti) type. Let the approvers finish their tasks, or cancel the requests. After the upgrade, such requests would remain permanently in the "In progress" state. Approvals already running on the new engine continue after the upgrade without interruption.
2. PostgreSQL. If you run IdM on MS SQL, the database must be migrated to PostgreSQL before the upgrade. The embedded database for the first start is no longer available.
3. Configure approvals using the new approval engine. The approval configuration from IdM 15 (role criticality mapped to workflows in the configuration, the helpdesk/manager/security steps) is not migrated. However, the complete version of the new workflow engine has been available since IdM 15 - the recommended approach is therefore to migrate fully to the new approval processes while still on IdM 15; the upgrade preserves that configuration.
4. Map out synchronizations with a custom workflow. Synchronizations that had a custom workflow selected for a situation (Linked / Unlinked / Missing entity / Missing account) will only perform the standard action after the upgrade - the custom behaviour has to be converted into a script (see News).
5. Export the approval history if you need it for evidence. The history of approvals performed by the old system (who decided, when and how) will no longer be available in the application - the data remains only in the database (the act_hi_* tables). Prepare your audit outputs before the upgrade.
6. Record any custom configuration tied to the old approval system. On the first application start after the upgrade, IdM permanently removes authorization policies that use the removed workflow evaluators, database record-count monitoring configured over the removed Activiti services, and delegations of type approve-role-by-manager-delegation-type. The cleanup cannot be reversed. Every deleted record is written to the application log at WARNING level and remains traceable in the audit. Export or document any configuration that you may need when recreating the behaviour after the upgrade.

News

Synchronization: custom synchronization behavior is now achieved in scripts

For the four synchronization situations, a script is now selected instead of a workflow (the new Synchronization script category). The script runs instead of the standard action for each processed item and has the complete context available (the account, the entity, the attributes, the synchronization configuration); it can invoke the standard action itself. Two sample scripts ship with the product:

• syncActionExample - a sample script (performs the standard action),
• syncRoleLdap - a full replacement of the former workflow for synchronizing roles/groups from AD/LDAP (role catalogue, membership, role assignment), configured by the same idm.pub.acc.syncRole.* properties as before.

A script used in a synchronization cannot be deleted by mistake - the application blocks the deletion and lists the synchronization and the system where the script is used. In the synchronization log, items handled by a script are shown with the new result type "Script executed".

Limitation: the script runs synchronously inside the synchronization run - unlike a workflow, it cannot include a human approval step.

Other

• Writing logs into the database is non-blocking - a problem with database logging no longer slows down or stalls the application (under extreme load some records in the log agenda may be dropped; the file logs are always complete).

Behaviour changes

Full transition to the new approval workflows

All approval logic is now driven solely by the new approval engine. All configuration is now done directly in the IdM GUI, in Settings → Workflows and Settings → Approval processes. The full documentation of the new approval engine can be found here: New Workflow Engine.

@since 16.1.0 The product delivers a set of workflows and approval processes which reproduce the approval by the criticality of the role, so an upgraded instance approves without anything being built by hand - see Default approval configuration.

• The configuration properties belonging to the old approval system, including idm.sec.core.wf.role.approval.*, idm.sec.core.wf.approval.*, idm.sec.core.wf.notification.*, spring.activiti.* and the other obsolete idm.sec.core.wf.* properties, were removed. There is no property-to-property replacement: approval processes are configured in Settings → Workflows and Settings → Approval processes. @since 16.1.0 the delivered default configuration reproduces approval by role criticality.
• The Criticality field on the role detail does not trigger any approval on its own - it is evaluated as a condition inside a workflow or as a condition of an approval process.
• The Approve role removal checkbox on the role detail has no effect and @since 16.1.0 it is removed altogether - approval of role removal is enabled by creating an approval process for the Remove Assigned Role Request event.
• The new workflow engine supports changing approval processes while the application is running - definitions are versioned automatically and an approval process that has already started is always finished with the original workflow version.
• IdM 16 supports only the recertification module that uses the new approvals (see Recertification (IdM 15+)).
• Workflow definitions can be imported/exported (IdM 16.1+).

Approval tasks

• The Tasks menu has two tabs (Tasks to approve (WF), All tasks (WF)) and requires the APPROVALTASK_READ permission (the default userRole role grants it). Custom roles built on the old WORKFLOWTASK_* permissions have to be adjusted - the old permission no longer grants access to anything.
• The approver has two decisions: Approve / Reject. The "return to requester" option from the old system does not exist - a rejected request has to be submitted again. By default, a justification is mandatory when rejecting (the idm.pub.workflow.task.note.required property). We expect the "return the request" functionality to come back in a later IdM 16 version.
• Bulk approve/reject actions and manual task delegation are available; the task detail shows notes from previous approval rounds and the delegation history.
• If the requester is one of the approvers of a step, the task is approved automatically. This behaviour is now global; it can be turned off using idm.sec.core.processor.approval-task-autoapprove-by-implementer-processor.enabled=false.
• If no approvers are found for a given approval step (for example they are disabled identities, or none are defined), the approval task falls to the holders of the superAdmin role, to prevent requests from being completed without approval by mistake.

Authorization policies based on the old workflow entities are no longer supported. On the first start after the upgrade, policies using the removed evaluators are deleted automatically. Product authorization policies are replaced as follows:

Notifications

• The "new task to approve" e-mail, the bulk summary and the reminders of open tasks work as before (the same templates and topics).
• E-mails tied to the old approval system are no longer sent:
  • the notification about a task of the old type (replaced by the new notification about an approval task assignment)
  • the "request has been executed on the systems" e-mail to the requester/applicant (replaced by the e-mails about the request result and account provisioning, available since IdM 15)
  • the e-mails about approval/rejection of a role definition change (no replacement)

The corresponding topics are still visible in the notification configuration, but they have no effect; they will be removed in one of the following IdM 16 versions.

Default approval configuration

@since 16.1.0 The product delivers a complete, working approval configuration - the workflow definitions and the approval processes that use them. An upgraded instance therefore approves role requests by the criticality of the role the way the removed engine did, without anybody building it by hand. In 16.0 none of this exists yet and the whole approval has to be created manually.

What the product delivers

Three workflow definitions in Settings → Workflows, deployed on every application start:

Two approval processes in Settings → Approval Processes, and a third one with the recertification module:

All three run the criticality workflow, which reproduces the mapping of the removed engine:

This is what the properties idm.sec.core.wf.role.approval.1/2/3 used to configure; criticality `0` and `4` had no property there either. The guarantor step accepts every type of guarantee, the manager step means the guarantee of the applicant's contract together with the superior in the tree structure.

The delivered workflows are read only. The application deploys them on every start and repairs a changed one back, so they cannot be edited or deleted, neither in the editor, nor over REST, nor by an import; only an archived (older) version can be removed.

A delivered approval process is created only when no process is bound to that event yet. Any existing process for the event stops it from being created - a disabled one and one of your own alike - so an upgrade never disturbs a configuration that is already in place. A process you delete is created again on the next start, so switch the default off by disabling it, not by deleting it.

What the default does not cover

• Removal of an assigned role is not approved. No process is delivered for the Remove Assigned Role Request event, even though the event itself is there and can be used. In IdM 15 this was driven by idm.sec.core.wf.role.approval.remove together with the Approve role removal checkbox on the role, and neither of the two has a successor. If you approved removals, create the process yourself - the delivered criticality workflow can be reused for it as it is.
• Changes of a business role are not approved. The Subrole Addition Request and Subrole Removal Request events have no delivered process either.
• Nothing that runs under the [SYSTEM] identity is ever approved, whatever the approval processes say - the scheduler, synchronizations, the initialization and background tasks execute their role requests directly.
• A single request can always be pushed through by the Execute without approval flag on the role request.
• With idm.sec.core.init.data.enabled=false no approval process is created at all. The workflows are deployed anyway, they are an artifact like scripts and notification templates.

Building on the default

The delivered configuration is a starting point, not a boundary.

1. Give an event the approval it does not have. Create a process in Settings → Approval Processes: fill in the name, pick the triggering event, the workflow and the order. The usual case is the removal of an assigned role.
2. Approve a part of the traffic differently. Add your own process for an event that already has the delivered one and give it a lower order. Matching processes are evaluated from the lowest order and the first one takes the change over, so the delivered process (order `1000`, deliberately last) only gets what nobody claimed before it. An order left empty means `0`, so your process wins.
3. Narrow a process down by a condition. An approval process can carry one condition, and the only one available there compares the form projection of the applicant. Everything else (criticality, catalogue, contract, the type of the target the role is assigned to) is a condition inside the workflow, on a Condition node.
4. Build your own approval graph. Copy a delivered workflow with the Duplicate workflow bulk action in Settings → Workflows and edit the copy. The copy is an ordinary workflow - its own code, its own versions, and never read only. Then point an approval process at it.

What you build from is described on the page of the New Workflow Engine: the approval node types (by user, by role, by role guarantor, by manager or guarantor, by script and others), the condition types of a Condition node, and the complete list of approvable events.

Removed features

Role import from CSV in the Extras module

@since Extras 16.1.0 The long running task Import roles from CSV (ImportRolesFromCSVExecutor) reads the "can be requested" flag from the file instead of a global parameter, checks the header of the file and fixes three parameters which did not work. Nothing has to be done before the upgrade, but review every scheduled import of roles afterwards - some of the changes alter what the same task does with the same file. The complete description of the task is on the page Roles - import data from CSV - v16.

The parameter Can be requested was replaced by a column

The global parameter Can be requested no longer exists. The flag is read from the file, from the column named in the new parameter Column with can be requested flags; the new parameter Column with disabled flags works the same way for the flag whether the role is disabled.

• The value of the removed parameter stays in the configuration of the scheduled task, but nothing reads it any more. Until you map the column, a newly created role cannot be requested - the default of the task is No, while the removed parameter was in most configurations set to Yes.
• A role which already exists is not touched at all when the column is not mapped, so the import no longer changes the flag on the roles it updates.
• When the column is mapped, the value is required in every record. A record with an empty value, or with a value other than true/false, yes/no or 1/0, is not processed and is reported as a failed item; the rest of the file is processed.

Every mapped column has to be present in the file

The task now checks the header of the CSV file before it processes the first record. When a column configured in the parameters is missing in the file, the import ends with one error which lists all the missing columns and no record is processed.

Before, such a column was silently read as an empty value. An import over a file with a missing column therefore looked successful, while it in fact only skipped the value (description, criticality), or - with the update of the given kind allowed - removed what the role had (catalogues, sub roles, guarantees). Columns which are in the file but are not configured in the parameters are ignored as before, so the file may contain any additional data.

Parameters which did not work before

Renamed parameters and the new form

The parameters Allow updating guarantee types and Allow updating guarantee role types are now Allow updating guarantees and Allow updating guarantee roles, because their names promised less than they do - both of them not only overwrite the type of a guarantee, but also remove all guarantees of the role which are not in the file. Some of the columns were renamed for consistency as well (Column with catalogue names is now Column with catalogue codes and so on). The codes of the parameters did not change, so the configuration of the scheduled tasks is kept and nothing has to be filled in again.

The form of the task is newly divided into seven sections - source file, role identification, role properties, guarantees, catalogues and relations to other roles, form attributes and assigned systems - and the parameters are ordered by them, so a parameter is somewhere else in the form than before. The grouping itself is a feature of the core and any long running task can use it.

After the upgrade - administrator checklist

• Create the approval processes (at least for assigning/changing/removing roles) - until then, role requests go through without approval. @since 16.1.0 Assigning and changing a role are covered by the delivered default, so only the removal has to be added by hand - check the criticality of the roles and the security role instead, see Default approval configuration.
• Synchronizations: find the configurations that used a workflow (the old values remain in the *_action_wf columns of the sys_sync_config table) and set a script for them.
• Delegations: recreate delegations that previously used approve-role-by-manager-delegation-type with the Default delegation for all tasks type. The old definitions are removed automatically during the first start.
• Scheduler: remove the task for deleting workflow history; for the HR processes (contract start/end/exclusion) clear the "Workflow definition" parameter - with the parameter filled in, the task finishes "successfully" but processes nothing.
• Requests: check the requests agenda with the filter set to the "In progress" state - cancel any leftovers from before the upgrade with the Delete bulk action. Check the event queue as well (Audit → Events).
• Permissions: in custom roles, replace WORKFLOWTASK_* with APPROVALTASK_*.
• Configuration: if you set idm.pub.core.workflows.wfengine.enabled=false in IdM 15, delete the property - otherwise the approval task dashboard is not displayed. The obsolete spring.activiti.* and idm.sec.core.wf.* properties have been removed and cannot configure approvals in IdM 16.
• Users: inform them that the old tabs and the links in old e-mails no longer work; they will find their tasks in the Tasks menu.
• Upgrade cleanup: review the WARNING records written during the first start. They identify the deleted authorization policies, including their roles and permissions, and deleted monitoring definitions, including their services. The removals remain traceable in the audit.
• Role import from CSV (Extras module): if you have the task Import roles from CSV scheduled, map the new column with the "can be requested" flag, check that the file contains every mapped column, and review the parameters of the guarantees and the multi value separator - see Role import from CSV in the Extras module.

Known issues

1. ⚠️ System export/import does not transfer the scripts of synchronizations. When transferring a system configuration between environments, the action script settings of the synchronization situations are silently lost (the import finishes successfully). Workaround: after every import, check and set the scripts again on the Synchronization tab of the target environment.
2. There is no overview of running workflow instances. The progress of an approval can only be followed through the task list (the "Approval process id" filter) and the notes of the approval rounds; a graphical view of the process run is not available yet.
3. Transferring workflow definitions between environments (export/import) is not supported in 16.0 - a definition has to be created manually in the target environment. @since 16.1.0 Solved: a definition, and a whole approval process together with the workflow it uses, are transferred by the standard export and import.
4. Administrators may see a "WF process" link on request details pointing to a removed page (error 404). The link will be removed/fixed.

Technology stack

Java 21, Spring Boot 4 / Spring Security 7, Hibernate 7, Tomcat 11, Jackson 3, Groovy 5; database PostgreSQL only. No visible impact for end users; for operations it mainly means a new version of the application server and the PostgreSQL requirement.