.. _workflow-loop:

.. role:: raw-html(raw)
    :format: html

Loop Process (Node)
==============================

- The Loop functionality provides the ability to repeatedly execute the same workflow process for each element of a given array (Loop Target Items).

Key Features
------------

- **Iterative Processing**: Executes the specified workflow sequentially for each element in the array.
- **Branch Control**: Moves to the 'loop' branch during loop execution and to the 'done' branch upon completion.
- **Result Collection**: Collects the results of each iteration and provides a final array of all results.

Parameter Configuration
-----------------------

To use the Loop process, you must configure the following parameters:

* **Loop Target Items (Required)**

    - Specifies the data array to be processed iteratively.
    - Can be provided as a List object or JSON array string format.
    - Can be dynamically generated using template variables.

    .. code-block:: javascript

        // Direct array specification
        ["item1", "item2", "item3"]

        // Using template variables
        ${previousResult.dataList}

        // JSON string format
        "[{\"id\":1,\"name\":\"first\"},{\"id\":2,\"name\":\"second\"}]"

Branch Structure (Target ID)
-----------------------------

The Loop process uses a special branch structure:

.. code-block:: json

    {
        "loop": "next_process_ID_during_iteration",
        "done": "next_process_ID_after_completion"
    }

- **loop**: Specifies the ID of the next process to be executed during each iteration.
- **done**: Specifies the ID of the process to be executed after all iterations are completed.

Operation Flow
--------------

1. **Initialization**: When the Loop process starts, it parses and validates the items array.
2. **Loop Start**: Outputs the first item as a result and moves to the 'loop' branch.
3. **Loop Progress**: For each iteration, outputs the current item and collects previous results.
4. **Completion**: When all items are processed, outputs the complete results and moves to the 'done' branch.

Result Data
-----------

The Loop process provides different results depending on the iteration status:

* **During Iteration**: JSON string of the currently processed item
* **Upon Completion**: JSON string of an array containing all iteration results

Usage Example
-------------

The following is an example of a Loop workflow for sending emails to a user list:

.. code-block:: javascript

    // Loop process parameters
    {
        "items": [
            {"email": "user1@example.com", "name": "John Smith"},
            {"email": "user2@example.com", "name": "Jane Doe"},
            {"email": "user3@example.com", "name": "Mike Johnson"}
        ]
    }

    // Data output for each iteration
    // 1st iteration: {"email": "user1@example.com", "name": "John Smith"}
    // 2nd iteration: {"email": "user2@example.com", "name": "Jane Doe"}
    // 3rd iteration: {"email": "user3@example.com", "name": "Mike Johnson"}
    
    // Final result upon completion: Array containing all iteration results

Limitations and Considerations
------------------------------

- **Maximum Item Count**: The maximum size of the items array is limited (1000) for performance and stability.
- **Empty Array Handling**: An error occurs when an empty array is input, so prior validation is required.
- **Memory Usage**: Memory usage should be considered when processing large volumes of data.
- **Infinite Loop Prevention**: Validation is included to prevent infinite loops due to incorrect branch configuration.

Template Variable Usage
-----------------------

The Loop process can utilize the following template variables:

.. code-block:: javascript

    // Using previous process results as items
    {
        "items": "${httpRequest.responseData}"
    }

    // Using conditionally filtered items
    {
        "items": "${filteredItems}"
    }

Error Handling
--------------

The Loop process generates errors in the following situations:

- When the items parameter is missing or null
- When items is not in the correct array format
- When the array is empty
- When the maximum item count is exceeded
- When the iteration index is invalid

These errors will halt workflow execution, so it is recommended to perform data validation beforehand.