While

The While stage iterates over a sequence of transformations until a specified condition is met.

Stage Processing

This stage continues until the loop condition evaluates to false or an error occurs during processing.

Returning Values

Use the Return Stage to return a value during each loop iteration. Depending on the configured Loop Value, the returned value may be included in the generated output.

Metadata Chaining

Metadata chaining ensures that updates to metadata are reflected in subsequent loop iterations. By returning modified metadata along with a value, the updated metadata object becomes available in the next iteration.

Metadata

During the loop, the metadata payload includes a loopIndex that indicates the index of the current iteration.

Success and Failure Paths

• Success path: If all iterations complete successfully and the condition evaluates to false, the configured Loop Value and updated metadata are passed down the success path.
• Failure path: If any iteration fails for reasons other than a timeout, the stage follows the failure path.

Note: If a failure path is specified, all failures except a timeout will not cause the stage to go into an error state.

Settings

Loop Condition

The loop condition is a JavaScript expression that determines whether the loop continues. Return true to continue processing or false to stop. The expression must return a boolean value; otherwise, the stage will produce an error. The condition is evaluated after each iteration.

/**
 * Loop Stage Variable
 *
 * Contains the result(s) of loop iterations.
 */
let loop: {
    /**
     * The number of times the loop has run
     */
    runCount: number,
    /**
     * The value associated with the most recent run
     *
     * Can be an array of values (Accumulated), the incoming value to the stage (Incoming), or the last return value (Last Return) depending on the Loop Value configuration.
     */
    value: any | any[],
    /**
     * The metadata associated with the latest run result
     */
    metadata: any
};

Loop Value

Controls the starting value for each loop and the output value of the stage. The available options are:

• Accumulated: All values returned from each iteration are collected in a single array (starting as [] on the first pass). If an array is returned during an iteration, it is flattened into the accumulated value, ensuring a one-dimensional array.
  • Common for pagination-style use cases when collecting array returns.
• Incoming: The original incoming value (e.g., event.value) of the While stage. This value remains unchanged by other values returned during looping.
  • Useful for scenarios where work is performed inside the loop, leveraging solutions like metadata chaining.
• Last Return: The output is the last value returned across all iterations. If no value is returned, the incoming value is used as the output.
  • Common for transactional use cases that wait for an update to happen

Stage Timeout

Defines the maximum time a stage can spend processing an event. If the timeout is reached before processing completes, all remaining operations are canceled.

Example

Use Case: Paginating Through Sensor Data

Description

Retrieve sensor data from a paginated API. Each page contains a subset of sensor readings, and the While stage is used to iterate through all pages until no more data is available. The loop condition checks the isComplete flag in the metadata to determine when the loop is done. The accumulated results are built up over multiple iterations.

Settings

• Loop Condition:

// Keep looping while isComplete has not been set
return !loop.metadata.isComplete

• Loop Value: Accumulated
• Stage Timeout: 30 seconds

Iteration Details

Iteration 1

• Starting Value:

  []
  

• Value Read:

  [
    { "sensorId": "S1", "value": 100 },
    { "sensorId": "S2", "value": 200 }
  ]
  

• Metadata Returned:

  { "loopIndex": 0, "isComplete": false }
  

• Data Returned:

  [
    { "sensorId": "S1", "value": 100 },
    { "sensorId": "S2", "value": 200 }
  ]
  

Iteration 2

• Starting Value:

  [
    { "sensorId": "S1", "value": 100 },
    { "sensorId": "S2", "value": 200 }
  ]
  

• Value Read:

  [
    { "sensorId": "S3", "value": 300 },
    { "sensorId": "S4", "value": 400 }
  ]
  

• Metadata Returned:

  { "loopIndex": 1, "isComplete": false }
  

• Data Returned:

  [
    { "sensorId": "S3", "value": 300 },
    { "sensorId": "S4", "value": 400 }
  ]
  

Iteration 3

• Starting Value:

  [
    { "sensorId": "S1", "value": 100 },
    { "sensorId": "S2", "value": 200 },
    { "sensorId": "S3", "value": 300 },
    { "sensorId": "S4", "value": 400 }
  ]
  

• Value Read:

  [
    { "sensorId": "S5", "value": 500 }
  ]
  

• Metadata Returned:

  { "loopIndex": 2, "isComplete": true }
  

• Data Returned:

  [
    { "sensorId": "S5", "value": 500 }
  ]
  

Final Output Value

[
  { "sensorId": "S1", "value": 100 },
  { "sensorId": "S2", "value": 200 },
  { "sensorId": "S3", "value": 300 },
  { "sensorId": "S4", "value": 400 },
  { "sensorId": "S5", "value": 500 }
]