Transition

Overview

Transitions are the connecting elements that define the flow paths between workflow nodes. They establish the execution sequence and routing logic that determines how a workflow progresses from one node to another. Every transition must connect a source node to a target node, creating the directional flow that controls workflow behavior.

Caution

All transitions must be connected to both a source node and a target node. A workflow cannot contain transitions that do not fulfill this requirement. Incomplete transitions will cause workflow execution errors.

Transition Properties

Property	Type	Description
Name	Text	The name of the transition. This property is: - Optional: When a node has only one outgoing transition, naming is recommended but not required - Mandatory: When a node has multiple outgoing transitions, each transition must have a unique name. The workflow uses these names to determine which path to follow based on the return value from Decision nodes or Action nodes with routing logic. May exist several transitions with the same name in the workflow, but outgoing from a node, each transitions must have its own name.
Type	Dropdown	Determines the visual representation of the transition in the workflow diagram. Available types: - Default: Standard transition line - Step: Step-style transition line - Smooth Step: Rounded step-style transition line - Straight: Straight line transition The type only affects visual appearance and does not change transition behavior.
Animated	Checkbox	When enabled, the transition line blinks in the workflow diagram, creating a visual animation effect. This is useful for highlighting important flow paths or transitions that represent critical workflow routes.
Color	Color Picker	Defines the color of the transition line in the workflow diagram. Color coding helps users visually identify different workflow paths and their purposes. Common practices include: - Green: Success paths or approval flows - Red: Error paths or rejection flows - Blue: Standard processing paths - Yellow: Warning or conditional paths
Script definition	Code Editor	Optional Groovy script that executes when the workflow traverses this transition. The script has access to the workflow context and can perform actions similar to Action nodes. However, unlike Action node scripts, transition scripts should not return a string value since the transition path is already determined at this point in execution.

Transition Naming Requirements

Single Outgoing Transition

When a node has only one outgoing transition, the transition name is optional. The workflow automatically follows the single available path without requiring name-based routing.

Multiple Outgoing Transitions

When a node has multiple outgoing transitions (common with Decision nodes or Action nodes with routing logic), each transition must have a unique name. The source node’s script returns a string that matches the name of the transition to follow.

Example: Decision Node with Multiple Transitions

// Decision node script
if (approvalRequired) {
    return "approved";  // Follows transition named "approved"
} else {
    return "rejected";  // Follows transition named "rejected"
}

Note

Transition names are case-sensitive. Ensure that the string returned by Decision or Action node scripts exactly matches the transition name, including capitalization.

Transition Scripts

Transitions can execute Groovy scripts during workflow traversal. These scripts have access to the workflow context and can perform operations such as:

• Updating context variables
• Calling OpenKM API methods
• Setting document metadata
• Logging workflow events
• Performing data transformations

Script Context Access

Transition scripts have access to the same context variables as Action nodes:

• context - Map of workflow context variables
• processInstance - Current ProcessInstance object
• initiator - Actor who started the workflow
• processDefinition - ProcessDefinition object
• uuid - Document UUID (if workflow started from a document)
• node - OpenKM node object (Document, Folder, Mail, or Record)

Key Difference from Action Nodes

While transition scripts can perform similar operations to Action node scripts, there is a critical difference:

Caution

Transition scripts should NOT return a string value to control routing. Unlike Action nodes and Decision nodes, transitions are already executing along a determined path. The workflow cannot branch to a different transition at this point. Any return value from a transition script will be ignored.

Example: Transition Script

This example demonstrates a transition script that sets document metadata when the workflow follows a specific path:

import com.openkm.sdk4j.impl.OKMWebservices;
import com.openkm.sdk4j.bean.*;
import com.openkm.okmflow.util.*;
import com.openkm.okmflow.bean.*;
import com.openkm.bean.form.*;
import com.openkm.util.*;
import java.util.*;

OKMWebservices ws = WebservicesHelper.getInstance();
Class baseLibrary = ScriptUtils.evaluateFromNode("library_global_base");
def invoiceNumber = baseLibrary.getContextValue(context, "invoice_number");
def total = baseLibrary.getContextValue(context, "total");
def uuid = baseLibrary.getContextValue(context, "uuid");

Map<String,String> properties = new HashMap();
properties.put("okp:invoice.number", invoiceNumber.getValue());
properties.put("okp:invoice.total", total.getValue());
ws.propertyGroup.setProperties(uuid, "okg:invoice", properties);

This script:

1. Retrieves invoice-related variables from the workflow context
2. Obtains the document UUID
3. Creates a property map with invoice metadata
4. Updates the document’s property group with the metadata values

When to Use Transition Scripts vs Action Nodes

Use Case	Recommended Approach	Reason
Conditional routing logic	Action Node or Decision Node	These nodes are designed for branching logic and return values that determine the transition to follow
Complex business logic	Action Node	Action nodes provide better visibility, debugging, and separation of concerns
Simple data transformation	Either	Can use transition scripts for lightweight operations, but Action nodes offer better maintainability
Path-specific operations	Transition Script	When an operation should only occur when a specific path is taken, transition scripts are appropriate
Metadata updates on approval	Transition Script	Updating document properties when following an “approved” transition is a valid use case

Tip

Best Practice: Prefer Action nodes over transition scripts for most scripting needs. Transition scripts should be reserved for operations that are specific to a particular workflow path and must execute during transition traversal.

Visual Design with Transitions

Type Selection

Choose transition types based on visual clarity and diagram organization:

Field / Property	Appearence	Description
Default		General-purpose transitions for most workflows
Step		Useful for workflows with horizontal or vertical node arrangements
Smooth Step		Provides a more polished appearance with rounded corners
Straight		Best for direct, short-distance connections between nodes

Color Coding Strategy

Implement a consistent color scheme across workflows:

• Success paths: Green transitions for approvals, completions, and positive outcomes
• Error paths: Red transitions for rejections, failures, and error handling
• Standard paths: Blue or gray transitions for neutral processing steps
• Conditional paths: Yellow or orange transitions for warning conditions

Animation Usage

Use animated transitions sparingly to highlight:

• Critical approval paths that require special attention
• Error or exception handling routes
• Unusual or rarely-taken workflow branches
• Paths that trigger important business processes

Best Practices

• Name all important transitions: Even when optional, naming transitions improves workflow readability and maintainability
• Use descriptive names: Choose names that clearly indicate the transition’s purpose (e.g., “approved”, “rejected”, “needs_review”)
• Maintain naming consistency: Use a consistent naming convention across all workflows
• Avoid complex transition scripts: Keep transition scripts simple or use Action nodes for complex logic
• Document color meanings: Establish and document a color scheme for transitions in workflow documentation
• Test multi-path scenarios: Thoroughly test workflows with multiple outgoing transitions to ensure correct routing
• Validate transition names: Ensure Decision and Action node return values match transition names exactly
• Use visual cues effectively: Combine color, animation, and naming to make workflow paths intuitive
• Keep scripts focused: Transition scripts should perform operations specific to that path, not general workflow logic
• Log transition execution: Use FileLogger in transition scripts to track which paths the workflow follows

Common Pitfalls

• Missing transition names: Forgetting to name transitions when multiple paths exist from a node
• Name mismatches: Case-sensitive name mismatches between node return values and transition names
• Returning values from transition scripts: Attempting to control routing from a transition script (which doesn’t work)
• Disconnected transitions: Creating transitions without both source and target connections
• Overusing animation: Animating too many transitions, which reduces the effectiveness of the visual indicator
• Inconsistent naming: Using different naming conventions across similar transitions in the same workflow

Note

Transitions are fundamental to workflow flow control. Well-designed transitions with clear naming, appropriate visual styling, and focused scripts contribute significantly to workflow maintainability and user understanding.