Developer Guide: The Conditional Node

Developer Guide: The Conditional Node

Here is the updated documentation for the new Conditional node.

Logic & Control Flow: The Conditional Node

The Conditional node is a powerful control flow utility that evaluates a complex logical expression. Its purpose is to return the string "TRUE" or "FALSE" based on the outcome. This node is a fundamental building block for creating dynamic workflows, as its output can be used by a ConditionalCustomWorkflow node to decide whether or not to execute a subsequent sub-workflow.

It supports:

• Comparisons between numbers or strings (e.g., {score} > 90, '{status}' == 'complete').
• Logical operators AND and OR to combine multiple conditions.
• Parentheses () to group expressions and control the order of evaluation.

How It Works

1. Configuration Loading: The processor loads the node's JSON configuration and its condition string.
2. Variable Substitution: The condition field is processed, replacing any placeholders like {agent1Output} with their runtime values.
3. Expression Parsing: The system uses a standard Shunting-yard algorithm to parse the entire expression. This correctly handles operator precedence (AND is evaluated before OR) and nested expressions within parentheses.
4. Type Inference: During evaluation, the node intelligently parses each value.
   • A value enclosed in single or double quotes (e.g., "Admin") is treated as a string.
   • The special words TRUE and FALSE (case-insensitive, without quotes) are treated as booleans.
   • Any other unquoted value is first attempted as a number. If it's not a valid number, it's treated as a * string* (e.g., the resolved output of a variable).
5. Evaluation: The full expression is evaluated according to logical rules. Comparing a number to a string (e.g., 5 > "cat") will safely result in FALSE.
6. Output Handling:
   • The node returns the string "TRUE" if the final expression evaluates to true, and "FALSE" otherwise.
   • If the condition is malformed or a syntax error occurs, it safely returns "FALSE" and logs a warning.
   • The string output is captured as a variable (e.g., {agent2Output}), which can be directly used to control other nodes.

Properties

Variable Usage

The condition property supports all available workflow variables. The node will automatically determine the type ( number, string, or boolean) of the resolved variable. For string literals in the condition itself, it is best practice to enclose them in quotes (e.g., "completed").

⚠️ Critical Usage Note: Comparing Booleans vs. Strings

The node's type inference engine makes a critical distinction between a boolean TRUE and a string 'TRUE'. This is especially important when checking the output of a previous Conditional node.

The Conditional node outputs the raw string TRUE or FALSE. When this output (e.g., {agent3Output}) is used in another condition, the parser interprets it as a boolean.

• INCORRECT Comparison: "{agent3Output} == 'TRUE'"

  • This will evaluate as (boolean) True == (string) 'TRUE', which is FALSE.

• CORRECT Comparison: "{agent3Output} == TRUE"

  • This will evaluate as (boolean) True == (boolean) True, which is TRUE.

Always compare the output of a Conditional node against the unquoted keywords TRUE or FALSE.

Full Syntax Examples

Simple Numeric Comparison This example checks if a calculated score from a previous node is passing.

{
  "title": "Check if score is passing",
  "type": "Conditional",
  "condition": "{agent4Output} >= 65"
}

Combined Logic with AND This example checks if the string output from a task is 'complete' and was not assigned to a user named 'guest'.

{
  "title": "Check if task is complete and not a guest task",
  "type": "Conditional",
  "condition": "{agent2Output} == 'complete' AND {agent1Output} != 'guest'"
}

Complex Logic with OR and Parentheses This example demonstrates how to check for multiple valid states or an override condition. The parentheses ensure the OR conditions are evaluated together before the AND. Note the correct comparison to the unquoted boolean TRUE.

{
  "title": "Check for valid state or admin override",
  "type": "Conditional",
  "condition": "({agent1Output} == 'Admin') OR ({agent2Output} == 'Approved' AND {agent3Output} == TRUE)"
}