.. _workflow-loop:

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

Loop 프로세스(노드)
==============================

- Loop 기능은 주어진 배열(Loop 대상 항목)의 각 요소에 대해 동일한 워크플로우 과정을 반복 실행하는 기능을 제공합니다.

주요 특징
----------

- **반복 처리**: 배열의 각 요소에 대해 지정된 워크플로우를 순차적으로 실행합니다.
- **분기 제어**: 루프 진행 중에는 'loop' 분기로, 완료 시에는 'done' 분기로 이동합니다.
- **결과 수집**: 각 반복의 결과를 수집하여 최종적으로 전체 결과 배열을 제공합니다.

파라미터 설정
-------------

Loop 프로세스를 사용하기 위해서는 다음 파라미터를 설정해야 합니다:

* **Loop 대상 항목 (필수)**

    - 반복 처리할 데이터 배열을 지정합니다.
    - List 객체 또는 JSON 배열 문자열 형태로 제공할 수 있습니다.
    - 템플릿 변수를 사용하여 동적으로 생성할 수 있습니다.

    .. code-block:: javascript

        // 직접 배열 지정
        ["item1", "item2", "item3"]

        // 템플릿 변수 사용
        ${previousResult.dataList}

        // JSON 문자열 형태
        "[{\"id\":1,\"name\":\"첫번째\"},{\"id\":2,\"name\":\"두번째\"}]"

분기 구조 (Target ID)
---------------------

Loop 프로세스는 특별한 분기 구조를 사용합니다:

.. code-block:: json

    {
        "loop": "반복_진행중_다음_프로세스_ID",
        "done": "반복_완료후_다음_프로세스_ID"
    }

- **loop**: 각 반복 시 실행될 다음 프로세스의 ID를 지정합니다.
- **done**: 모든 반복이 완료된 후 실행될 프로세스의 ID를 지정합니다.

동작 흐름
---------

1. **초기화**: Loop 프로세스가 시작되면 items 배열을 파싱하고 검증합니다.
2. **반복 시작**: 첫 번째 아이템을 결과로 출력하고 'loop' 분기로 이동합니다.
3. **반복 진행**: 각 반복마다 현재 아이템을 출력하고 이전 결과를 수집합니다.
4. **완료 처리**: 모든 아이템 처리가 완료되면 전체 결과를 출력하고 'done' 분기로 이동합니다.

결과 데이터
-----------

Loop 프로세스는 반복 상황에 따라 다른 결과를 제공합니다:

* **반복 진행 중**: 현재 처리 중인 아이템의 JSON 문자열
* **반복 완료 시**: 모든 반복 결과를 포함하는 배열의 JSON 문자열

사용 예시
---------

다음은 사용자 목록에 대해 이메일을 발송하는 Loop 워크플로우 예시입니다:

.. code-block:: javascript

    // Loop 프로세스 파라미터
    {
        "items": [
            {"email": "user1@example.com", "name": "김철수"},
            {"email": "user2@example.com", "name": "이영희"},
            {"email": "user3@example.com", "name": "박민수"}
        ]
    }

    // 각 반복에서 출력되는 데이터
    // 1회차: {"email": "user1@example.com", "name": "김철수"}
    // 2회차: {"email": "user2@example.com", "name": "이영희"}
    // 3회차: {"email": "user3@example.com", "name": "박민수"}
    
    // 완료 시 최종 결과: 모든 반복 결과가 포함된 배열

제한 사항 및 주의사항
--------------------

- **최대 항목 수**: 성능과 안정성을 위해 items 배열의 최대 크기(1000)가 제한됩니다.
- **빈 배열 처리**: 빈 배열이 입력되면 오류가 발생하므로 사전에 검증이 필요합니다.
- **메모리 사용**: 대용량 데이터 처리 시 메모리 사용량을 고려해야 합니다.
- **무한 루프 방지**: 잘못된 분기 설정으로 인한 무한 루프를 방지하기 위한 검증이 포함되어 있습니다.

템플릿 변수 활용
---------------

Loop 프로세스에서는 다음과 같은 템플릿 변수를 활용할 수 있습니다:

.. code-block:: javascript

    // 이전 프로세스 결과를 items로 사용
    {
        "items": "${httpRequest.responseData}"
    }

    // 조건부로 아이템 필터링 후 사용
    {
        "items": "${filteredItems}"
    }

오류 처리
---------

Loop 프로세스는 다음과 같은 상황에서 오류를 발생시킵니다:

- items 파라미터가 누락되거나 null인 경우
- items가 올바른 배열 형식이 아닌 경우
- 배열이 비어있는 경우
- 최대 항목 수를 초과하는 경우
- 반복 인덱스가 유효하지 않은 경우

이러한 오류들은 워크플로우 실행을 중단시키므로, 사전에 데이터 검증을 수행하는 것이 좋습니다.