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.

Note

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.

Tip

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	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	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. application/pdf). Available in document events.

String mime = automationUtils.getMimeType(env);
if ("application/pdf".equals(mime)) {
    // ...
}

getCategories

Method	Return values	Description
getCategories(Map<String, Object> env)	Set	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	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	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. 1.0, 1.1). Available in document update events.

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. en, es). Available in the Document text extraction event.

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	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 EVENT_DOCUMENT_CREATE or EVENT_MAIL_MOVE.

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 AutomationRule.AT_PRE or AutomationRule.AT_POST indicating whether the action is running before or after the operation completes.

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.