Mail node

Overview

The Mail node sends email notifications to one or more recipients as part of the workflow process. This node executes automatically without pausing the workflow, delivering emails through the OpenKM SMTP service. It supports context variables and HTML formatting, making it ideal for notifying users about workflow events, document updates, or task assignments.

Node Properties

Context Variables

The Mail node supports context variables in the Recipients, Subject, and Body fields using the ${variable} syntax. Variables are evaluated at runtime and replaced with their current values from the workflow context.

Common Context Variables

• ${initiator.email} - Email address of the workflow initiator
• ${initiator.name} - Full name of the workflow initiator
• ${node.path} - Path of the document/node that started the workflow (if applicable)
• ${uuid} - UUID of the document that started the workflow (if applicable)
• Custom variables created by Task forms or Action nodes (e.g., ${emails}, ${subject}, ${message.value})

Recipients

The Recipients field accepts email addresses separated by comma ",". You can specify recipients in two ways:

1. Direct email addresses: user1@example.com,user2@example.com,user3@example.com
2. Context variable: ${emails} (variable must contain semicolon-separated email addresses)

Subject

The Subject field supports plain text and context variables. Use variables to create dynamic subject lines that reflect the current workflow state:

• New Document Notification
• ${subject}
• Task Assignment: ${taskName}
• Document ${docName} requires your review

Body

The Body field provides a rich text editor that generates HTML content. You can use formatting tools to create professional emails with:

• Text formatting (bold, italic, underline)
• Paragraphs and headings
• Lists (ordered and unordered)
• Links and images
• Tables
• Context variables using ${variable} syntax
• FreeMarker template expressions for conditional logic and loops

FreeMarker Support

The Body field supports FreeMarker template language, allowing you to include conditional content, loops, and other advanced templating features:

• Conditional content: <#if condition>...<#else>...</#if>
• Null checks: <#if variable??>...</#if>
• Loops: <#list items as item>...</#list>

Example: Document Notification Email

This example demonstrates a complete email notification that uses context variables and FreeMarker expressions:

Hi
I would like to inform you that there is a new document that may be of interest to you.

If you have any comments, you can contact me by email: ${initiator.email}
<strong>The document: ${node.path}</strong> <a href="${docUrl}">Open ${docName}</a>

<#if message.value?? && message.value != "">
<strong>Extra message:</strong>
${message.value}
<#else>
No message available
</#if>

Regards
FYI: ${initiator.name}

This email includes:

• Workflow initiator's email and name
• Document path and clickable link
• Conditional display of an optional message
• Professional formatting with HTML paragraphs

Preparing Recipients with Action Node

Often you need to convert user IDs (from Task form selections) into email addresses. Use an Action node before the Mail node to prepare the recipient list:

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

// Get users from the context
Select users = (Select) context.get("users");
String usersIdSemicolonSeparated = users.getValue();

FileLogger.info("mail-management", "Select value: " + usersIdSemicolonSeparated);

// Convert to userId to email string comma separated
List<String> userList = WorkflowUtils.convertToListFromSelectValue(usersIdSemicolonSeparated);
List<String> emailList = new ArrayList();
for (String userId : userList){
  CommonUser commonUser = ws.auth.getUser(userId);
  emailList.add(commonUser.getEmail());
}
String emails = String.join(";", emailList); // email separator must be the semicolon

FileLogger.info("mail-management", "Semicolon separated: " + emails);

// Save email list in the context
context.put("emails", emails);

This code:

1. Retrieves a Select field value containing user IDs
2. Converts the semicolon-separated string to a list
3. Fetches each user's email address via the OpenKM API
4. Joins emails with semicolons (required for Mail node)
5. Stores the result in context as ${emails}

Common Use Cases

1. Task Assignment Notification

Notify users when a task is assigned to them:

• Recipients: ${assignedUser.email}
• Subject: New Task Assigned: ${taskName}
• Body: Include task details, due date, and link to workflow

2. Document Approval Request

Request approval from supervisors:

• Recipients: ${supervisorEmails}
• Subject: Document Approval Required: ${documentName}
• Body: Include document details, requester info, and approval link

3. Workflow Completion Notice

Inform stakeholders when workflow completes:

• Recipients: ${initiator.email};${participantEmails}
• Subject: Workflow Completed: ${workflowName}
• Body: Summary of workflow results and final document location

Best Practices

• Use descriptive names that clearly indicate what action is being performed
• Validate email addresses using an Action node before sending
• When preparing email lists in context variables, always use semicolons (;) as separators
• Verify that context variables contain expected values before deploying
• Use FreeMarker's null-checking (<#if variable??>) to prevent errors
• Keep emails concise and focus on essential information
• Create subject lines that clearly identify the email purpose
• Use FileLogger in Action nodes to track email preparation and troubleshoot issues
• Be aware of SMTP server limits on recipient count and message size
• For automated notifications, consider including preferences management