Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Tutorial 3: Branching & Routing

This chapter covers two routing mechanisms: conditional edges (if) and multi-way switching (switch), enabling workflows to make decisions based on data.

Conditional Edges – if

The most basic branching: take different paths based on a condition.

[check]: score = 85
[pass]: print(message="Passed!")
[fail]: print(message="Failed.")
[done]: print(message="Done")

[check] if score >= 60 -> [pass]
[check] if score < 60 -> [fail]
[pass] -> [done]
[fail] -> [done]

Line-by-line explanation:

  1. The [check] node writes score to the context with a value of 85.
  2. [check] if score >= 60 -> [pass] – if the score >= 60, take the [pass] path.
  3. [check] if score < 60 -> [fail] – if the score < 60, take the [fail] path.
  4. Both paths ultimately converge at [done].

Conditional edge syntax:

[source_node] if condition_expression -> [target_node]

The edge is only traversed when the condition evaluates to true.

Supported Operators

Comparison operators:

OperatorMeaningExample
==Equal tostatus == "ok"
!=Not equal tostatus != "error"
>Greater thanscore > 80
<Less thanscore < 60
>=Greater than or equal tolevel >= 3
<=Less than or equal tocount <= 10

Logical operators:

OperatorMeaningExample
&& or andAnda && b
|| or orOra || b
! or notNot!banned

String Comparison

String values are wrapped in double quotes:

[input]: type = "question"
[question]: print(message="Handling question")
[task]: print(message="Handling task")
[other]: print(message="Unknown type")

[input] if type == "question" -> [question]
[input] if type == "task" -> [task]
[input] -> [other]

Note the last line [input] -> [other] – this is an unconditional edge, serving as the default path when none of the preceding conditions are satisfied.

Multi-Condition Combinations

Combine multiple conditions with logical operators:

[check]: role = "admin", level = 5, banned = false
[admin]: print(message="Welcome, admin")
[vip]: print(message="VIP access")
[normal]: print(message="Normal user")
[blocked]: print(message="Access denied")

[check] if banned -> [blocked]
[check] if role == "admin" && level > 3 -> [admin]
[check] if role == "vip" || level > 8 -> [vip]
[check] -> [normal]

All matching if edges fire — they are evaluated independently, and every one whose condition is true activates its successor. If you need exactly one branch (mutual exclusion), use switch (see below) or write conditions that cannot both be true (x < 5 and x >= 5).

Branch Convergence

Multiple paths converging at a single node is a common pattern:

[evaluate]: grade = "B"
[excellent]: print(message="Outstanding!")
[good]: print(message="Well done")
[average]: print(message="Keep going")
[summary]: print(message="Evaluation complete")

[evaluate] if grade == "A" -> [excellent]
[evaluate] if grade == "B" -> [good]
[evaluate] -> [average]

[excellent] -> [summary]
[good] -> [summary]
[average] -> [summary]

[summary] has three predecessor nodes, but only one path will actually execute. Juglans uses OR semantics: the convergence node executes as soon as any one predecessor completes. Branches that were not taken are automatically marked as unreachable.

Switch Routing – Multi-Way Exclusive

When branching is based on the value of a single variable with multiple possible outcomes, switch is cleaner than multiple if edges:

[classify]: intent = "question"
[handle_q]: print(message="Question handler")
[handle_t]: print(message="Task handler")
[handle_c]: print(message="Chat handler")
[fallback]: print(message="Unknown intent")
[done]: print(message="Done")

[classify] -> switch intent {
    "question": [handle_q]
    "task": [handle_t]
    "chat": [handle_c]
    default: [fallback]
}
[handle_q] -> [done]
[handle_t] -> [done]
[handle_c] -> [done]
[fallback] -> [done]

Syntax structure:

[source_node] -> switch variable {
    "value1": [target1]
    "value2": [target2]
    default: [fallback_node]
}

Rules:

  • The variable’s value is matched against each case in order. Only the first matching branch is taken.
  • default handles all unmatched cases.
  • default is not required, but it is strongly recommended to always include one to avoid dead-end situations where no path is taken.

switch vs if

When should you use which?

ScenarioRecommendedReason
Multi-way selection based on a single variable’s valueswitchSemantically clear, one block handles everything
Binary choiceifConcise, two lines are enough
Complex conditions (ranges, logical combinations)ifswitch only does equality matching
Need a default pathEitherswitch uses default, if uses an unconditional edge

The key difference: switch guarantees that exactly one branch is taken (the first matching case, or default:), while if conditional edges all fire independently — every edge whose condition is true activates its successor. Use switch when you need mutual exclusion; use if edges when multiple paths may legitimately fire at once.

Mixing Unconditional and Conditional Edges

A node can have both unconditional and conditional edges:

[start]: priority = "high"
[log]: print(message="Logging request...")
[fast_track]: print(message="Priority routing!")
[done]: print(message="Complete")

[start] -> [log]
[start] if priority == "high" -> [fast_track]
[log] -> [done]
[fast_track] -> [done]

Execution behavior:

  • The unconditional edge [start] -> [log] is always executed.
  • The conditional edge [start] if ... -> [fast_track] is only executed when the condition is true.
  • If the condition is true, both [log] and [fast_track] will execute, and both will converge at [done].

This differs from switch’s “only one branch” behavior. If you need strict mutual exclusivity, use switch or ensure your if conditions are mutually exclusive.

Comprehensive Example

A workflow that routes based on message type and priority:

[receive]: type = "task", priority = "high"

[done]: print(message="Routing complete")

# Layer 1: Route by message type
[route_type]: print(message="Routing by type...")
[handle_question]: print(message="Answering question")
[route_task]: print(message="Processing task...")
[handle_other]: print(message="General handler")

[receive] -> [route_type]

[route_type] -> switch type {
    "question": [handle_question]
    "task": [route_task]
    default: [handle_other]
}

# Layer 2: Route tasks by priority
[urgent]: print(message="URGENT: handling immediately")
[normal]: print(message="Queued for processing")

[route_task] if priority == "high" -> [urgent]
[route_task] -> [normal]

# All paths converge
[handle_question] -> [done]
[urgent] -> [done]
[normal] -> [done]
[handle_other] -> [done]

This example demonstrates two-layer routing composition:

  1. The first layer uses switch to route by type.
  2. The second layer uses if to further split the task path by priority.
  3. All branches ultimately converge at [done].

This is the most common routing pattern in real projects: coarse-grained routing first, fine-grained routing second, then merge all paths.

Summary

  • Conditional edges [node] if expr -> [target] – the edge is taken when the condition is true
  • switch [node] -> switch var { "val": [target], default: [fb] } – multi-way exclusive selection based on a variable’s value
  • All matching if conditions fire — for mutual exclusion use switch, or write non-overlapping conditions
  • Unconditional edges [node] -> [target] can serve as a default path
  • Branch convergence uses OR semantics: the convergence node triggers when any predecessor completes
  • switch is best for equality-based multi-way selection; if is best for complex conditions and binary choices

Next chapter: Tutorial 4: Loops – learn foreach and while to make workflows repeat execution.