Switch switch

When to Use

• Route by order status: Direct orders to separate processing paths for pending, processing, shipped, delivered, and cancelled states each triggering different notifications and API calls.
• Dispatch by webhook event type: Fan out incoming webhook payloads to specialised handlers: order.created, order.updated, payment.received, refund.requested each going to its own processing branch.
• Payment method routing: Apply different processing logic for card, bank_transfer, wallet, and buy_now_pay_later payment instruments — each method has distinct validation and settlement steps.
• Locale-specific processing: Route users to region-specific document templates, tax calculations, and compliance checks based on en-US, en-GB, de-DE, or fr-FR locale values.
• Tier-based feature gating: Gate workflow paths by subscription tier — free, starter, professional, enterprise — applying different rate limits, quotas, and feature sets to each tier.

Configuration

Output Ports

OutputData Fields

Fields available downstream via $output.<nodeKey>:

Sample Configuration

Order status routing

{
  "Expression": "{{ $json.status }}",
  "Cases": {
    "pending":    "handlePending",
    "shipped":    "sendTrackingEmail",
    "cancelled":  "processRefund",
    "delivered":  "requestReview"
  },
  "DefaultPort": "unknownStatus"
}

Webhook event dispatcher

{
  "Expression": "{{ $json.eventType }}",
  "Cases": {
    "order.created":   "onOrderCreated",
    "payment.received": "onPaymentReceived",
    "refund.requested": "onRefundRequested"
  },
  "DefaultPort": "logUnknownEvent"
}

Payment method routing

{
  "Expression": "{{ $json.paymentMethod }}",
  "Cases": {
    "card":          "processCard",
    "bank_transfer": "processBankTransfer",
    "wallet":        "processWallet"
  },
  "DefaultPort": "unsupportedPaymentMethod"
}

Sample Output

Matched Case Port

The input data routes unchanged to whichever case port matches. The _switch metadata indicates which case was matched.

{
  "eventType": "payment.failed",
  "orderId": "ORD-2025-00123",
  "customerId": "cust_007",
  "amount": 4500.00,
  "currency": "USD",
  "failureCode": "card_declined",
  "_switch": {
    "matchedCase": "payment.failed",
    "caseIndex": 2,
    "totalCases": 5
  }
}

Default Port (no case matched)

{
  "eventType": "order.updated",
  "orderId": "ORD-2025-00124",
  "_switch": {
    "matchedCase": null,
    "routedToDefault": true,
    "totalCases": 5
  }
}

Expression Reference

Validation Errors

Node Policies and GuardRails

• Always configure a DefaultPort: External systems introduce new enumeration values without warning. An unwired default port means new values silently drop execution. Route the default port to a logging or alerting node at minimum.
• Log unmatched cases: Connect the default branch to a VariableAssignment that captures the raw unmatched value, then send it to a monitoring or alerting node. This surfaces new values from external systems early.
• Use descriptive port names: Name your case ports for their action, not their value — sendTrackingEmail rather than shipped. The port name appears in workflow visual diagrams and makes intent obvious.
• Prefer Switch over chained IfConditions: For 3 or more branches on a single variable, Switch produces a flat, readable workflow graph. Chained IfConditions create deep nesting that is error-prone to extend.
• Case values are strings: Ensure your expression resolves to the exact string form of your case keys. Numeric values from JSON will be coerced to strings before matching.

Pattern Examples

Pattern 1 — Order Status Fan-Out

A central order processing workflow receives orders in various states. Switch fans each to its dedicated handler, keeping each handler focused on a single state transition.

WebhookTrigger  (order event received)
  └─► Switch  [key: "routeByStatus"]
        Expression:  {{ $json.orderStatus }}
        Cases:       { "pending": "notifyWarehouse", "shipped": "sendTracking",
                       "cancelled": "initiateRefund", "delivered": "requestReview" }
        DefaultPort: "logUnknown"
        ├─► notifyWarehouse ──► SlackNode  (alert warehouse team)
        ├─► sendTracking    ──► EmailSmtp  (email customer tracking link)
        ├─► initiateRefund  ──► HttpRequest (POST /refunds)
        ├─► requestReview   ──► EmailSmtp  (ask for product review)
        └─► logUnknown      ──► VariableAssignment (capture raw status)
                                  └─► SlackNode (alert engineering)

Pattern 2 — Tier-Based Feature Gate

Gate workflow capabilities by subscription tier, applying different processing rules and quotas to each tier.

FormTrigger  (export request submitted)
  └─► Switch  [key: "routeByTier"]
        Expression:  {{ $var.userTier }}
        Cases:       { "free": "limitedExport", "starter": "standardExport",
                       "professional": "fullExport", "enterprise": "fullExport" }
        DefaultPort: "unknownTier"
        ├─► limitedExport   ──► [export max 100 rows, add watermark]
        ├─► standardExport  ──► [export max 10,000 rows]
        ├─► fullExport      ──► [unlimited export, scheduled delivery]
        └─► unknownTier     ──► StopWorkflow

Pattern 3 — Locale-Specific Document Generation

Generate region-appropriate documents by routing to locale-specific template and tax calculation nodes.

FormTrigger  (invoice generation request)
  └─► Switch  [key: "routeByLocale"]
        Expression:  {{ $json.locale }}
        Cases:       { "en-US": "usInvoice", "en-GB": "gbInvoice",
                       "de-DE": "deInvoice",  "fr-FR": "frInvoice" }
        DefaultPort: "defaultInvoice"
        ├─► usInvoice      ──► [USD, US tax rules, Letter format]
        ├─► gbInvoice      ──► [GBP, UK VAT, A4 format]
        ├─► deInvoice      ──► [EUR, German MwSt, A4 format]
        ├─► frInvoice      ──► [EUR, French TVA, A4 format]
        └─► defaultInvoice ──► [USD, no tax, standard template]