Action node

Resumen

El nodo Action permite la ejecución automatizada de lógica personalizada dentro del flujo de trabajo. Cuando el flujo de trabajo llega a un nodo Action, ejecuta un script que puede realizar diversas operaciones, como gestionar variables de contexto, llamar a la API de OpenKM o ejecutar cualquier lógica de negocio personalizada. A diferencia de los nodos Task, que requieren interacción humana, los nodos Action se ejecutan automáticamente sin pausar el flujo de trabajo.

Propiedades del nodo

DescriptionÁrea de texto

Campo opcional para aportar detalles adicionales o documentación sobre el propósito de la acción y la lógica que ejecuta.

Propiedad	Tipo	Descripción
Name	Texto	El nombre que identifica este nodo Action. Debe describir claramente la acción que se realiza (por ejemplo, “Añadir metadatos de factura”, “Calcular total”, “Actualizar propiedades del documento”).
Id	Número	Identificador único asignado al nodo. Este valor se genera automáticamente por el sistema e identifica de forma única al nodo dentro de la definición de proceso.
Source position	Desplegable	Define la posición desde la que salen las flechas de transición del nodo. Opciones disponibles: Top, Bottom, Left, Right.
Target position	Desplegable	Define la posición en la que entran las flechas de transición al nodo. Opciones disponibles: Top, Bottom, Left, Right.
Script definition	Editor de scripts	Contiene el código del script que se ejecutará cuando el flujo de trabajo llegue a este nodo. El script tiene acceso completo al contexto del flujo de trabajo, a las variables y a la API de OpenKM. Se puede acceder al editor de dos formas: - Área de texto: editar directamente en el campo de texto - Editor emergente: haga clic en el icono sobre el área de texto para abrir una ventana de edición más grande El editor admite autocompletado. Pulse Ctrl+Espacio mientras escribe para ver las opciones disponibles y sugerencias de código.

Precaución

Importante: Source position y Target position no pueden tener el mismo valor. Por ejemplo, si Source position está establecido en “Bottom”, Target position no puede ser también “Bottom”.

Casos de uso habituales

Los nodos Action se usan habitualmente para las siguientes operaciones:

• Gestionar variables de contexto: crear, actualizar o eliminar variables en el contexto del flujo de trabajo
• Añadir metadatos: establecer propiedades y metadatos de documento usando los webservices de la API de OpenKM
• Realizar cálculos: ejecutar lógica de negocio y almacenar los resultados en variables de contexto
• Llamadas a API externas: integrarse con sistemas y servicios externos
• Operaciones sobre documentos: crear, mover, copiar o modificar documentos mediante programación
• Enrutado condicional: determinar el siguiente camino del flujo de trabajo según lógica (capacidad de decisión opcional)

Capacidad de decisión opcional

Aunque los nodos Action ejecutan principalmente lógica, pueden funcionar opcionalmente como nodos Decision. Si el script devuelve un valor de tipo cadena, el flujo de trabajo usará ese valor para determinar el siguiente camino de transición, de forma similar a cómo funciona un nodo Decision.

Nota

Cuando un nodo Action devuelve una cadena, esta debe coincidir con el nombre de una de las transiciones salientes. Si no coincide, la ejecución del flujo de trabajo fallará. Esta funcionalidad permite que los nodos Action ejecuten lógica y controlen el enrutado del flujo de trabajo en un único paso.

Ejemplo de script

El siguiente ejemplo muestra un nodo Action que añade metadatos a un documento y opcionalmente enruta a distintas transiciones según el total de la factura:

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();
Class baseLibrary = ScriptUtils.evaluateFromNode("library_global_base");
def invoiceNumber = baseLibrary.getContextValue(context, "invoice_number");
def total = baseLibrary.getContextValue(context, "total");
def uuid = baseLibrary.getContextValue(context, "uuid");

Map<String,String> properties = new HashMap();
properties.put("okp:invoice.number", invoiceNumber.getValue());
properties.put("okp:invoice.total", total.getValue());
ws.propertyGroup.setProperties(uuid, "okg:invoice", properties);

// Optional (works as decision node)
int totalValue = Integer.parseInt(total.getValue());
if (totalValue > 1000) {
  return "supervisor";
} else {
  return "go";
}

Este script realiza las siguientes operaciones:

1. Obtiene variables de contexto: obtiene el número de factura, el total y el UUID del documento desde el contexto del flujo de trabajo
2. Prepara los metadatos: crea un Map con los campos del grupo de propiedades a establecer
3. Llama a la API de OpenKM: usa los webservices para establecer las propiedades de metadatos en el documento
4. Enrutado opcional: evalúa el total de la factura y devuelve “supervisor” (si el total > 1000) o “go” (si el total ≤ 1000)

Consejo

La sentencia return final es opcional. Si la elimina, el script simplemente ejecutará las operaciones de metadatos y continuará al siguiente nodo sin enrutado condicional. Esto hace que los nodos Action sean muy flexibles: pueden realizar operaciones con o sin controlar el flujo del proceso.

Acceso a las variables de contexto

Los scripts de los nodos Action tienen acceso completo a todas las variables de contexto del flujo de trabajo. Puede:

• Leer variables existentes usando métodos de ayuda o directamente desde el contexto
• Crear nuevas variables almacenando valores en el contexto
• Modificar valores de variables existentes
• Eliminar variables cuando ya no se necesiten

Normalmente se accede a las variables mediante métodos de ayuda de biblioteca (como en el ejemplo anterior) o directamente a través del objeto de contexto de ejecución del flujo de trabajo.

Integración con la API de OpenKM

Una de las funcionalidades más potentes de los nodos Action es la capacidad de interactuar con la API de OpenKM. Las operaciones de API habituales incluyen:

• Operaciones sobre documentos: crear, actualizar, eliminar, mover o copiar documentos
• Gestión de metadatos: establecer u obtener valores de grupos de propiedades
• Operaciones sobre carpetas: crear o gestionar estructuras de carpetas
• Operaciones de búsqueda: consultar documentos según metadatos o contenido
• Operaciones sobre notas: añadir notas o anotaciones a documentos

El objeto OKMWebservices (obtenido mediante WebservicesHelper.getInstance()) da acceso a toda la funcionalidad de la API de OpenKM.

Buenas prácticas

• Use nombres descriptivos que indiquen claramente qué acción se realiza
• Añada descripciones detalladas para documentar lógica compleja, especialmente cuando los scripts son largos o intrincados
• Gestione las excepciones adecuadamente para evitar fallos en el flujo de trabajo
• Al usar la capacidad de decisión opcional, asegúrese de que todos los posibles valores de retorno coinciden con nombres de transiciones existentes
• Pruebe los scripts a fondo con distintos escenarios de datos antes de desplegar a producción
• Mantenga los scripts enfocados: si una acción se vuelve demasiado compleja, considere dividirla en varios nodos Action
• Use funciones de biblioteca para operaciones habituales, favoreciendo la reutilización y el mantenimiento del código
• Documente las variables de contexto esperadas en el campo Description