Add Variable

1. Overview

The Add Variable component (add-variable) creates and stores variables that can be used at any later point in the flow's execution. The created variables are made available to the other components in the same flow through references in the message body.

Use this component when you need to:

• Store an intermediate result to reuse later.
• Create a short "alias" for a complex expression, avoiding repeating it multiple times.
• Keep a calculated value during a flow's execution.

Not suited for persisting data across different runs (that's the job of the Local Storage component, with APPLICATION scope) — Add Variable's variables only exist during the current run.

2. Prerequisites

No credentials, licenses, or external access required. The component works internally in the flow engine, with no network calls.

3. Authentication and Connection

Not applicable — this component doesn't connect to any external system.

4. Configuration / Supported Operations

The component has a single operation: define one or more variables.

Field	Required	Type	Description	Example
variables	Yes	Object (key/value map) or equivalent JSON text	Each key becomes the variable's name. Each value can be a fixed text or an expression that fetches data from the message. If the resulting value is text in object ({...}) or list ([...]) format, it's automatically parsed as JSON.	{"userAge": "customer's age", "category": "order category"}
stopOnError	No	Text ("true"/"false")	Defines whether the flow stops when an error occurs while processing the variables. Default value: "true".	"false"
executeOnError	No	Text	Name of a function to be called automatically if an error occurs. That function needs to exist in a separate sub-flow triggered by a Function component.	"handleVariableError"
onBeforeExecute	No	Text	Name of a function to run before this component executes. Doesn't accept expressions, just the function's literal name.	"validateInput"
onAfterExecute	No	Text	Name of a function to run after this component executes. Doesn't accept expressions, just the function's literal name.	"enrichData"

If variables isn't informed, the component simply does nothing and continues the flow without error (a warning is logged).

Error behavior: if the value of variables isn't in a recognized format (neither an object nor valid JSON text), or if something fails during processing, the component interrupts execution with an error message describing the cause.

5. Practical Examples

Simple example: a flow receives an order and wants to store the customer's age and the order category as variables, to use later in a condition.

Input (body of the message received by the flow):

{
  "customer": { "name": "Maria Silva", "age": 34 },
  "order": { "category": "electronics", "amount": 1500 }
}

Component configuration:

{
  "componentName": "add-variable",
  "configurations": {
    "variables": {
      "userAge": "{$.body.customer.age}",
      "category": "{$.body.order.category}"
    }
  }
}

Response (the message body stays the same, but now with the variables available for the next flow steps):

{
  "customer": { "name": "Maria Silva", "age": 34 },
  "order": { "category": "electronics", "amount": 1500 },
  "variables": {
    "userAge": 34,
    "category": "electronics"
  }
}

Advanced example: the same scenario, but now with error handling. If the age or category don't exist in the message (e.g., a missing field), the flow isn't stopped (stopOnError off) and an error-handling function (executeOnError) is called automatically.

Input (now without the age field):

{
  "customer": { "name": "John Smith" },
  "order": { "category": "furniture", "amount": 800 }
}

Component configuration:

{
  "componentName": "add-variable",
  "configurations": {
    "variables": {
      "userAge": "{$.body.customer.age}",
      "category": "{$.body.order.category}"
    },
    "stopOnError": "false",
    "executeOnError": "handleVariableError"
  }
}

Response (the flow continues and the handleVariableError function is called receiving, for example):

{
  "success": false,
  "errorMessage": "Could not resolve variable 'userAge'",
  "errorType": "FlowException"
}

6. Common Errors and Troubleshooting

Error / Symptom	Likely Cause	How to Fix
"Invalid variables configuration format. Expected Map or JSON string."	The variables field was filled with a type that is neither an object nor valid JSON text.	Review the configuration and make sure variables is a key/value object or a valid JSON string.
"Error processing variables in add-variable component: ..."	Failure resolving an expression inside the variable values.	Check whether the paths/expressions used in the values actually exist in the input message.
Variable disappears or appears empty	The path used in the value found nothing in the message.	Check whether the referenced field exists in the message at that point of the flow.

⚠️ TO CONFIRM: the code doesn't make it clear which exact expression syntax (JSONPath, MVEL, or other) is accepted in variable values — this depends on a translation mechanism shared by several components, not documented in this file.

7. References

• Local Storage