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.

Transition Properties

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"
}

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:

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

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