WorkflowUtils

Utility methods for workflow operations including form element handling, process instance management, and task execution.

Methods

getFormElementValue

Description:

Method	Return values	Description
getFormElementValue(Map<String, Object> context, String name)	String	Gets the value from a form element in the context.

context: The workflow context containing form elements.

name: The name of the form element to retrieve.

Example:

import com.openkm.okmflow.util.WorkflowUtils;
import java.util.Map;
import java.util.HashMap;

try {
        Map<String, Object> context = new HashMap(); // Context is a variable already injected into the context of the script execution
    String value = WorkflowUtils.getFormElementValue(context, "userName");
    System.out.println("User name: " + value);
} catch (Exception e) {
    e.printStackTrace();
}

getFormElementValueMap

Description:

Method	Return values	Description
getFormElementValueMap(Map<String, Object> context, List names)	Map<String, String>	Gets the values from multiple form elements in the context.

context: The workflow context containing form elements.

names: The list of form element names to retrieve.

Example:

import com.openkm.okmflow.util.WorkflowUtils;
import java.util.Arrays;
import java.util.Map;
import java.util.HashMap;
import java.util.List;

try {
        Map<String, Object> context = new HashMap(); // Context is a variable already injected into the context of the script execution
    List<String> names = Arrays.asList("userName", "email", "department");
    Map<String, String> values = WorkflowUtils.getFormElementValueMap(context, names);
    System.out.println("Form values: " + values);
} catch (Exception e) {
    e.printStackTrace();
}

formElementToPropertyMap

Description:

Method	Return values	Description
formElementToPropertyMap(Map<String, Object> context, String prefix, List names)	Map<String, String>	Converts form elements to a property map with a given prefix.

context: The workflow context containing form elements.

prefix: The prefix to add to property names.

names: The list of form element names to convert.

Example:

import com.openkm.okmflow.util.WorkflowUtils;
import java.util.Arrays;
import java.util.Map;
import java.util.HashMap;
import java.util.List;

try {
        Map<String, Object> context = new HashMap(); // Context is a variable already injected into the context of the script execution
    List<String> names = Arrays.asList("title", "description");
    Map<String, String> properties = WorkflowUtils.formElementToPropertyMap(context, "okp.document", names);
    System.out.println("Properties: " + properties);
} catch (Exception e) {
    e.printStackTrace();
}

convertToListFromSelectValue

Description:

Method	Return values	Description
convertToListFromSelectValue(String value)	List	Converts a semicolon-separated string into a list of strings.

value: The semicolon-separated string to convert (e.g. “one;two;three”).

Example:

import com.openkm.okmflow.util.WorkflowUtils;
import java.util.List;

try {
    String selectValue = "apple;banana;orange";
    List<String> fruits = WorkflowUtils.convertToListFromSelectValue(selectValue);
    System.out.println("Fruits: " + fruits);
} catch (Exception e) {
    e.printStackTrace();
}

convertToSelectValue

Description:

Method	Return values	Description
convertToSelectValue(List values)	String	Converts a list of strings into a semicolon-separated string.

values: The list of string values to convert.

Example:

import com.openkm.okmflow.util.WorkflowUtils;
import java.util.Arrays;
import java.util.List;

try {
    List<String> fruits = Arrays.asList("apple", "banana", "orange");
    String selectValue = WorkflowUtils.convertToSelectValue(fruits);
    System.out.println("Select value: " + selectValue);
} catch (Exception e) {
    e.printStackTrace();
}

addProcessInstanceVariable

Description:

Method	Return values	Description
addProcessInstanceVariable(Long piId, String key, Object value)	void	Adds a variable to a process instance.

piId: The process instance ID.

key: The variable name.

value: The variable value.

Example:

import com.openkm.okmflow.util.WorkflowUtils;

try {
    Long processId = 123L;
    WorkflowUtils.addProcessInstanceVariable(processId, "status", "approved");
    WorkflowUtils.addProcessInstanceVariable(processId, "priority", 5);
} catch (Exception e) {
    e.printStackTrace();
}

removeProcessInstanceVariable

Description:

Method	Return values	Description
removeProcessInstanceVariable(Long piId, String key)	void	Removes a variable from a process instance.

piId: The process instance ID.

key: The variable name to remove.

Example:

import com.openkm.okmflow.util.WorkflowUtils;

try {
    Long processId = 123L;
    WorkflowUtils.removeProcessInstanceVariable(processId, "tempValue");
} catch (Exception e) {
    e.printStackTrace();
}

getProcessInstanceVariable

Description:

Method	Return values	Description
getProcessInstanceVariable(Long piId, String key)	Object	Gets a variable value from a process instance.

piId: The process instance ID.

key: The variable name to retrieve.

Example:

import com.openkm.okmflow.util.WorkflowUtils;

try {
    Long processId = 123L;
    Object status = WorkflowUtils.getProcessInstanceVariable(processId, "status");
    System.out.println("Process status: " + status);
} catch (Exception e) {
    e.printStackTrace();
}

getProcessInstance

Description:

Method	Return values	Description
getProcessInstance(Long piId)	ProcessInstanceDTO	Gets a process instance by its ID.

piId: The process instance ID.

Example:

import com.openkm.okmflow.util.WorkflowUtils;
import com.openkm.okmflow.rest.dto.ProcessInstanceDTO;

try {
    Long processId = 123L;
    ProcessInstanceDTO processInstance = WorkflowUtils.getProcessInstance(processId);
    System.out.println("Process: " + processInstance.getName());
} catch (Exception e) {
    e.printStackTrace();
}

getProcessInstancesByProcessName

Description:

Method	Return values	Description
getProcessInstancesByProcessName(String procDefName)	List	Gets all process instances by process definition name.

procDefName: The process definition name.

Example:

import com.openkm.okmflow.util.WorkflowUtils;
import com.openkm.okmflow.rest.dto.ProcessInstanceDTO;
import java.util.List;

try {
    String processName = "DocumentApproval";
    List<ProcessInstanceDTO> instances = WorkflowUtils.getProcessInstancesByProcessName(processName);
    System.out.println("Found " + instances.size() + " instances");
} catch (Exception e) {
    e.printStackTrace();
}

getProcessDefinitionByName

Description:

Method	Return values	Description
getProcessDefinitionByName(String procDefName)	ProcessDefinitionDTO	Gets a process definition by its name.

procDefName: The process definition name.

Example:

import com.openkm.okmflow.util.WorkflowUtils;
import com.openkm.okmflow.rest.dto.ProcessDefinitionDTO;

try {
    String processName = "DocumentApproval";
    ProcessDefinitionDTO processDef = WorkflowUtils.getProcessDefinitionByName(processName);
    System.out.println("Process definition: " + processDef.getName());
} catch (Exception e) {
    e.printStackTrace();
}

runProcessDefinition

Description:

Method	Return values	Description
runProcessDefinition(Long pdId, Map<String, Object> data)	CompletableFuture	Executes a process definition asynchronously and returns the process instance ID.

pdId: The process definition ID.

data: The initial data for the process instance.

Example:

import com.openkm.okmflow.util.WorkflowUtils;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.CompletableFuture;

try {
    Long processDefId = 456L;
    Map<String, Object> data = new HashMap<>();
    data.put("initiator", "user123");
    data.put("document", "/documents/contract.pdf");

    CompletableFuture<Long> future = WorkflowUtils.runProcessDefinition(processDefId, data);
    Long processInstanceId = future.get();
    System.out.println("Started process instance: " + processInstanceId);
} catch (Exception e) {
    e.printStackTrace();
}

endProcessInstance

Description:

Method	Return values	Description
endProcessInstance(Long piId)	CompletableFuture	Ends a process instance asynchronously.

piId: The process instance ID to end.

Example:

import com.openkm.okmflow.util.WorkflowUtils;
import java.util.concurrent.CompletableFuture;

try {
    Long processInstanceId = 789L;
    CompletableFuture<Void> future = WorkflowUtils.endProcessInstance(processInstanceId);
    future.get(); // Wait for completion
    System.out.println("Process instance ended successfully");
} catch (Exception e) {
    e.printStackTrace();
}

setTaskInstanceValues

Description:

Method	Return values	Description
setTaskInstanceValues(Long piId, String taskName, String transName, Map<String, Object> data)	CompletableFuture	Sets values on a task instance and continues process execution asynchronously.

piId: The process instance ID.

taskName: The name of the task.

transName: The transition name.

data: The data to set on the task.

Example:

import com.openkm.okmflow.util.WorkflowUtils;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.CompletableFuture;

try {
    Long processInstanceId = 789L;
    Map<String, Object> taskData = new HashMap<>();
    taskData.put("approved", true);
    taskData.put("comments", "Document looks good");

    CompletableFuture<Void> future = WorkflowUtils.setTaskInstanceValues(
        processInstanceId, "ApprovalTask", "approve", taskData);
    future.get(); // Wait for completion
    System.out.println("Task values set and process continued");
} catch (Exception e) {
    e.printStackTrace();
}

getTaskInstance

Description:

Method	Return values	Description
getTaskInstance(Long piId, String taskName)	TaskInstanceDTO	Gets a task instance by process instance ID and task name.

piId: The process instance ID.

taskName: The name of the task to retrieve.

Example:

import com.openkm.okmflow.util.WorkflowUtils;
import com.openkm.okmflow.rest.dto.TaskInstanceDTO;

try {
    Long processInstanceId = 789L;
    TaskInstanceDTO task = WorkflowUtils.getTaskInstance(processInstanceId, "ApprovalTask");
    if (task != null) {
        System.out.println("Task found: " + task.getName());
    } else {
        System.out.println("Task not found");
    }
} catch (Exception e) {
    e.printStackTrace();
}

getTaskInstances

Description:

Method	Return values	Description
getTaskInstances(Long piId, String taskName)	List	Returns all historical instances of a task by name within a process instance, ordered by id ASC. Useful for recovering the actor who previously handled a task or checking how many times a task has been executed.

piId: The process instance ID.

taskName: The name of the task to retrieve.

Example:

import com.openkm.okmflow.util.WorkflowUtils;
import com.openkm.okmflow.rest.dto.TaskInstanceDTO;
import java.util.List;

try {
    Long processInstanceId = 789L;
    List<TaskInstanceDTO> tasks = WorkflowUtils.getTaskInstances(processInstanceId, "Manager approval");
    if (tasks != null && !tasks.isEmpty()) {
        for (TaskInstanceDTO t : tasks) {
            if (t.getActor() != null && !t.getActor().isEmpty()) {
                System.out.println("Previous actor: " + t.getActor());
                break;
            }
        }
    }
} catch (Exception e) {
    e.printStackTrace();
}

getCurrentTaskInstance

Description:

Method	Return values	Description
getCurrentTaskInstance(Long piId)	TaskInstanceDTO	Gets the current waiting task instance for a process instance.

piId: The process instance ID.

Example:

import com.openkm.okmflow.util.WorkflowUtils;
import com.openkm.okmflow.rest.dto.TaskInstanceDTO;

try {
    Long processInstanceId = 789L;
    TaskInstanceDTO currentTask = WorkflowUtils.getCurrentTaskInstance(processInstanceId);
    if (currentTask != null) {
        System.out.println("Current task: " + currentTask.getName());
    } else {
        System.out.println("No current task waiting");
    }
} catch (Exception e) {
    e.printStackTrace();
}

setProcessInstanceNode

Description:

Method	Return values	Description
setProcessInstanceNode(Long piId, String uuid)	void	Changes the node associated with a process instance. Updates the three variables that track the associated node: uuid, node (the full Node object), and nodeName (the last path segment).

piId: The process instance identifier.

uuid: The UUID of the new node to associate.

Example:

import com.openkm.okmflow.util.WorkflowUtils;

try {
    Long processInstanceId = 123L;
    String nodeUuid = "a3f1c2d4-5678-90ab-cdef-1234567890ab";
    WorkflowUtils.setProcessInstanceNode(processInstanceId, nodeUuid);
    System.out.println("Process instance node updated successfully");
} catch (Exception e) {
    e.printStackTrace();
}