Transition

Resumen

Las transiciones son los elementos de conexión que definen los caminos de flujo entre los nodos del flujo de trabajo. Establecen la secuencia de ejecución y la lógica de enrutado que determina cómo avanza un flujo de trabajo de un nodo a otro. Cada transición debe conectar un nodo de origen con un nodo de destino, creando el flujo direccional que controla el comportamiento del flujo de trabajo.

Precaución

Todas las transiciones deben estar conectadas tanto a un nodo de origen como a un nodo de destino. Un flujo de trabajo no puede contener transiciones que no cumplan este requisito. Las transiciones incompletas provocarán errores de ejecución del flujo de trabajo.

Propiedades de la transición

Propiedad	Tipo	Descripción
Name	Texto	El nombre de la transición. Esta propiedad es: - Opcional: cuando un nodo tiene una única transición saliente, se recomienda asignar un nombre, pero no es obligatorio - Obligatoria: cuando un nodo tiene varias transiciones salientes, cada transición debe tener un nombre único. El flujo de trabajo usa estos nombres para determinar qué camino seguir según el valor devuelto por los nodos Decision o los nodos Action con lógica de enrutado. Pueden existir varias transiciones con el mismo nombre en el flujo de trabajo, pero, saliendo de un mismo nodo, cada transición debe tener su propio nombre.
Type	Desplegable	Determina la representación visual de la transición en el diagrama del flujo de trabajo. Tipos disponibles: - Default: línea de transición estándar - Step: línea de transición con estilo de escalón - Smooth Step: línea de transición con estilo de escalón redondeado - Straight: línea de transición recta El tipo solo afecta a la apariencia visual y no cambia el comportamiento de la transición.
Animated	Casilla	Cuando está activada, la línea de transición parpadea en el diagrama del flujo de trabajo, creando un efecto visual de animación. Es útil para resaltar caminos de flujo importantes o transiciones que representan rutas críticas del flujo de trabajo.
Color	Selector de color	Define el color de la línea de transición en el diagrama del flujo de trabajo. La codificación por color ayuda a los usuarios a identificar visualmente los distintos caminos del flujo de trabajo y su propósito. Las prácticas habituales incluyen: - Verde: caminos de éxito o flujos de aprobación - Rojo: caminos de error o flujos de rechazo - Azul: caminos de procesamiento estándar - Amarillo: caminos de advertencia o condicionales
Script definition	Editor de código	Script Groovy opcional que se ejecuta cuando el flujo de trabajo recorre esta transición. El script tiene acceso al contexto del flujo de trabajo y puede realizar acciones similares a las de los nodos Action. Sin embargo, a diferencia de los scripts de los nodos Action, los scripts de transición no deben devolver un valor de tipo cadena, ya que el camino de la transición ya está determinado en este punto de la ejecución.

Requisitos de nomenclatura de las transiciones

Transición saliente única

Cuando un nodo tiene una única transición saliente, el nombre de la transición es opcional. El flujo de trabajo sigue automáticamente el único camino disponible sin necesitar enrutado basado en nombres.

Varias transiciones salientes

Cuando un nodo tiene varias transiciones salientes (habitual en nodos Decision o nodos Action con lógica de enrutado), cada transición debe tener un nombre único. El script del nodo de origen devuelve una cadena que coincide con el nombre de la transición a seguir.

Ejemplo: nodo Decision con varias transiciones

// Decision node script
if (approvalRequired) {
    return "approved";  // Follows transition named "approved"
} else {
    return "rejected";  // Follows transition named "rejected"
}

Nota

Los nombres de las transiciones distinguen entre mayúsculas y minúsculas. Asegúrese de que la cadena devuelta por los scripts de los nodos Decision o Action coincide exactamente con el nombre de la transición, incluyendo el uso de mayúsculas y minúsculas.

Scripts de transición

Las transiciones pueden ejecutar scripts Groovy durante el recorrido del flujo de trabajo. Estos scripts tienen acceso al contexto del flujo de trabajo y pueden realizar operaciones como:

• Actualizar variables de contexto
• Llamar a métodos de la API de OpenKM
• Establecer metadatos de documentos
• Registrar eventos del flujo de trabajo
• Realizar transformaciones de datos

Acceso al contexto del script

Los scripts de transición tienen acceso a las mismas variables de contexto que los nodos Action:

• context - Map de variables de contexto del flujo de trabajo
• processInstance - objeto ProcessInstance actual
• initiator - actor que inició el flujo de trabajo
• processDefinition - objeto ProcessDefinition
• uuid - UUID del documento (si el flujo de trabajo se inició desde un documento)
• node - objeto de nodo de OpenKM (Document, Folder, Mail o Record)

Diferencia clave respecto a los nodos Action

Aunque los scripts de transición pueden realizar operaciones similares a los scripts de los nodos Action, existe una diferencia fundamental:

Precaución

Los scripts de transición NO deben devolver un valor de tipo cadena para controlar el enrutado. A diferencia de los nodos Action y Decision, las transiciones ya se están ejecutando por un camino determinado. El flujo de trabajo no puede bifurcarse hacia otra transición en este punto. Cualquier valor devuelto por un script de transición será ignorado.

Ejemplo: script de transición

Este ejemplo muestra un script de transición que establece metadatos de documento cuando el flujo de trabajo sigue un camino concreto:

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

Este script:

1. Obtiene variables relacionadas con la factura desde el contexto del flujo de trabajo
2. Obtiene el UUID del documento
3. Crea un map de propiedades con los metadatos de la factura
4. Actualiza el grupo de propiedades del documento con los valores de metadatos

Cuándo usar scripts de transición frente a nodos Action

Caso de uso	Enfoque recomendado	Motivo
Lógica de enrutado condicional	Nodo Action o Decision	Estos nodos están diseñados para lógica de bifurcación y valores de retorno que determinan la transición a seguir
Lógica de negocio compleja	Nodo Action	Los nodos Action ofrecen mejor visibilidad, depuración y separación de responsabilidades
Transformación de datos sencilla	Cualquiera	Puede usar scripts de transición para operaciones ligeras, pero los nodos Action ofrecen mejor mantenibilidad
Operaciones específicas de un camino	Script de transición	Cuando una operación solo debe producirse al seguir un camino concreto, los scripts de transición son adecuados
Actualización de metadatos en la aprobación	Script de transición	Actualizar propiedades del documento al seguir una transición “approved” es un caso de uso válido

Consejo

Buena práctica: prefiera los nodos Action a los scripts de transición para la mayoría de las necesidades de scripting. Los scripts de transición deben reservarse para operaciones específicas de un camino concreto del flujo de trabajo que deban ejecutarse durante el recorrido de la transición.

Diseño visual con transiciones

Selección de tipo

Elija los tipos de transición según la claridad visual y la organización del diagrama:

Campo / Propiedad	Apariencia	Descripción
Default		Transiciones de propósito general para la mayoría de los flujos de trabajo
Step		Útil para flujos de trabajo con disposiciones de nodos horizontales o verticales
Smooth Step		Ofrece un aspecto más pulido con esquinas redondeadas
Straight		Ideal para conexiones directas y de corta distancia entre nodos

Estrategia de codificación por color

Implemente un esquema de color consistente en todos los flujos de trabajo:

• Caminos de éxito: transiciones verdes para aprobaciones, finalizaciones y resultados positivos
• Caminos de error: transiciones rojas para rechazos, fallos y gestión de errores
• Caminos estándar: transiciones azules o grises para pasos de procesamiento neutros
• Caminos condicionales: transiciones amarillas o naranjas para condiciones de advertencia

Uso de la animación

Use las transiciones animadas con moderación para resaltar:

• Caminos de aprobación críticos que requieren atención especial
• Rutas de gestión de errores o excepciones
• Ramas del flujo de trabajo inusuales o poco frecuentes
• Caminos que desencadenan procesos de negocio importantes

Buenas prácticas

• Nombre todas las transiciones importantes: aunque sea opcional, nombrar las transiciones mejora la legibilidad y la mantenibilidad del flujo de trabajo
• Use nombres descriptivos: elija nombres que indiquen claramente el propósito de la transición (por ejemplo, “approved”, “rejected”, “needs_review”)
• Mantenga la consistencia de nomenclatura: use una convención de nomenclatura consistente en todos los flujos de trabajo
• Evite scripts de transición complejos: mantenga los scripts de transición sencillos o use nodos Action para lógica compleja
• Documente el significado de los colores: establezca y documente un esquema de color para las transiciones en la documentación del flujo de trabajo
• Pruebe escenarios multicamino: pruebe a fondo los flujos de trabajo con varias transiciones salientes para garantizar el enrutado correcto
• Valide los nombres de las transiciones: asegúrese de que los valores devueltos por los nodos Decision y Action coinciden exactamente con los nombres de las transiciones
• Use señales visuales de forma eficaz: combine color, animación y nomenclatura para que los caminos del flujo de trabajo sean intuitivos
• Mantenga los scripts enfocados: los scripts de transición deben realizar operaciones específicas de ese camino, no lógica general del flujo de trabajo
• Registre la ejecución de las transiciones: use FileLogger en los scripts de transición para seguir qué caminos sigue el flujo de trabajo

Errores habituales

• Transiciones sin nombre: olvidar nombrar las transiciones cuando existen varios caminos desde un nodo
• Discrepancias de nombre: discrepancias de nombre (sensibles a mayúsculas y minúsculas) entre los valores de retorno de los nodos y los nombres de las transiciones
• Devolver valores desde scripts de transición: intentar controlar el enrutado desde un script de transición (lo cual no funciona)
• Transiciones desconectadas: crear transiciones sin conexión de origen y destino
• Abusar de la animación: animar demasiadas transiciones, lo que reduce la eficacia del indicador visual
• Nomenclatura inconsistente: usar convenciones de nomenclatura distintas para transiciones similares dentro del mismo flujo de trabajo

Nota

Las transiciones son fundamentales para el control del flujo del flujo de trabajo. Unas transiciones bien diseñadas, con nomenclatura clara, un estilo visual adecuado y scripts enfocados, contribuyen significativamente a la mantenibilidad del flujo de trabajo y a su comprensión por parte del usuario.