> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 워크플로우 FAQ

> Twenty의 워크플로우에 관한 자주 묻는 질문입니다.

<AccordionGroup>
  <Accordion title="워크플로우를 활성화할 수 없는 이유는 무엇인가요?">
    이는 권한 문제일 가능성이 높습니다. 워크플로우를 생성하고 활성화하려면 워크플로우에 대한 접근 권한이 필요합니다.

    **해결 방법**: 워크스페이스 관리자에게 문의하여 **Settings → Members → Roles**에서 워크플로 액세스 권한을 부여받으세요.

    사이드바에서 워크플로우 섹션이 전혀 보이지 않는다면, 이는 권한 문제임이 확실합니다.
  </Accordion>

  <Accordion title="상단 내비게이션 바에서 수동 워크플로우 버튼이 보이지 않는 이유는 무엇인가요?">
    수동 워크플로우는 올바르게 구성된 경우에만 내비게이션 바에 표시됩니다:

    1. 워크플로우가 **활성화**되어 있어야 합니다(초안 모드 아님)
    2. navbar 배치는 **Pinned**로 설정되어 있어야 합니다
    3. Single/Bulk 트리거의 경우 올바른 오브젝트 페이지에 있어야 합니다

    **확인 방법**: 워크플로우를 연 다음 → 트리거를 클릭 → "Navbar placement"가 "Pinned"로 설정되어 있는지 확인합니다.

    내비게이션 바 설정과 관계없이 **Cmd + K**(또는 **Ctrl + K**)를 통해 언제든지 수동 워크플로우에 접근할 수 있습니다.
  </Accordion>

  <Accordion title="Single, Global, Bulk 수동 트리거의 차이점은 무엇인가요?">
    | 유형            | 필요한 레코드   | Workflow 실행들           |
    | ------------- | --------- | ---------------------- |
    | \| **Global** | 없음        | 한 번 실행, 레코드 입력 없음      |
    | \| **Single** | 하나 이상 선택됨 | 선택된 레코드마다 한 번씩 실행      |
    | \| **Bulk**   | 하나 이상 선택됨 | 한 번 실행, 모든 레코드를 배열로 처리 |

    * **Global**: 워크플로우에 레코드 컨텍스트가 필요하지 않을 때 사용합니다(예: 리포트 생성)
    * **Single**: 선택된 각 레코드를 개별적으로 처리하려는 경우에 사용합니다(예: 개별 이메일 발송)
    * **Bulk**: 레코드를 함께 처리하거나 크레딧 사용을 최적화해야 할 때 사용합니다(Iterator 액션 필요)

    자세한 내용은 [Workflow Triggers](/l/ko/user-guide/workflows/capabilities/workflow-triggers)를 참조하세요.
  </Accordion>

  <Accordion title="If/Else 노드가 보이지 않습니다. 어떻게 해야 하나요?">
    명시적인 If/Else 노드는 아직 제공되지 않지만 로드맵에 포함되어 있습니다.

    **현재 우회 방법**: 단계에서 여러 분기를 만들고, 각 분기의 첫 단계로 **Filter** 액션을 추가하세요:

    ```
    Step 1
       │
       ├── Branch A: Filter (condition = true) → Actions...
       │
       └── Branch B: Filter (condition = false) → Actions...
    ```

    Filter 조건을 통과한 분기만 이후 액션을 실행합니다.

    단계별 안내는 [How to Use Branches](/l/ko/user-guide/workflows/capabilities/workflow-branches)를 참고하세요.
  </Accordion>

  <Accordion title="워크플로우 분기는 병렬로 실행되나요?">
    **예**, 분기는 기본적으로 병렬로 실행됩니다.

    하나의 분기만 실행되도록 하려면:

    * 각 분기의 시작 부분에 **Filter** 액션을 추가합니다
    * 서로 반대되는 조건을 설정합니다(예: 분기 A: status = "Open", 분기 B: status ≠ "Open")

    Filter 조건을 만족하지 못한 분기는 실행이 중지되고, 다른 분기는 계속 실행됩니다.
  </Accordion>

  <Accordion title="분기를 다시 병합할 수 있나요?">
    **예**. 병렬 분기가 완료된 후, 두 분기 모두가 연결되는 단계를 추가할 수 있습니다.

    워크플로우 편집기에서:

    1. 분기된 액션을 완료합니다
    2. 분기 이후에 실행될 새 단계를 추가합니다
    3. 각 분기의 마지막 단계에서 이 새 단계로 연결선을 드래그합니다

    모든 연결된 분기가 완료된 후 병합된 단계가 실행됩니다.
  </Accordion>

  <Accordion title="Search Records 결과의 한도는 얼마인가요?">
    **Search Records는 최대 200개 레코드를 반환합니다.**

    더 많은 레코드를 처리해야 하는 경우:

    * 결과를 줄이기 위해 더 구체적인 필터를 추가합니다
    * 배치 처리를 위해 예약된 워크플로우를 사용합니다
    * 대량 작업에는 API 사용을 고려합니다

    대부분의 워크플로우에는 200개 레코드면 충분합니다. 이 한도에 자주 도달한다면 자동화 구조를 재설계하는 것을 고려하세요.
  </Accordion>

  <Accordion title="워크플로우 이메일에 사람들을 CC로 포함할 수 있나요?">
    **아직은 불가능합니다.** Send Email 액션의 CC 및 BCC 필드는 로드맵에 포함되어 있습니다.

    **현재 우회 방법**: 추가 수신자에게 이메일을 보내기 위해 여러 개의 Send Email 액션을 추가하거나, CC를 지원하는 외부 이메일 서비스를 통해 전송하도록 HTTP Request를 사용하세요.
  </Accordion>

  <Accordion title="이전 단계의 출력을 어떻게 사용하나요?">
    모든 액션은 이후 단계에서 사용할 수 있는 출력 데이터를 생성합니다.

    **이전 단계 데이터를 참조하려면**:

    * 필드를 구성할 때 변수 선택기를 사용합니다
    * 또는 `{{stepName.fieldName}}`을 직접 입력합니다

    **예시**:

    * 트리거 데이터: `{{trigger.object.email}}`
    * 검색 결과: `{{searchRecords[0].name}}`
    * 코드 출력: `{{code.calculatedValue}}`

    액션 구성에서 임의의 필드 위에 마우스를 올리면 이전 단계에서 사용할 수 있는 변수를 확인할 수 있습니다.
  </Accordion>

  <Accordion title="Iterator가 실패하는 이유는 무엇인가요?">
    **Iterator에는 배열 입력이 필요합니다.** 일반적인 문제는 다음과 같습니다:

    1. **입력이 배열이 아님**: Search Records 또는 배열을 반환하는 다른 액션의 결과를 전달하고 있는지 확인합니다
    2. **배열이 비어 있음**: `{{searchRecords.length}} > 0`을 확인하는 Filter를 Iterator 앞에 추가하세요
    3. **잘못된 변수가 선택됨**: 단일 레코드가 아니라 배열 자체를 선택했는지 확인합니다

    **올바른 설정**:

    1. Search Records(배열 반환)
    2. Filter: length > 0
    3. Iterator: `{{searchRecords}}` 선택
    4. Iterator 내부의 액션은 `{{iterator.currentItem.fieldName}}`을 사용합니다
  </Accordion>

  <Accordion title="Code 액션의 최대 실행 시간은 얼마인가요?">
    코드 액션(로직 함수)에는 **5분의 기본 제한 시간** (300초)이 있습니다.

    최대로 설정할 수 있는 타임아웃은 **15분**(900초)입니다.

    코드 실행 시간이 이 한도를 초과하면 액션은 타임아웃 오류와 함께 실패합니다.

    **타임아웃을 피하기 위한 팁**:

    * Iterator를 사용해 대규모 작업을 더 작은 단위로 나눕니다
    * 무거운 연산은 피하고, 많은 연산이 필요한 경우 HTTP Request를 통해 외부 서비스를 사용하세요
    * 코드를 최적화하여 실행 시간을 줄이세요
    * 더 긴 처리가 필요하다면 데이터를 배치로 처리하는 예약된 워크플로우 사용을 고려하세요
  </Accordion>

  <Accordion title="워크플로우 실행 내역은 어떻게 읽나요?">
    워크플로우 실행 내역은 실행 이력을 보여주며 문제를 디버깅하는 데 도움이 됩니다.

    **실행 내역에 접근하려면**:

    * 워크플로우 편집기에서 → 오른쪽의 **Runs** 패널을 엽니다
    * 또는 사이드바에서 **워크플로우 실행**으로 이동합니다

    **실행 내역 이해하기**:

    * **Status**: Running, Completed, Failed, Waiting
    * **Steps**: 어떤 단계가 실행되었고 어떤 출력을 생성했는지 확인합니다
    * **Errors**: 실패한 단계를 클릭하여 오류 메시지를 확인합니다
    * **Data**: 각 단계에서 입력 및 출력 데이터를 확인합니다

    자세한 내용은 [Workflow Runs](/l/ko/user-guide/workflows/capabilities/workflow-runs)를 참조하세요.
  </Accordion>

  <Accordion title="워크플로우 실행 내역이 보이지 않는 이유는 무엇인가요?">
    워크플로우 실행이 레이트 리밋 때문에 즉시 실패하고 있을 수 있습니다.

    **하드 한도: 워크스페이스당 시간당 5,000회 실행.**

    이 한도를 초과하면 워크플로우는 즉시 실패로 표시되며, 실행 내역 목록에 예상대로 나타나지 않습니다.

    **이 한도에 도달하기 쉬운 일반적인 시나리오**:

    * Single 수동 트리거로 5,000개가 넘는 레코드를 선택하는 경우
    * 워크스페이스 전체에서 여러 워크플로우가 동시에 실행되는 경우
    * (예: 트래픽이 많은 오브젝트에서의 Record Updated 트리거와 같은) 고빈도 자동 트리거

    **해결책**:

    * 많은 레코드를 한 번에 처리해야 할 때는 Single 대신 **Bulk** 트리거를 사용합니다
    * 대규모 배치 작업 사이에 간격을 두어 실행합니다
    * 트리거 빈도를 줄이기 위해 필터를 사용합니다
    * 부하가 큰 워크플로우는 피크 타임이 아닌 시간대에 예약 실행하세요
  </Accordion>

  <Accordion title="워크플로우 레이트 리밋은 무엇인가요?">
    Twenty는 시스템 안정성을 보장하기 위해 두 가지 레이트 리밋을 적용합니다:

    | 한도                | 값             | 동작                                 |
    | ----------------- | ------------- | ---------------------------------- |
    | \| **Soft limit** | 분당 100회 실행    | "Not Started" 상태로 큐에 쌓인 뒤 점진적으로 처리 |
    | \| **Hard limit** | 시간당 5,000회 실행 | 실행이 즉시 실패                          |

    **Soft limit(분당 100회)**: 워크플로우가 실패하지는 않으며, 단지 큐에서 대기하다가 시간이 지나면서 처리됩니다. 100개가 넘는 레코드를 트리거할 수 있지만, 실행 속도는 느려집니다.

    **Hard limit(시간당 5,000회)**: 워크스페이스 전체에 적용됩니다. 모든 워크플로우를 합쳐 한 시간에 5,000회 실행을 초과하면, 추가 실행은 즉시 실패합니다.

    **한도 내에 머무르기 위한 팁**:

    * 대규모 배치 작업에는 Single 트리거 대신 Iterator를 함께 사용하는 Bulk 트리거를 사용합니다
    * 관련된 자동화를 더 적은 수의 워크플로우로 통합합니다
    * 부하를 분산하기 위해 예약된 워크플로우를 사용하세요
  </Accordion>

  <Accordion title="실패한 워크플로우 실행을 다시 시도할 수 있나요?">
    **현재는 자동 재시도 기능이 없습니다.**

    워크플로우 실행이 실패한 경우 다음을 수행해야 합니다:

    1. **Settings → Workflows → \[Your Workflow] → Runs**에서 오류를 확인합니다
    2. 문제(데이터, 설정, 외부 서비스)를 수정합니다
    3. 영향을 받은 레코드(들)에 대해 워크플로우를 수동으로 다시 트리거합니다

    **실패를 줄이기 위한 팁**:

    * 액션 실행 전에 데이터를 검증하기 위해 **Filter** 노드를 추가합니다
    * 관련 레코드가 존재하는지 확인하기 위해 **Search Records**를 사용합니다
    * 대량 작업 전에 소수의 레코드로 충분히 테스트합니다

    자동 재시도 기능은 향후 릴리스를 위한 로드맵에 포함되어 있습니다.
  </Accordion>

  <Accordion title="CSV 가져오기 전에 워크플로우를 비활성화해야 하나요?">
    **예, 워크플로우가 레코드 생성 또는 업데이트에 의해 트리거되는 경우에는 비활성화하는 것이 좋습니다.**

    CSV로 데이터를 가져올 때, 생성되거나 업데이트되는 각 레코드가 워크플로우를 트리거할 수 있습니다. 수천 개의 레코드를 포함한 대규모 가져오기는 다음과 같은 상황을 초래할 수 있습니다:

    * 시간당 5,000회 실행 한도에 도달
    * 상당한 워크플로우 크레딧 소모
    * 예상치 못한 이메일 또는 알림 발송
    * 중복 작업 또는 레코드 생성

    **대량 가져오기 전에**:

    1. **Settings → Workflows**로 이동합니다
    2. 가져오려는 오브젝트에 의해 트리거되는 워크플로우를 식별합니다
    3. 해당 워크플로우를 일시적으로 **비활성화**합니다
    4. CSV 가져오기를 실행합니다
    5. 작업이 끝나면 워크플로우를 다시 **활성화**합니다

    **대안**: 가져온 데이터에 워크플로우를 실행해야 한다면, 레이트 리밋 내에 머물 수 있도록 더 작은 배치로 나누어 가져오세요.
  </Accordion>

  <Accordion title="워크플로우 레이아웃을 정리하려면 어떻게 해야 하나요?">
    워크플로우 캔버스에 노드가 흩어져 지저분해 보이는 경우, 자동 정리 기능을 사용할 수 있습니다:

    1. 워크플로우 캔버스의 아무 곳이나 마우스 오른쪽 버튼으로 클릭합니다
    2. **Tidy up workflow**를 클릭합니다

    그러면 모든 노드가 자동으로 재배치되어 깔끔하고 정돈된 레이아웃이 됩니다.
  </Accordion>
</AccordionGroup>