AutomationUtils
AutomationUtils is a Spring bean that provides type-safe access to the event context map (env) shared between automation events and automation actions/validators. When an automation event fires (e.g. Document create, Mail move, Property group set), the system populates the env map with the variables relevant to that event. Your action reads those values through AutomationUtils getters.
Not all variables are available in every event. If you call a getter for a variable that was not set by the current event, an AutomationException is thrown. Use the has*() guard methods where available, or handle the exception explicitly.
To understand which variables are available for each event, consult the Variables by automation event reference page in this documentation.
Typical automation action skeleton
An automation action injects AutomationUtils and uses it inside the execute method:
package com.openkm.plugin.automation.action;
import com.openkm.db.bean.NodeBase;
import com.openkm.plugin.PluginImplementation;
import com.openkm.plugin.automation.Action;
import com.openkm.plugin.automation.AutomationException;
import com.openkm.plugin.automation.AutomationUtils;
import org.springframework.beans.factory.annotation.Autowired;
import java.util.Map;
@PluginImplementation
public class MyCustomAction implements Action {
@Autowired
private AutomationUtils automationUtils;
@Override
public void execute(Map<String, Object> env, Object... params) throws Exception {
// Read action parameters configured in the UI
String param0 = automationUtils.getString(0, params);
// Read event context variables
NodeBase node = automationUtils.getNodeBase(env);
String name = automationUtils.getName(env);
// ... your logic here ...
}
@Override
public String getName() {
return "My Custom Action";
}
}
Action parameter methods
These methods read typed values from the params varargs array — the configurable parameters that the administrator sets for the action in the Automation UI, not from the event context.
getString
| Method | Return values | Description |
|---|---|---|
|
getString(int index, Object... params) |
String |
Returns the action parameter at the given index as a String. |
String folderPath = automationUtils.getString(0, params);
getInteger
| Method | Return values | Description |
|---|---|---|
|
getInteger(int index, Object... params) |
Integer |
Returns the action parameter at the given index as an Integer. |
Integer maxDays = automationUtils.getInteger(1, params);
getLong
| Method | Return values | Description |
|---|---|---|
|
getLong(int index, Object... params) |
Long |
Returns the action parameter at the given index as a Long. |
Long maxSize = automationUtils.getLong(0, params);
getBoolean
| Method | Return values | Description |
|---|---|---|
|
getBoolean(int index, Object... params) |
Boolean |
Returns the action parameter at the given index as a Boolean. |
Boolean sendNotification = automationUtils.getBoolean(2, params);
getList
| Method | Return values | Description |
|---|---|---|
|
getList(int index, Object... params) |
List<String> |
Returns the action parameter at the given index as a List of Strings. |
List<String> roles = automationUtils.getList(0, params);
Event context node getters
These methods read node-related variables from the event env map. Most throw AutomationException if the variable is not present in the current event context.
getNodeBase
| Method | Return values | Description |
|---|---|---|
|
getNodeBase(Map<String, Object> env) |
NodeBase |
Returns the main node involved in the event (document, folder, mail, or record). This is the primary accessor for the affected node. |
NodeBase node = automationUtils.getNodeBase(env);
System.out.println("Node UUID: " + node.getUuid());
System.out.println("Node path: " + node.getPath());
getNodeToEvaluate
| Method | Return values | Description |
|---|---|---|
|
getNodeToEvaluate(Map<String, Object> env) |
NodeBase |
Smart getter that resolves the correct node depending on the event phase. On PRE create or PRE move events it returns the destination node (the future container); in all other cases it returns the node base. Use this for validator logic. |
NodeBase nodeToEvaluate = automationUtils.getNodeToEvaluate(env);
getNodeBaseList
| Method | Return values | Description |
|---|---|---|
|
getNodeBaseList(Map<String, Object> env) |
List<NodeBase> |
Returns a list of nodes involved in bulk operations such as ZIP export. |
List<NodeBase> nodes = automationUtils.getNodeBaseList(env);
for (NodeBase n : nodes) {
System.out.println(n.getPath());
}
getDestinationNode
| Method | Return values | Description |
|---|---|---|
|
getDestinationNode(Map<String, Object> env) |
NodeParent |
Returns the destination container node for create and move events. Only available in create and move events. |
if (automationUtils.hasDestinationNode(env)) {
NodeParent dest = automationUtils.getDestinationNode(env);
System.out.println("Destination: " + dest.getPath());
}
hasDestinationNode
| Method | Return values | Description |
|---|---|---|
|
hasDestinationNode(Map<String, Object> env) |
boolean |
Returns true if the destination node variable is present in the event context. |
getSourcePath
| Method | Return values | Description |
|---|---|---|
|
getSourcePath(Map<String, Object> env) |
String |
Returns the original repository path of the node before a move operation. Only available in move events. |
if (automationUtils.hasSourcePath(env)) {
String original = automationUtils.getSourcePath(env);
System.out.println("Moved from: " + original);
}
hasSourcePath
| Method | Return values | Description |
|---|---|---|
|
hasSourcePath(Map<String, Object> env) |
boolean |
Returns true if the source path variable is present in the event context. |
getName
| Method | Return values | Description |
|---|---|---|
|
getName(Map<String, Object> env) |
String |
Returns the name of the node. On PRE create events the name can be changed by the action to rename the node before it is saved. |
String name = automationUtils.getName(env);
System.out.println("Node name: " + name);
hasName
| Method | Return values | Description |
|---|---|---|
|
hasName(Map<String, Object> env) |
boolean |
Returns true if the name variable is present in the event context. |
getMimeType
| Method | Return values | Description |
|---|---|---|
|
getMimeType(Map<String, Object> env) |
String |
Returns the MIME type of the document (e.g. |
String mime = automationUtils.getMimeType(env);
if ("application/pdf".equals(mime)) {
// ...
}
getCategories
| Method | Return values | Description |
|---|---|---|
|
getCategories(Map<String, Object> env) |
Set<String> |
Returns the set of category UUIDs assigned to the node. |
Set<String> categories = automationUtils.getCategories(env);
for (String catUuid : categories) {
System.out.println("Category UUID: " + catUuid);
}
getKeywords
| Method | Return values | Description |
|---|---|---|
|
getKeywords(Map<String, Object> env) |
Set<String> |
Returns the set of keywords assigned to the node. |
Set<String> keywords = automationUtils.getKeywords(env);
getNotes
| Method | Return values | Description |
|---|---|---|
|
getNotes(Map<String, Object> env) |
List<NodeNote> |
Returns the list of notes attached to the node. |
List<NodeNote> notes = automationUtils.getNotes(env);
getTitle
| Method | Return values | Description |
|---|---|---|
|
getTitle(Map<String, Object> env) |
String |
Returns the title metadata field of the node. |
String title = automationUtils.getTitle(env);
getVersion
| Method | Return values | Description |
|---|---|---|
|
getVersion(Map<String, Object> env) |
String |
Returns the version label of the document (e.g. |
String version = automationUtils.getVersion(env);
getCreationDate
| Method | Return values | Description |
|---|---|---|
|
getCreationDate(Map<String, Object> env) |
Calendar |
Returns the creation date of the node. |
Calendar created = automationUtils.getCreationDate(env);
getNodeClass
| Method | Return values | Description |
|---|---|---|
|
getNodeClass(Map<String, Object> env) |
Long |
Returns the node class (classification) ID of the node. Returns -1 if no node class is set or the variable is absent. |
Long nodeClass = automationUtils.getNodeClass(env);
if (nodeClass != -1) {
// node has a classification
}
getNewNodeClass
| Method | Return values | Description |
|---|---|---|
|
getNewNodeClass(Map<String, Object> env) |
Long |
Returns the new node class ID being applied during a set-node-class event. Returns -1 if absent. |
getOldNodeClass
| Method | Return values | Description |
|---|---|---|
|
getOldNodeClass(Map<String, Object> env) |
Long |
Returns the previous node class ID before a set-node-class event. Returns -1 if absent. |
Event context — document getters
getFile
| Method | Return values | Description |
|---|---|---|
|
getFile(Map<String, Object> env) |
File |
Returns the temporary local file containing the document content. Available during document create and update events. |
if (automationUtils.hasFile(env)) {
File file = automationUtils.getFile(env);
System.out.println("File size: " + file.length());
}
hasFile
| Method | Return values | Description |
|---|---|---|
|
hasFile(Map<String, Object> env) |
boolean |
Returns true if the document file variable is present in the event context. |
getInputStream
| Method | Return values | Description |
|---|---|---|
|
getInputStream(Map<String, Object> env) |
InputStream |
Returns the input stream of the document content. Available during document create and update PRE events. |
InputStream is = automationUtils.getInputStream(env);
getDocumentSize
| Method | Return values | Description |
|---|---|---|
|
getDocumentSize(Map<String, Object> env) |
long |
Returns the size of the document content in bytes. |
long size = automationUtils.getDocumentSize(env);
getTextExtracted
| Method | Return values | Description |
|---|---|---|
|
getTextExtracted(Map<String, Object> env) |
String |
Returns the full text extracted from the document. Available in the Document text extraction event. |
String text = automationUtils.getTextExtracted(env);
if (text.contains("CONFIDENTIAL")) {
// apply policy ...
}
getLanguageDetected
| Method | Return values | Description |
|---|---|---|
|
getLanguageDetected(Map<String, Object> env) |
String |
Returns the ISO 639-1 language code detected during text extraction (e.g. |
String lang = automationUtils.getLanguageDetected(env);
getTextExtractor
| Method | Return values | Description |
|---|---|---|
|
getTextExtractor(Map<String, Object> env) |
TextExtractor |
Returns the text extractor plugin instance used for the current extraction. Returns null if not present. |
Event context — mail getters
These variables are only available during mail-related events (e.g. Mail creation).
getMailFrom
| Method | Return values | Description |
|---|---|---|
|
getMailFrom(Map<String, Object> env) |
String |
Returns the sender address of the mail. |
String from = automationUtils.getMailFrom(env);
getMailReply
| Method | Return values | Description |
|---|---|---|
|
getMailReply(Map<String, Object> env) |
String[] |
Returns the reply-to addresses of the mail. |
getMailTo
| Method | Return values | Description |
|---|---|---|
|
getMailTo(Map<String, Object> env) |
String[] |
Returns the recipient addresses of the mail. |
String[] to = automationUtils.getMailTo(env);
getMailCc
| Method | Return values | Description |
|---|---|---|
|
getMailCc(Map<String, Object> env) |
String[] |
Returns the CC addresses of the mail. |
getMailBcc
| Method | Return values | Description |
|---|---|---|
|
getMailBcc(Map<String, Object> env) |
String[] |
Returns the BCC addresses of the mail. |
getMailSubject
| Method | Return values | Description |
|---|---|---|
|
getMailSubject(Map<String, Object> env) |
String |
Returns the subject of the mail. |
String subject = automationUtils.getMailSubject(env);
getMailContent
| Method | Return values | Description |
|---|---|---|
|
getMailContent(Map<String, Object> env) |
String |
Returns the body content of the mail. |
getMailSentDate
| Method | Return values | Description |
|---|---|---|
|
getMailSentDate(Map<String, Object> env) |
Calendar |
Returns the sent date of the mail. |
getMailReceivedDate
| Method | Return values | Description |
|---|---|---|
|
getMailReceivedDate(Map<String, Object> env) |
Calendar |
Returns the date on which the mail was received by the system. |
Event context — property group getters
These variables are available in property group events (Add metadata group, Set metadata group, Remove metadata group, Get all metadata groups).
getPropertyGroupName
| Method | Return values | Description |
|---|---|---|
|
getPropertyGroupName(Map<String, Object> env) |
String |
Returns the name of the property group (metadata group) involved in the event. |
if (automationUtils.hasPropertyGroupName(env)) {
String grpName = automationUtils.getPropertyGroupName(env);
}
hasPropertyGroupName
| Method | Return values | Description |
|---|---|---|
|
hasPropertyGroupName(Map<String, Object> env) |
boolean |
Returns true if the property group name variable is present in the event context. |
getPropertyGroupProperties
| Method | Return values | Description |
|---|---|---|
|
getPropertyGroupProperties(Map<String, Object> env) |
Map<String, String> |
Returns the property key-value map being set on the node during the event. The map key is the property field name; the value is the new field value. |
if (automationUtils.hasPropertyGroupProperties(env)) {
Map<String, String> props = automationUtils.getPropertyGroupProperties(env);
String invoiceNumber = props.get("okp:invoice.number");
}
hasPropertyGroupProperties
| Method | Return values | Description |
|---|---|---|
|
hasPropertyGroupProperties(Map<String, Object> env) |
boolean |
Returns true if the property group properties map is present in the event context. |
getPropertyGroups
| Method | Return values | Description |
|---|---|---|
|
getPropertyGroups(Map<String, Object> env) |
Map<String, String> |
Returns a map of all property groups assigned to the node, keyed by group name with their current serialized state. |
getAllPropertyGroups
| Method | Return values | Description |
|---|---|---|
|
getAllPropertyGroups(Map<String, Object> env) |
List<PropertyGroup> |
Returns all property group definitions available in the system (not just those assigned to the node). Available in Get all metadata groups events. |
Event context — task manager getters
getTaskId
| Method | Return values | Description |
|---|---|---|
|
getTaskId(Map<String, Object> env) |
long |
Returns the ID of the task involved in the event. Available in task create, update, and delete events. |
long taskId = automationUtils.getTaskId(env);
getTaskManagerTask
| Method | Return values | Description |
|---|---|---|
|
getTaskManagerTask(Map<String, Object> env) |
TaskManagerTask |
Returns the full task object involved in the event. |
TaskManagerTask task = automationUtils.getTaskManagerTask(env);
System.out.println("Task name: " + task.getName());
Event context — user and session getters
getUser
| Method | Return values | Description |
|---|---|---|
|
getUser(Map<String, Object> env) |
DbUser |
Returns the user object involved in the event. Available in user create, login, and logout events. |
DbUser user = automationUtils.getUser(env);
System.out.println("User ID: " + user.getId());
getTenant
| Method | Return values | Description |
|---|---|---|
|
getTenant(Map<String, Object> env) |
long |
Returns the tenant ID in a multi-tenant deployment. |
getHttpServletRequest
| Method | Return values | Description |
|---|---|---|
|
getHttpServletRequest(Map<String, Object> env) |
HttpServletRequest |
Returns the HTTP request associated with the event. Returns null if the event was not triggered by an HTTP request (e.g. background/cron tasks). |
HttpServletRequest request = automationUtils.getHttpServletRequest(env);
if (request != null) {
String ip = request.getRemoteAddr();
}
getHttpServletResponse
| Method | Return values | Description |
|---|---|---|
|
getHttpServletResponse(Map<String, Object> env) |
HttpServletResponse |
Returns the HTTP response associated with the event. Returns null if not in an HTTP context. |
getAuthentication
| Method | Return values | Description |
|---|---|---|
|
getAuthentication(Map<String, Object> env) |
Authentication |
Returns the Spring Security Authentication object for the user that triggered the event. Returns null if not available. |
Event context — note getters
getNoteText
| Method | Return values | Description |
|---|---|---|
|
getNoteText(Map<String, Object> env) |
String |
Returns the text of the note involved in a note create, update, or delete event. Returns null if not present. |
String noteText = automationUtils.getNoteText(env);
if (noteText != null) {
System.out.println("Note: " + noteText);
}
Event type helper methods
These methods inspect the current event to help actions make branching decisions without hard-coding event names.
getEvent
| Method | Return values | Description |
|---|---|---|
|
getEvent(Map<String, Object> env) |
AutomationRule.EnumEvents |
Returns the current event enum value, such as |
AutomationRule.EnumEvents event = automationUtils.getEvent(env);
if (event == AutomationRule.EnumEvents.EVENT_DOCUMENT_CREATE) {
// ...
}
getEventAt
| Method | Return values | Description |
|---|---|---|
|
getEventAt(Map<String, Object> env) |
String |
Returns |
isPreEvent
| Method | Return values | Description |
|---|---|---|
|
isPreEvent(Map<String, Object> env) |
boolean |
Returns true if the action is running in the PRE phase (before the operation completes). In PRE phase some variables (e.g. name) can be modified to alter the outcome of the operation. |
if (automationUtils.isPreEvent(env)) {
// Can still intercept and modify the operation
}
isMoveAction
| Method | Return values | Description |
|---|---|---|
|
isMoveAction(Map<String, Object> env) |
boolean |
Returns true if the current event is a move event for any node type (document, folder, mail, or record). |
isCreationAction
| Method | Return values | Description |
|---|---|---|
|
isCreationAction(Map<String, Object> env) |
boolean |
Returns true if the current event is a create event for any node type (document, folder, mail, or record). |
isDocumentCreateFromTemplate
| Method | Return values | Description |
|---|---|---|
|
isDocumentCreateFromTemplate() |
boolean |
Returns true if the document being created originates from a template (createFromTemplate call). Inspects the call stack; no parameters needed. |
if (automationUtils.isDocumentCreateFromTemplate()) {
// skip: document was created from a template, not uploaded by the user
return;
}
isFolderCreateFromTemplate
| Method | Return values | Description |
|---|---|---|
|
isFolderCreateFromTemplate() |
boolean |
Returns true if the folder is being created as part of a template instantiation. |
isRecordCreateFromTemplate
| Method | Return values | Description |
|---|---|---|
|
isRecordCreateFromTemplate() |
boolean |
Returns true if the record is being created as part of a template instantiation. |
