Skip to main content

Switch

Enables conditional branching within workflows. Based on a set of conditions evaluated at runtime, the Switch task determines the next flow directive to execute.

When to use​

Use Switch when you need to route execution to different tasks based on the value of workflow state or input data.

Properties​

NameTypeRequiredDescription
switchcase[]yesA name/value map of the cases to switch on

Switch case​

NameTypeRequiredDescription
whenstringnoA runtime expression that evaluates to a boolean. If the expression is truthy, this case matches.
If not set, this case is the default and matches when no other case matches.
Only one default case is allowed.
thenflowDirectiveyesThe flow directive to execute when the case matches.

How it works​

Cases are evaluated in order. The first case whose when expression evaluates to true wins. If no case matches, the default case (where when is absent) is used.

When a case matches, its then flow directive determines what happens next: execution may continue to the next task, jump to a named task, exit the current scope or end the workflow.

Example​

This workflow routes an order through different processing steps depending on $input.orderType:

document:
  dsl: 1.0.0
  taskQueue: zigflow
  workflowType: order-router
  version: 1.0.0
do:
  - routeOrder:
      switch:
        - electronic:
            when: ${ $input.orderType == "electronic" }
            then: processElectronicOrder
        - physical:
            when: ${ $input.orderType == "physical" }
            then: processPhysicalOrder
        - default:
            then: handleUnknownType

  - processElectronicOrder:
      do:
        - validatePayment:
            call: http
            with:
              method: get
              endpoint: https://jsonplaceholder.typicode.com/posts/1
        - fulfillOrder:
            call: http
            with:
              method: get
              endpoint: https://jsonplaceholder.typicode.com/posts/2

  - processPhysicalOrder:
      do:
        - checkInventory:
            call: http
            with:
              method: get
              endpoint: https://jsonplaceholder.typicode.com/posts/3

  - handleUnknownType:
      raise:
        error:
          type: https://serverlessworkflow.io/spec/1.0.0/errors/validation
          status: 400
          title: Unknown order type
          detail: ${ "Received order type: " + $input.orderType }

When triggered with { "orderType": "electronic" }, the switch selects processElectronicOrder as the next branch to execute.

Using flow directives​

The then property accepts any flow directive:

- classify:
    switch:
      - urgent:
          when: ${ $input.priority == "high" }
          then: escalate       # Jump to a named task
      - empty:
          when: ${ $input.items | length == 0 }
          then: end            # End the workflow immediately
      - default:
          then: continue       # Proceed to the next task

Gotchas​

Cases are evaluated in declaration order. Place more specific conditions before broader ones to avoid unintended matches.

A missing default case is valid but risky. If no case matches and there is no default, execution falls through to the next task in the do list. This is rarely intentional. Include a default case to make intent explicit.

Named then directives target a task by name. The named task must exist within the current workflow scope. Referencing a non-existent task fails at validation.

end terminates the workflow. Use exit when you only want to leave the current scope, such as a nested do or loop.