Workflow definitions and approval processes

Page ID and namespace are not decided yet - fix the internal links below before publishing.

An approval process decides whether a request (assignment of a role, change of an assigned role, recertification, …) has to be approved and by whom. It binds three things together: the event that triggers it, the workflow definition that describes the approval graph, and an optional condition that narrows down when it applies.

Since IdM 16 the product uses its own workflow engine (agenda Workflows) instead of Activiti. IdM 16.1 adds a set of workflow definitions and approval processes that are delivered with the product, so that an upgraded instance keeps approving role requests the way it did before the engine was replaced.

Compatible with the product from the version stated above.

• Workflow definition - the approval graph: nodes (start, condition, approval, end), their ports and the edges between them. Stored in the agenda Workflows.
• Approval process (IdmBusinessProcess) - configuration record that says "when event X happens, run workflow Y". It carries the triggering workflow event type, the workflow, an optional named condition, the order and a disabled flag.
• Named condition - a condition attached to one approval process. It belongs to that process only and is created and removed together with it.
• Workflow instance - one run of a definition. Instances keep the version of the definition they started with.

@since 16.1.0 Three workflow definitions ship inside the product and are deployed on every application start:

A workflow delivered with the product is managed by the application. It cannot be changed and it cannot be deleted - not through the user interface, not over REST and not by an import. The editor opens it in a read only mode: no palette, no Save, the fields are greyed out, a node cannot be moved or deleted. Clicking a node still shows its properties, read only.

The deployment compares the shipped content with what is in the database and acts per workflow:

An unchanged workflow is deliberately not saved again: a save of a definition that has instances creates a new version (see below), so writing on every start would produce a new version per restart. The comparison uses the content of the graph - its natural keys, node attribute values and edges. The layout is not part of it, so moving a node in the editor is not a content change.

The deployment runs as an initialization processor (core-init-system-workflow-processor). An enabled initialization processor that fails prevents the application from starting - that is the standard behaviour and it is intentional here: an instance without the shipped workflows would silently approve nothing. Data situations the processor recognises (an ambiguous code) are answered with a warning instead.

If starting without the shipped workflows is preferred, disable the processor in the configuration:

# Deployment of the workflows delivered with the product
idm.sec.core.processor.core-init-system-workflow-processor.enabled=true

A definition that has no instance is updated in place. A definition that has an instance is versioned by copy on write:

• the current row is archived and keeps its graph, so running instances still see what they started with,
• a new row is created with the same code, the same version group and the version increased by one,
• approval processes that referenced the old version are re-pointed to the new one.

Archived versions therefore share the code with the current one by design. Deleting a definition that has instances archives it as well, it does not remove it.

@since 16.1.0 The code of a current (not archived) workflow definition is unique. Everything that resolves a workflow by its code - the deployment above, the default approval processes, pairing of an import - expects exactly one row, and before 16.1 two current definitions could share a code even through the user interface.

The rule is enforced twice: by a partial unique index in the database (ux\_wfe\_definition\_code, only over rows that are not archived) and by a validation in the service, so a client gets a readable error (WORKFLOW\_CODE\_NOT\_UNIQUE) instead of a constraint violation.

A definition without a code is allowed and is not checked - the graph can be built before the code is filled in.

@since 16.1.0 The bulk action Duplicate workflow in the agenda Workflows creates an independent copy of the selected definitions, including the whole graph. The copy:

• gets new identifiers - the definition and every node, port and edge,
• gets the first free code in the form `<original code>_1`, `_2`, … and the name with ` (1)` appended,
• starts its own group of versions at version one, so it is a new workflow and not another version of the original,
• is never a workflow delivered with the product, even when the original is.

A definition can be exported and imported through the standard export and import batches. Two things are specific to this agenda:

• Pairing. An imported definition is paired with an existing one by code, so an import updates the workflow of the same code instead of creating a second one.
• References travel as natural keys. Node types, referenced roles and script codes are exported by their code and resolved in the target environment, because their identifiers differ per instance.

An import cannot change a workflow delivered with the product and cannot grant that flag either. An import of an unchanged shipped workflow is a no operation.

Approval processes live in the agenda Business processes. Each one binds a triggering event to a workflow.

@since 16.1.0 After an upgrade the product creates the approval configuration an instance had before the engine was replaced:

A process is created only when it is missing. An existing configuration is never changed, so an administrator can replace the default or switch it off.

Approval processes are started in the order given by the order column, and the first process that reaches a concept of the request claims it - a later process is not started for the same concept. The processes delivered with the product therefore use the order `1000`, so that a process created by an administrator (order `0` unless it is filled in) always wins.

An approval process can carry a named condition that decides whether the process applies at all (for example only for identities with a given form projection). The condition belongs to its process: it is created with it and @since 16.1.0 removed with it, including its extended attributes.

@since 16.1.0 The code of an approval process is unique. The database has enforced it since the agenda was introduced, but a reused code ended as an internal error - now it is refused with BUSINESS\_PROCESS\_CODE\_NOT\_UNIQUE.

When the triggering event of a process is not known to the application - typically after a module was uninstalled - the process is ignored, a warning is logged and the requests of other events are not affected. The same holds for a process whose workflow no longer exists.

In the application profile (application.properties) - overloadable via ConfigurationService.

# Product initialization data. The default approval processes are init data, so they are
# not created when this is switched off. The shipped workflows are deployed regardless -
# they are an artifact, like scripts and notification templates.
# @since 16.1.0
idm.pri.core.init.data.enabled=true
 
# Deployment of the workflows delivered with the product
# @since 16.1.0
idm.sec.core.processor.core-init-system-workflow-processor.enabled=true
 
# Creation of the default approval processes
# @since 16.1.0
idm.sec.core.processor.core-init-business-process-processor.enabled=true

• A workflow delivered with the product can still be selected into the delete bulk action. The server refuses the item, so the workflow survives and the item ends as failed with the localized reason. This is a limitation of the selection, not a defect.
• The user interface saves the whole definition with a single POST - there is no partial update of a graph.

• Content comparison - WfeDefinitionContentSignature expresses the content of a definition by its natural keys, so two definitions can be compared regardless of their identifiers. The layout is deliberately outside the signature.
• Portable references - references that differ per instance are exported as natural keys and resolved back on import. A new kind of reference has to be added there, otherwise an exported workflow does not survive the transfer.
• Initialization - InitSystemWorkflowProcessor deploys the shipped batch, InitBusinessProcessProcessor creates the default approval. A module that ships its own default approval follows the second one (see the module rec) and reuses IdmBusinessProcessService.DEFAULT\_APPROVAL\_WORKFLOW\_CODE and DEFAULT\_APPROVAL\_PROCESS\_ORDER.

• A workflow delivered with the product can still be selected into the delete bulk action. The server refuses the item, so the workflow survives and the item ends as failed with the localized reason. This is a limitation of the selection, not a defect.
• The user interface saves the whole definition with a single POST - there is no partial update of a graph.

• Content comparison - WfeDefinitionContentSignature expresses the content of a definition by its natural keys, so two definitions can be compared regardless of their identifiers. The layout is deliberately outside the signature.
• Portable references - references that differ per instance are exported as natural keys and resolved back on import. A new kind of reference has to be added there, otherwise an exported workflow does not survive the transfer.
• Initialization - InitSystemWorkflowProcessor deploys the shipped batch, InitBusinessProcessProcessor creates the default approval. A module that ships its own default approval follows the second one (see the module rec) and reuses IdmBusinessProcessService.DEFAULT\_APPROVAL\_WORKFLOW\_CODE and DEFAULT\_APPROVAL\_PROCESS\_ORDER.

• The whole initialization runs in ONE transaction. An exception from any initialization processor rolls the whole event back, so a per item try and catch does not isolate anything. This is why the deployment refuses to write on a code it cannot resolve unambiguously.
• An eventable service needs its delete processor. IdmNamedConditionService publishes a delete event and the row is removed by IdmNamedConditionDeleteProcessor. Without such a processor a delete is a silent no operation - no exception and nothing deleted.
• Archiving has to reach the database before the new version is inserted. A new version carries the code of the original, and Hibernate executes inserts before updates within one flush, so the insert would meet a row that is not archived yet and collide with the unique index of the code.
• A read only property is invisible in both directions of a round trip. systemWorkflow is serialized but never deserialized, so reading a response back into the DTO always yields `false`. Assert such a property against the raw json.

• The workflows and the default approval processes delivered with the product are present in every test context. A test that builds its own approval configuration has to clear the existing one first, otherwise the shipped process claims the concept and the own process is never started.
• A fixture that sits on a shipped identifier or holds a shipped code needs its own clean up - the clean up by the flag does not find an unflagged row, and an unflagged row with a shipped code is adopted by the next test.
• The long running task is synchronous in the test profile, so a refused item of a bulk action marks the shared transaction rollback only and the whole action ends with a transaction error. In production the task runs asynchronously and every item gets its own transaction.