워크플로우

Connect Base 워크플로우 자동화 심화 가이드입니다.

개요

워크플로우를 사용하면 시각적 편집기로 비즈니스 로직을 자동화할 수 있습니다. 코드 없이 복잡한 작업 흐름을 설계하고 실행할 수 있습니다.

트리거 종류

ent 의 workflowexecution.trigger_type enum 은 4가지입니다 (manual, schedule, api, webhook).

수동 (`manual`)

콘솔이나 API 호출(POST /v1/apps/:appID/workflows/:workflowID/execute)로 직접 실행합니다. 이 엔드포인트는 콘솔 운영자의 User JWT 가 필수이며, Public Key 로는 실행할 수 없습니다.

스케줄 (`schedule`)

정해진 시간에 실행:

Cron 표현식 지원
예: 0 9 * * 1 (매주 월요일 오전 9시)

API (`api`)

워크플로우 별도 엔드포인트 호출. 외부 시스템이 인증 헤더와 함께 POST 합니다.

웹훅 (`webhook`)

웹훅 entity 에 target_type=workflow 로 연결하면 데이터 변경 / 파일 업로드 등의 이벤트가 워크플로우를 트리거합니다.

📌 데이터 변경 자동 트리거는 워크플로우 자체가 아니라 위의 웹훅 → 워크플로우 경유로 구성합니다.

노드 타입

ent 의 functiongroupstep.step_type enum 은 정확히 6가지입니다 (function, builtin, condition, parallel, merge, delay). "HTTP 요청" / "반복(loop·foreach)" / "agent" 같은 빌트인 노드는 존재하지 않습니다.

함수 노드 (`function`)

서버리스 함수 호출. 외부 HTTP 호출이 필요하면 함수 노드 안의 사용자 코드(fetch 등)로 구현합니다:

[함수: send-email]
├── 입력: { to, subject, body }
└── 출력: { success, messageId }

빌트인 노드 (`builtin`)

플랫폼이 제공하는 빌트인 동작을 실행합니다.

조건 노드 (`condition`)

조건식 평가 후 true/false 분기. 조건식은 중괄호 없는 점경로로 input.*(초기 입력) / previous.*(직전 스텝 출력) / results.<stepId>.*(특정 스텝 결과) 를 참조합니다:

[조건: previous.amount > 100000]
├── True → [고액 주문 처리]
└── False → [일반 주문 처리]

// 여러 스텝 결과를 조합
previous.success == true && results.<stepId>.status == 'done'

병렬 노드 (`parallel`)

여러 자식 step 을 동시에 실행. 모든 자식이 완료될 때까지 merge 까지 대기합니다.

[parallel]
├── [함수: charge-card]
├── [함수: send-receipt]
└── [함수: notify-admin]

병합 노드 (`merge`)

parallel 에서 분기된 모든 경로를 합쳐서 다음 step 으로 진행시킵니다.

지연 노드 (`delay`)

지정 시간 동안 대기:

[delay: 7일]
└── 이후 → [리마인드 이메일]

📌 "반복(loop·foreach)" / "HTTP" / "agent" 노드는 워크플로우 빌트인이 아닙니다. 엔진이 그래프 사이클을 거부하므로(authoring-time 검증 + 실행 시 maxStepVisits=16 안전망) 반복은 함수 노드 내부 코드로, HTTP 호출은 함수 노드에서 fetch 등을 사용해 구현합니다.

변수 사용

워크플로우에는 {{ ... }} 중괄호 템플릿 문법이 없습니다. 대신 두 가지 메커니즘으로 데이터를 전달합니다.

스텝 입력 매핑 (`input_mapping`)

스텝의 input_mapping 값은 중괄호 없는 접두사 문자열입니다. previous.<field>(직전 스텝 출력) 또는 initial.<field>(워크플로우 초기 입력)를 씁니다.

json

"input_mapping": {
  "order_id": "previous.order_id",
  "user_email": "initial.email"
}

조건식 (`condition`)

조건 스텝의 조건식은 중괄호 없는 점경로로 input.* / previous.* / results.<stepId>.* 를 참조합니다.

previous.amount > 100000
previous.success == true && results.<stepId>.status == 'done'

예제: 신규 회원 온보딩

[트리거: 데이터 생성 (멤버 가입)]
    │
    ▼
[함수: 환영 이메일 발송]
    │
    ▼
[대기: 1일]
    │
    ▼
[조건: previous.profile_completed == true]
    ├── True → [종료]
    └── False → [리마인드 이메일]
             │
             ▼
         [대기: 3일]
             │
             ▼
         [조건: previous.profile_completed == true]
             ├── True → [종료]
             └── False → [최종 리마인드]

모범 사례

1. 에러 처리

각 노드에 에러 핸들링 설정:

재시도 횟수 설정
실패 시 대체 경로 지정
에러 알림 설정

2. 테스트 실행

프로덕션 배포 전 테스트:

테스트 데이터로 실행
각 노드 결과 확인
로그 검토

3. 버전 관리

변경사항 추적:

주요 변경 시 새 버전 생성
이전 버전으로 롤백 가능

실행 타임아웃 / Stuck-running 처리 (2026-05-09)

워크플로우 실행이 비정상 종료되어 status: 'running' 상태로 남는 stuck-running 을 방지하기 위해 2-layer 안전망 이 적용됩니다.

in-process defer 안전망: 실행 컨텍스트가 정상 종료되면 자동으로 timeout / failed 로 마감
ExecutionTimeoutScheduler: 5분 주기로 sweep, 1시간 이상 status: 'running' 인 행은 강제 timeout 처리

따라서 트리거 응답이 빠르게 돌아왔더라도 최종 status 는 콘솔의 실행 로그 또는 GET /v1/apps/:appID/workflow-executions/:id 로 비동기 확인하세요. 임계값(5분 / 1시간) 변경은 backend/cmd/core-server/app/scheduler/execution_timeout_scheduler.go 를 참고합니다.

함수 실행도 동일한 스케줄러가 적용됩니다(서버리스 함수 문서 참고).

웹훅

실시간 통신

워크플로우

개요

트리거 종류

수동 (manual)

스케줄 (schedule)

API (api)

웹훅 (webhook)