Mail node

Resumen

El nodo Mail envía notificaciones por correo electrónico a uno o más destinatarios como parte del proceso de flujo de trabajo. Este nodo se ejecuta automáticamente sin pausar el flujo de trabajo, enviando los correos a través del servicio SMTP de OpenKM. Admite variables de contexto y formato HTML, lo que lo hace ideal para notificar a los usuarios sobre eventos del flujo de trabajo, actualizaciones de documentos o asignaciones de tareas.

Propiedades del nodo

Propiedad	Tipo	Descripción
Name	Texto	Identificador único del nodo Mail dentro del flujo de trabajo. Este nombre debe ser único entre todos los nodos de la definición de proceso.
Id	Número	Identificador numérico generado por el sistema y asignado automáticamente al crear el nodo.
Source position	Desplegable	Posición donde se conectan las transiciones entrantes a este nodo. Opciones disponibles: Top, Bottom, Left, Right.
Target position	Desplegable	Posición donde salen las transiciones salientes de este nodo. Opciones disponibles: Top, Bottom, Left, Right. No puede coincidir con Source position.
Description	Área de texto	Campo de texto opcional para documentar el propósito y el comportamiento de este nodo Mail. Esta descripción solo es visible en el diseñador de flujos de trabajo.
Recipients	Área de texto	Direcciones de correo de los destinatarios, separadas por coma “,”. Admite variables de contexto para listas de destinatarios dinámicas, por ejemplo: ${emails}.
Subject	Texto	Línea de asunto del correo. Admite variables de contexto, por ejemplo: ${subject}, para crear asuntos dinámicos según los datos del flujo de trabajo.
Body	Editor HTML	Contenido del mensaje de correo en formato HTML. Admite edición de texto enriquecido, variables de contexto y expresiones de plantilla FreeMarker para generar contenido dinámico.

Variables de contexto

El nodo Mail admite variables de contexto en los campos Recipients, Subject y Body mediante la sintaxis ${variable}. Las variables se evalúan en tiempo de ejecución y se sustituyen por sus valores actuales del contexto del flujo de trabajo.

Variables de contexto habituales

• ${initiator.email} - dirección de correo del iniciador del flujo de trabajo
• ${initiator.name} - nombre completo del iniciador del flujo de trabajo
• ${node.path} - ruta del documento/nodo que inició el flujo de trabajo (si procede)
• ${uuid} - UUID del documento que inició el flujo de trabajo (si procede)
• Variables personalizadas creadas por formularios de Task o nodos Action (por ejemplo, ${emails}, ${subject}, ${message.value})

Recipients

El campo Recipients admite direcciones de correo separadas por coma “,". Puede indicar los destinatarios de dos formas:

1. Direcciones de correo directas: user1@example.com,user2@example.com,user3@example.com
2. Variable de contexto: ${emails} (la variable debe contener direcciones de correo separadas por punto y coma)

Precaución

Importante: al introducir direcciones de correo manualmente en el campo, use comas (,) como separador. Sin embargo, al usar variables de contexto que contienen listas de correos, esas variables deben usar punto y coma (;) como separador.

Subject

El campo Subject admite texto plano y variables de contexto. Use variables para crear asuntos dinámicos que reflejen el estado actual del flujo de trabajo:

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

Body

El campo Body ofrece un editor de texto enriquecido que genera contenido HTML. Puede usar las herramientas de formato para crear correos profesionales con:

• Formato de texto (negrita, cursiva, subrayado)
• Párrafos y encabezados
• Listas (ordenadas y sin ordenar)
• Enlaces e imágenes
• Tablas
• Variables de contexto mediante sintaxis ${variable}
• Expresiones de plantilla FreeMarker para lógica condicional y bucles

Soporte de FreeMarker

El campo Body admite el lenguaje de plantillas FreeMarker, lo que permite incluir contenido condicional, bucles y otras funcionalidades avanzadas de plantillas:

• Contenido condicional: <#if condition>...<#else>...</#if>
• Comprobaciones de nulos: <#if variable??>...</#if>
• Bucles: <#list items as item>...</#list>

Ejemplo: correo de notificación de documento

Este ejemplo muestra una notificación de correo completa que usa variables de contexto y expresiones FreeMarker:

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}

Este correo incluye:

• El correo y el nombre del iniciador del flujo de trabajo
• La ruta del documento y un enlace en el que se puede hacer clic
• Visualización condicional de un mensaje opcional
• Formato profesional con párrafos HTML

Preparar los destinatarios con un nodo Action

A menudo necesitará convertir IDs de usuario (procedentes de selecciones en formularios Task) en direcciones de correo. Use un nodo Action antes del nodo Mail para preparar la lista de destinatarios:

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

Este código:

1. Obtiene el valor de un campo Select que contiene IDs de usuario
2. Convierte la cadena separada por punto y coma en una lista
3. Obtiene la dirección de correo de cada usuario mediante la API de OpenKM
4. Une los correos con punto y coma (requerido por el nodo Mail)
5. Guarda el resultado en el contexto como ${emails}

Casos de uso habituales

1. Notificación de asignación de tarea

Notificar a los usuarios cuando se les asigna una tarea:

• Recipients: ${assignedUser.email}
• Subject: New Task Assigned: ${taskName}
• Body: incluya los detalles de la tarea, la fecha límite y un enlace al flujo de trabajo

2. Solicitud de aprobación de documento

Solicitar aprobación a los supervisores:

• Recipients: ${supervisorEmails}
• Subject: Document Approval Required: ${documentName}
• Body: incluya los detalles del documento, información del solicitante y el enlace de aprobación

3. Aviso de finalización del flujo de trabajo

Informar a las partes interesadas cuando finaliza el flujo de trabajo:

• Recipients: ${initiator.email};${participantEmails}
• Subject: Workflow Completed: ${workflowName}
• Body: resumen de los resultados del flujo de trabajo y la ubicación final del documento

Buenas prácticas

• Use nombres descriptivos que indiquen claramente qué acción se realiza
• Valide las direcciones de correo con un nodo Action antes de enviar
• Al preparar listas de correo en variables de contexto, use siempre el punto y coma (;) como separador
• Verifique que las variables de contexto contienen los valores esperados antes de desplegar
• Use la comprobación de nulos de FreeMarker (<#if variable??>) para evitar errores
• Mantenga los correos concisos y centrados en la información esencial
• Cree asuntos que identifiquen claramente el propósito del correo
• Use FileLogger en los nodos Action para seguir la preparación de correos y resolver problemas
• Tenga en cuenta los límites del servidor SMTP en cuanto a número de destinatarios y tamaño del mensaje
• Para notificaciones automatizadas, considere incluir la gestión de preferencias

Consejo

Use el método WorkflowUtils.convertToListFromSelectValue() para convertir fácilmente los valores de un campo Select en listas de destinatarios, y luego obtenga las direcciones de correo mediante la API de OpenKM.

Nota

El nodo Mail usa el servicio SMTP de OpenKM configurado en los ajustes del servidor de OpenKM. Asegúrese de que su servidor SMTP esté correctamente configurado y accesible para el envío de correos.