> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noxus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Conditionals & Branching

> Control workflow execution with conditional logic and branching

Conditionals enable your workflows to make decisions and take different paths based on data, creating dynamic, intelligent automation.

## Conditional Nodes

### Switch Node

The **Switch Node** enables multi-branch conditional routing with complex conditions.

**Key Features**:

* Multiple condition paths
* Complex condition builder
* Default fallback path
* Priority-based evaluation (top to bottom)

**Use Cases**:

* Multi-way decisions (if/elif/elif/else)
* Routing based on categories
* Complex business logic
* State machines

### Conditional Node

The **Conditional Node** provides simple if/else branching.

**Key Features**:

* Two paths: true and false
* Single condition
* Simpler than Switch for binary decisions

**Use Cases**:

* Yes/no decisions
* Binary states
* Simple validation checks

## Connecting branches in V2

To run a step only on a branch, connect that branch's output handle to the step. When building through the API, set the edge's `source_handle` to `when_true`, `when_false`, or the Switch branch ID. Validation rejects routing edges that omit this field. Use `output` explicitly for a data dependency without branch gating. Putting a branch-handle reference in a Combine Text template does not gate execution.

Multiple handles connected directly from the **same routing node** combine with OR: the receiving step can run when any connected handle fires, provided its other sources are live. For example, connecting both Conditional handles directly to one step allows it to run for either outcome.

An ordinary step skips when **any distinct source** is dead. If each mutually exclusive branch has its own processing step, connect those steps to **Join Paths** (`MergePathsNode`) before continuing. Join Paths skips only when all its sources are dead.

## Building Conditions

### Condition Builder

Both Switch and Conditional nodes use a visual condition builder:

**Components**:

1. **Left Value**: The data to evaluate
2. **Operator**: Comparison type
3. **Right Value**: Value to compare against

### Operators

**Text Operators**:

* `equals`: Exact match
* `not equals`: Not an exact match
* `contains`: Substring match
* `not contains`: Doesn't contain substring
* `starts with`: Begins with text
* `ends with`: Ends with text
* `matches regex`: Regex pattern match
* `is empty`: Empty string or null
* `is not empty`: Has value

**Number Operators**:

* `equals`: Equal to
* `not equals`: Not equal to
* `greater than`: >
* `less than`: \<
* `greater than or equal`: >=
* `less than or equal`: \<=

**Boolean Operators**:

* `is true`: Value is true
* `is false`: Value is false

**List Operators**:

* `contains`: List contains item
* `not contains`: List doesn't contain item
* `is empty`: Empty list
* `is not empty`: Has items
* `length equals`: List length equals number
* `length greater than`: List length > number
* `length less than`: List length \< number

### Complex Conditions

Combine multiple conditions with AND/OR logic:

**AND Condition** (all must be true):

```
Condition 1: status equals "approved"
AND
Condition 2: amount greater than 1000
```

**OR Condition** (at least one must be true):

```
Condition 1: priority equals "high"
OR
Condition 2: priority equals "urgent"
```

**Nested Conditions**:

```
(Condition 1 AND Condition 2) OR Condition 3
```

## Switch Node Patterns

### Basic Multi-Way Branching

**Example: Customer Type Routing**

```
Switch Node: customer_type
├─ Case 1: customer_type equals "new"
│   → Send onboarding email
├─ Case 2: customer_type equals "active"
│   → Send product update
├─ Case 3: customer_type equals "churned"
│   → Send win-back offer
└─ Default:
    → Log unknown type
```

### Priority Evaluation

Conditions are evaluated **top to bottom**, first match wins:

```
Switch Node: order_value
├─ Case 1: value greater than 10000
│   → VIP processing
├─ Case 2: value greater than 1000
│   → Priority processing
├─ Case 3: value greater than 100
│   → Standard processing
└─ Default:
    → Economy processing
```

**Important**: Order matters! A value of 15000 matches Case 1 and won't reach Case 2.

### Category-Based Routing

**Example: Support Ticket Routing**

```
Switch Node: ticket_category
├─ Case 1: category contains "billing"
│   → Route to billing team
├─ Case 2: category contains "technical"
│   → Route to tech support
├─ Case 3: category contains "sales"
│   → Route to sales team
└─ Default:
    → Route to general queue
```

### State Machine Pattern

**Example: Order Status Processing**

```
Switch Node: order_status
├─ Case 1: status equals "pending_payment"
│   → Process payment
├─ Case 2: status equals "paid"
│   → Prepare shipment
├─ Case 3: status equals "shipped"
│   → Track delivery
├─ Case 4: status equals "delivered"
│   → Request feedback
└─ Default:
    → Log invalid status
```

## Conditional Node Patterns

### Simple Validation

**Example: Email Validation**

```
Conditional Node: email_valid
├─ True (email contains "@" AND email contains ".")
│   → Continue processing
└─ False
    → Send error notification
```

### Threshold Checking

**Example: Approval Workflow**

```
Conditional Node: requires_approval
├─ True (amount greater than 5000)
│   → Human in the Loop (approval)
└─ False
    → Auto-approve
```

### Null/Empty Checking

**Example: Optional Field Handling**

```
Conditional Node: has_attachment
├─ True (attachment is not empty)
│   → Process attachment
└─ False
    → Skip attachment processing
```

## Common Patterns

### Pattern 1: Validation Chain

Multiple validation checks in sequence:

```
Input
    ↓
Conditional 1: email is valid
    ├─ True → Continue
    └─ False → Error: Invalid email
    ↓
Conditional 2: company exists
    ├─ True → Continue
    └─ False → Error: Unknown company
    ↓
Conditional 3: has permission
    ├─ True → Process
    └─ False → Error: Unauthorized
```

### Pattern 2: Early Exit

Check for error conditions early and exit:

```
Input
    ↓
Conditional: data is empty
    ├─ True → Return error, exit workflow
    └─ False → Continue processing
    ↓
(rest of workflow)
```

### Pattern 3: Confidence-Based Routing

Route based on AI confidence scores:

```
AI Analysis (returns confidence score)
    ↓
Switch Node: confidence
├─ Case 1: confidence greater than 90
│   → Auto-process
├─ Case 2: confidence greater than 70
│   → Review by junior staff
├─ Case 3: confidence greater than 50
│   → Review by senior staff
└─ Default
    → Reject and re-process
```

### Pattern 4: Feature Flags

Enable/disable features dynamically:

```
Conditional: feature_enabled
├─ True → Use new processing logic
└─ False → Use legacy processing logic
```

### Pattern 5: A/B Testing

Route to different logic for testing:

```
Switch Node: experiment_group
├─ Case 1: group equals "A"
│   → Original workflow
├─ Case 2: group equals "B"
│   → Experimental workflow
└─ Default
    → Control group (no special handling)
```

## Advanced Techniques

### Chaining Conditionals

Combine multiple conditionals for complex logic:

```
Conditional 1: is_premium_user
    ├─ True
    │   ↓
    │   Conditional 2: has_addon
    │       ├─ True → Premium + Addon flow
    │       └─ False → Premium only flow
    └─ False
        ↓
        Conditional 3: is_trial_user
            ├─ True → Trial flow
            └─ False → Free flow
```

### Computed Conditions

Use data from previous nodes in conditions:

```
API Request (get user data)
    ↓
Extract Information (extract subscription_tier, last_login_days)
    ↓
Switch Node: subscription_tier + last_login_days
├─ Case 1: subscription_tier equals "pro" AND last_login_days less than 7
│   → Active pro user flow
├─ Case 2: subscription_tier equals "pro" AND last_login_days greater than 30
│   → Inactive pro user (re-engagement)
└─ Default
    → Other user types
```

### Dynamic Routing Table

Use data lookup for routing decisions:

```
Airtable Read (routing rules table)
    ↓
Filter List (find matching rule)
    ↓
Conditional: rule_found
    ├─ True → Route based on rule
    └─ False → Use default routing
```

## Working with Lists

### List-Based Conditions

Conditionals work with list data:

```
Conditional: errors is not empty
    ├─ True → Handle errors
    └─ False → Continue
```

```
Conditional: results length greater than 10
    ├─ True → Paginate results
    └─ False → Show all results
```

### Filtering Lists

Use Filter List node for list-based conditionals:

```
List of Orders
    ↓
Filter List: amount greater than 1000
    ↓
Filtered High-Value Orders
```

### Conditional List Processing

Apply different processing based on list characteristics:

```
Process Items
    ↓
Conditional: processed_count equals input_count
    ├─ True → All items processed successfully
    └─ False → Some items failed
        ↓
        Filter List: status equals "failed"
        ↓
        Retry Failed Items
```

## Error Handling with Conditionals

### Check for Errors

```
API Request (continue on error: true)
    ↓
Conditional: response is empty (indicates error)
    ├─ True
    │   ↓
    │   Log Error
    │   ↓
    │   Send Alert
    │   ↓
    │   Return Error Output
    └─ False
        ↓
        Process Response
```

### Retry Logic

```
Loop (max 3 iterations)
    ├─ Try Operation
    ├─ Conditional: operation succeeded
    │   ├─ True → Exit loop
    │   └─ False → Continue loop (retry)
    └─ (next iteration)
```

### Fallback Logic

```
Primary API Request (continue on error: true)
    ↓
Conditional: primary request succeeded
    ├─ True → Use primary result
    └─ False
        ↓
        Fallback API Request
        ↓
        Conditional: fallback succeeded
            ├─ True → Use fallback result
            └─ False → Return error
```

## Debugging Conditionals

### Common Issues

**Condition Never True**:

* Check data types (string "1" vs number 1)
* Verify exact spelling and casing
* Use log nodes to inspect actual values

**Wrong Path Taken**:

* Check condition order in Switch node
* Verify AND/OR logic
* Test with known values

**Null/Empty Handling**:

* Add explicit null checks
* Use "is empty" / "is not empty" operators
* Provide default values upstream

### Testing Tips

**Use Test Data**:

* Test with known values that should match each path
* Verify all branches are reachable

**Log Values**:

* Add Log Value nodes before conditionals
* Inspect actual data types and values
* Verify condition variables exist

**Edge Cases**:

* Test with null/empty values
* Test with extreme values (very large, very small)
* Test with unexpected data types

## Best Practices

### Design

**Keep Conditions Simple**: Complex conditions are hard to debug

**Use Descriptive Names**: Name conditional paths clearly

**Avoid Deep Nesting**: More than 3 levels of nesting is hard to follow

**Prefer Switch Over Chained Conditionals**: For 3+ branches, use Switch node

**Handle Default Cases**: Always include default/fallback paths

### Performance

**Early Exit**: Check expensive conditions last

**Compute Once**: Store computed values, don't recalculate in each condition

**Minimize Branching**: Fewer branches = simpler workflows

### Maintainability

**Document Complex Logic**: Add comments to workflows explaining business rules

**Use Subflows**: Extract complex conditional logic into subflows

**Centralize Rules**: Consider storing rules in databases/config for easy updates

## Example Workflows

### Example 1: Lead Scoring and Routing

```
Lead Input (name, email, company, title, industry)
    ↓
Switch Node: industry
├─ Case 1: industry equals "Technology"
│   ↓
│   Switch Node: title
│   ├─ Case 1: title contains "CTO" OR title contains "VP"
│   │   → Score: 100 (Hot lead, assign to senior sales)
│   ├─ Case 2: title contains "Director" OR title contains "Manager"
│   │   → Score: 75 (Warm lead, assign to mid-level sales)
│   └─ Default
│       → Score: 50 (Standard lead, assign to SDR)
│
├─ Case 2: industry equals "Finance"
│   → Score: 90 (High-value vertical, assign to specialist)
│
└─ Default
    → Score: 40 (General lead, assign to pool)
    ↓
CRM Update (lead score and assignment)
    ↓
Conditional: score greater than 80
    ├─ True → Send immediate alert to assigned rep
    └─ False → Add to standard queue
```

### Example 2: Invoice Approval Workflow

```
Invoice Input (invoice_number, amount, vendor, department)
    ↓
Conditional: amount less than 500
├─ True → Auto-approve (threshold)
└─ False
    ↓
    Conditional: vendor is in approved_vendors list
    ├─ True
    │   ↓
    │   Switch Node: department
    │   ├─ Case 1: department equals "IT" AND amount less than 5000
    │   │   → Manager approval only
    │   ├─ Case 2: amount less than 10000
    │   │   → Department head approval
    │   └─ Default
    │       → CFO approval required
    └─ False → Vendor verification + CFO approval required
```

### Example 3: Content Moderation

```
User-Generated Content Input
    ↓
AI Sentiment Analysis
    ↓
AI Content Classification (toxicity, spam, etc.)
    ↓
Switch Node: content_status
├─ Case 1: toxicity_score greater than 0.8
│   → Auto-reject + Flag for review
│
├─ Case 2: toxicity_score greater than 0.5 AND toxicity_score less than 0.8
│   → Hold for manual review
│
├─ Case 3: spam_score greater than 0.7
│   → Auto-reject as spam
│
├─ Case 4: sentiment equals "positive" AND toxicity_score less than 0.2
│   → Auto-approve
│
└─ Default
    → Standard approval queue
```

## Next Steps

> **[Loops](https://docs.noxus.ai/building/logic/loops)**
>
> Iterate with loop control

> **[Subflows](https://docs.noxus.ai/building/logic/subflows)**
>
> Modular workflow components

> **[Error Handling](https://docs.noxus.ai/building/logic/error-handling)**
>
> Graceful error recovery

> **[List Handling](https://docs.noxus.ai/building/fundamentals/list-handling)**
>
> Automatic list iteration

***

Conditionals are essential for building intelligent, dynamic workflows that adapt to data and make decisions automatically.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.