Action node

Overview

The Action node enables automated execution of custom logic within the workflow. When the workflow reaches an Action node, it executes a script that can perform various operations such as managing context variables, calling the OpenKM API, or executing any custom business logic. Unlike Task nodes that require human interaction, Action nodes execute automatically without pausing the workflow.

Node Properties

DescriptionTextarea

Optional field for providing additional details or documentation about the action’s purpose and the logic it executes.

Property	Type	Description
Name	Text	The name that identifies this Action node. This name should clearly describe the action being performed (e.g., “Add invoice metadata”, “Calculate total”, “Update document properties”).
Id	Number	Unique identifier assigned to the node. This value is automatically generated by the system and uniquely identifies the node within the process definition.
Source position	Dropdown	Defines the position from which outgoing transition arrows exit the node. Available options: Top, Bottom, Left, Right.
Target position	Dropdown	Defines the position where incoming transition arrows enter the node. Available options: Top, Bottom, Left, Right.
Script definition	Script Editor	Contains the script code that will be executed when the workflow reaches this node. The script has full access to the workflow context, variables, and the OpenKM API. The editor can be accessed in two ways: - Textarea: Edit directly in the textarea field - Popup editor: Click the icon above the textarea to open a larger editing window The editor supports autocomplete functionality. Press Ctrl+Space while typing to display available options and code suggestions.

Caution

Important: The Source position and Target position cannot have the same value. For example, if Source position is set to “Bottom”, Target position cannot also be “Bottom”.

Common Use Cases

Action nodes are commonly used for the following operations:

• Managing context variables: Create, update, or delete variables in the workflow context
• Adding metadata: Set document properties and metadata using the OpenKM API webservices
• Performing calculations: Execute business logic and store results in context variables
• External API calls: Integrate with external systems and services
• Document operations: Create, move, copy, or modify documents programmatically
• Conditional routing: Determine the next workflow path based on logic (optional decision capability)

Optional Decision Capability

While Action nodes primarily execute logic, they can optionally function as Decision nodes. If the script returns a string value, the workflow will use that value to determine the next transition path, similar to how a Decision node operates.

Note

When an Action node returns a string, that string must match the name of one of the outgoing transitions. If it doesn’t match, the workflow execution will fail. This feature allows Action nodes to both execute logic and control workflow routing in a single step.

Script Example

The following example demonstrates an Action node that adds metadata to a document and optionally routes to different transitions based on the invoice total:

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);

// Optional (works as decision node)
int totalValue = Integer.parseInt(total.getValue());
if (totalValue > 1000) {
  return "supervisor";
} else {
  return "go";
}

This script performs the following operations:

1. Retrieves context variables: Gets the invoice number, total, and document UUID from the workflow context
2. Prepares metadata: Creates a Map with the property group fields to be set
3. Calls OpenKM API: Uses the webservices to set the metadata properties on the document
4. Optional routing: Evaluates the invoice total and returns either “supervisor” (if total > 1000) or “go” (if total ≤ 1000)

Tip

The return statement at the end is optional. If you remove it, the script will simply execute the metadata operations and continue to the next node without conditional routing. This makes Action nodes very flexible - they can perform operations with or without controlling the workflow flow.

Context Variables Access

Action node scripts have full access to all workflow context variables. You can:

• Read existing variables using helper methods or directly from the context
• Create new variables by storing values in the context
• Modify existing variable values
• Delete variables when they’re no longer needed

Variables are typically accessed through library helper methods (as shown in the example above) or directly through the workflow execution context object.

OpenKM API Integration

One of the most powerful features of Action nodes is the ability to interact with the OpenKM API. Common API operations include:

• Document operations: Create, update, delete, move, or copy documents
• Metadata management: Set or get property group values
• Folder operations: Create or manage folder structures
• Search operations: Query documents based on metadata or content
• Note operations: Add notes or annotations to documents

The OKMWebservices object (obtained via WebservicesHelper.getInstance()) provides access to all OpenKM API functionality.

Best Practices

• Use descriptive names that clearly indicate what action is being performed
• Add detailed descriptions to document complex logic, especially when scripts are long or intricate
• Handle exceptions appropriately to prevent workflow failures
• When using the optional decision capability, ensure all possible return values match existing transition names
• Test scripts thoroughly with different data scenarios before deploying to production
• Keep scripts focused - if an action becomes too complex, consider breaking it into multiple Action nodes
• Use library functions for common operations to promote code reuse and maintainability
• Document the expected context variables in the Description field