Add Variable

1. Visión General

El componente Add Variable (add-variable) crea y almacena variables que pueden usarse en cualquier punto posterior del flujo de ejecución. Las variables creadas quedan disponibles para los demás componentes del mismo flujo mediante referencias en el cuerpo del mensaje.

Usa este componente cuando necesites:

• Guardar un resultado intermedio para reutilizarlo más adelante.
• Crear un "alias" corto para una expresión compleja, evitando repetirla varias veces.
• Mantener un valor calculado durante la ejecución de un flujo.

No es recomendable para persistir datos entre ejecuciones diferentes (ese es el papel del componente Local Storage, con ámbito APPLICATION) — las variables de Add Variable solo existen durante la ejecución actual.

2. Prerrequisitos

No hay credenciales, licencias ni accesos externos necesarios. El componente funciona internamente en el motor de flujo, sin llamadas de red.

3. Autenticación y Conexión

No aplica — este componente no se conecta a ningún sistema externo.

4. Configuración / Operaciones Soportadas

El componente tiene una única operación: definir una o más variables.

Campo	Obligatorio	Tipo	Descripción	Ejemplo
variables	Sí	Objeto (mapa clave/valor) o texto JSON equivalente	Cada clave se convierte en el nombre de la variable. Cada valor puede ser un texto fijo o una expresión que busca datos en el mensaje. Si el valor resultante es un texto con formato de objeto ({...}) o lista ([...]), se interpreta automáticamente como JSON.	{"userAge": "edad del usuario", "category": "categoría del pedido"}
stopOnError	No	Texto ("true"/"false")	Define si el flujo se detiene cuando ocurre un error al procesar las variables. Valor por defecto: "true".	"false"
executeOnError	No	Texto	Nombre de una función que se llamará automáticamente si ocurre un error. Esa función debe existir en un subflujo separado disparado por un componente Function.	"handleVariableError"
onBeforeExecute	No	Texto	Nombre de una función que se ejecutará antes de que corra este componente. No acepta expresiones, solo el nombre literal de la función.	"validarEntrada"
onAfterExecute	No	Texto	Nombre de una función que se ejecutará después de que corra este componente. No acepta expresiones, solo el nombre literal de la función.	"enriquecerDatos"

Si variables no se informa, el componente simplemente no hace nada y sigue el flujo sin error (queda registrado un aviso en el log).

Comportamiento en caso de error: si el valor de variables no está en un formato reconocido (ni objeto, ni texto JSON válido), o si algo falla durante el procesamiento, el componente interrumpe la ejecución con un mensaje de error describiendo la causa.

5. Ejemplos Prácticos

Ejemplo simple: un flujo recibe un pedido y quiere guardar la edad del cliente y la categoría del pedido como variables, para usarlas después en una condición.

Entrada (cuerpo del mensaje recibido por el flujo):

{
  "cliente": { "nome": "Maria Silva", "idade": 34 },
  "pedido": { "categoria": "eletronicos", "valor": 1500 }
}

Configuración del componente:

{
  "componentName": "add-variable",
  "configurations": {
    "variables": {
      "userAge": "{$.body.cliente.idade}",
      "category": "{$.body.pedido.categoria}"
    }
  }
}

Respuesta (el cuerpo del mensaje sigue igual, pero ahora con las variables disponibles para los próximos pasos del flujo):

{
  "cliente": { "nome": "Maria Silva", "idade": 34 },
  "pedido": { "categoria": "eletronicos", "valor": 1500 },
  "variables": {
    "userAge": 34,
    "category": "eletronicos"
  }
}

Ejemplo avanzado: el mismo escenario, pero ahora con manejo de errores. Si la edad o la categoría no existen en el mensaje (por ejemplo, un campo faltante), el flujo no se interrumpe (stopOnError desactivado) y una función de manejo (executeOnError) es llamada automáticamente.

Entrada (ahora sin el campo idade):

{
  "cliente": { "nome": "João Souza" },
  "pedido": { "categoria": "moveis", "valor": 800 }
}

Configuración del componente:

{
  "componentName": "add-variable",
  "configurations": {
    "variables": {
      "userAge": "{$.body.cliente.idade}",
      "category": "{$.body.pedido.categoria}"
    },
    "stopOnError": "false",
    "executeOnError": "handleVariableError"
  }
}

Respuesta (el flujo continúa y la función handleVariableError es llamada recibiendo, por ejemplo):

{
  "success": false,
  "errorMessage": "No fue posible resolver la variable 'userAge'",
  "errorType": "FlowException"
}

6. Errores Comunes y Troubleshooting

Error / Síntoma	Causa probable	Cómo resolverlo
"Invalid variables configuration format. Expected Map or JSON string."	El campo variables fue completado con un tipo que no es ni objeto ni texto JSON válido.	Revisar la configuración y garantizar que variables sea un objeto clave/valor o una cadena JSON válida.
"Error processing variables in add-variable component: ..."	Falla al resolver alguna expresión dentro de los valores de las variables.	Verificar que las rutas/expresiones usadas en los valores realmente existan en el mensaje de entrada.
La variable desaparece o aparece vacía	La ruta usada en el valor no encontró nada en el mensaje.	Comprobar que el campo referenciado exista en el mensaje en ese punto del flujo.

A CONFIRMAR: el código no deja claro qué sintaxis exacta de expresión (JSONPath, MVEL u otra) se acepta en los valores de las variables — eso depende de un mecanismo de traducción común a varios componentes, no documentado en este archivo.