Add a While loop step to a workflow

Use a While loop when you want to repeat steps until a condition is met, such as polling for a status change. The loop body always runs at least once before the first condition check.

Before you begin

  • You have access to the workflow builder.
  • The workflow has a trigger step and is in an editable state.

Procedure

  1. Navigate to the Workflows page and select the workflow you want to modify.
  2. Click Add step > Logic > Loop.
  3. In the Type field on the Parameters pane, select While.
  4. In the Conditional expression field, define the condition that determines whether the loop continues. You can use the visual expression builder or write a custom expression. The condition must reference output from a step inside the loop body. For example, ${check_deploy.status} != "complete".
    Note

    In the visual expression builder, the Field input displays variables wrapped in ${...} notation. The field adds the wrapper automatically.
  5. Optional: In the Max iterations field, enter a maximum number of iterations. This acts as a safety limit to prevent infinite loops. If you do not set a value, the system applies a default limit.
  6. Optional: Select the Settings tab and configure the On failure behavior:
    • System default: Uses the system-wide setting configured by an administrator.
    • Continue on failure: The loop stops and the workflow continues to the done path.
    • Stop workflow or branch on failure: The loop stops and the workflow fails.
  7. Click Create or Update to save the step and add it to the canvas.

    A Replace this step to complete the loop placeholder step appears next to the loop step.

  8. Click the placeholder step to open the Add step panel. Select the step type you want to add to the loop.
  9. Click Save to save the step to the canvas.
  10. Click the step you added to the loop to open its configuration. The loop body must contain the step whose output the conditional expression references. Verify that at least one step in the loop body modifies the data that the conditional expression evaluates. If the condition never changes, the loop runs until the maximum iteration limit.
  11. Verify that the last step in the loop body connects back to the loop step. This connection creates the loop cycle.
  12. Connect the Done output of the loop step to the next step that runs after the loop completes.
  13. Click Save to save the workflow.

Results

  1. Run the workflow manually or wait for the configured trigger to start it.

  2. Monitor the workflow run and confirm that:

    • The loop body executes the expected number of iterations. The loop step displays an iteration count badge on the Loop branch handle. The badge shows the current iteration number during execution and the total count when complete.
    • The loop completes and the workflow continues on the done path.
    • Downstream steps can access the loop output, including iteration_count and iteration_results.
    • In the execution detail activity table, each iteration appears as a separate row with the iteration number.
  3. In the execution detail view, confirm that the taken branch handle displays a green border with a checkmark. Skipped path edges display as dashed lines, and skipped downstream steps display with a dashed status icon.