#작업 전 이벤트

#소개

작업 전 이벤트 플러그인은 생성, 업데이트, 삭제 작업 요청이 제출된 후 처리되기 전에 트리거될 수 있는 작업 가로채기(interception) 메커니즘을 제공합니다.

트리거된 워크플로우에서 "워크플로우 종료" 노드가 실행되거나, 다른 노드가 오류 등으로 인해 실행에 실패하면 해당 폼 작업은 가로채집니다. 그렇지 않으면 예정된 작업은 정상적으로 실행됩니다.

“응답 메시지” 노드와 함께 사용하면 클라이언트에 적절한 안내 메시지를 제공하기 위해 해당 워크플로우에 반환될 응답 메시지를 구성할 수 있습니다. 작업 전 이벤트는 클라이언트가 제출한 생성, 업데이트, 삭제 등의 작업 요청을 승인하거나 가로채기 위한 비즈니스 유효성 검사 또는 논리적 검사에 활용될 수 있습니다.

#트리거 설정

#트리거 생성

워크플로우를 생성할 때, 유형을 "작업 전 이벤트"로 선택합니다:

#컬렉션 선택

가로채기 워크플로우의 트리거에서 가장 먼저 설정해야 할 것은 작업에 해당하는 컬렉션입니다:

다음으로 가로채기 모드를 선택합니다. 이 워크플로우에 바인딩된 작업 버튼만 가로챌 수도 있고, 해당 컬렉션의 모든 선택된 작업을 가로챌 수도 있습니다(어떤 폼에서 왔는지 구분하지 않으며, 해당 워크플로우를 바인딩할 필요도 없습니다):

#가로채기 모드

현재 지원되는 작업 유형은 "생성", "업데이트", "삭제"이며, 여러 작업 유형을 동시에 선택할 수 있습니다.

#작업 설정

트리거 설정에서 "이 워크플로우에 바인딩된 폼이 제출될 때만 가로채기 트리거" 모드를 선택했다면, 폼 인터페이스로 돌아가서 해당 작업 버튼에 이 워크플로우를 바인딩해야 합니다:

워크플로우 바인딩 설정에서 해당 워크플로우를 선택합니다. 일반적으로 트리거 데이터의 컨텍스트 선택은 기본값인 "전체 폼 데이터"로 충분합니다:

#가로채기 조건

“작업 전 이벤트”에서는 해당 작업이 가로채지는 두 가지 조건이 있습니다:

1. 워크플로우가 임의의 "워크플로우 종료" 노드에 도달했을 때. 이전 사용 설명과 유사하게, 워크플로우를 트리거한 데이터가 "조건 판단" 노드에 미리 설정된 조건을 충족하지 못하면 "아니요" 분기로 진입하여 "워크플로우 종료" 노드를 실행합니다. 이때 워크플로우가 종료되고 요청된 작업은 가로채집니다.
2. 워크플로우 내의 임의의 노드가 실행에 실패했을 때. 노드 실행 오류 또는 기타 예외 상황을 포함하여, 이때 워크플로우는 해당 상태로 종료되며 요청된 작업도 가로채집니다. 예를 들어, 워크플로우에서 "HTTP 요청"을 통해 외부 데이터를 호출할 때 요청이 실패하면, 해당 워크플로우는 실패 상태로 종료됨과 동시에 해당 작업 요청도 가로챕니다.

가로채기 조건이 충족되면 해당 작업은 더 이상 실행되지 않습니다. 예를 들어, 주문 제출이 가로채지면 해당 주문 데이터는 생성되지 않습니다.

#해당 작업의 관련 매개변수

“작업 전 이벤트” 유형의 워크플로우에서는 다양한 작업에 대해 트리거의 다양한 데이터를 변수로 사용하여 워크플로우에서 활용할 수 있습니다:

#응답 메시지 출력

트리거를 설정한 후, 워크플로우에서 관련 판단 로직을 사용자 정의할 수 있습니다. 일반적으로 "조건 판단" 노드의 분기 모드를 사용하여 특정 비즈니스 조건 판단 결과에 따라 "워크플로우 종료" 여부를 선택하고 미리 설정된 "응답 메시지"를 반환합니다:

이로써 해당 워크플로우 설정이 완료되었습니다. 이제 워크플로우의 조건 판단 설정에 부합하지 않는 데이터를 제출하여 가로채기 로직을 트리거해 볼 수 있습니다. 이때 반환되는 응답 메시지를 확인할 수 있습니다:

#응답 메시지 상태

만약 "워크플로우 종료" 노드에서 "성공" 상태로 종료하도록 설정되어 있고, 해당 "워크플로우 종료" 노드가 실행될 때 해당 작업 요청은 여전히 가로채지지만, 반환되는 응답 메시지는 "성공" 상태로 표시됩니다(오류 대신):

#예시

위의 기본 사용 설명과 결합하여 "주문 제출" 시나리오를 예로 들어보겠습니다. 사용자가 주문을 제출할 때, 선택한 모든 제품의 재고를 확인해야 한다고 가정해 봅시다. 만약 어떤 제품이든 재고가 부족하면 해당 주문 제출을 가로채고 관련 안내 메시지를 반환합니다. 모든 제품의 재고가 충분해질 때까지 각 제품을 순환하며 확인하고, 재고가 충분하면 통과되어 사용자에게 주문 데이터가 생성됩니다.

다른 단계는 설명과 동일합니다. 하지만 하나의 주문이 여러 상품을 대상으로 하기 때문에, 데이터 모델링 시 "주문" <-- m:1 -- "주문 상세" -- 1:m --> "제품"의 다대다 관계를 추가하는 것 외에도, "작업 전 이벤트" 워크플로우에 각 제품의 재고가 충분한지 순환하며 확인하는 데 사용되는 "반복" 노드를 추가해야 합니다:

반복 대상은 제출된 주문 데이터의 "주문 상세" 배열로 선택됩니다:

반복 워크플로우 내의 조건 판단 노드는 현재 반복 중인 제품 객체의 재고가 충분한지 판단하는 데 사용됩니다:

다른 설정은 기본 사용법과 동일합니다. 최종적으로 주문을 제출할 때, 어떤 제품이든 재고가 부족하면 주문 제출이 가로채지고 해당 안내 메시지가 반환됩니다. 테스트 시 하나의 주문에 여러 제품을 제출해 보십시오. 그중 하나는 재고가 부족하고 다른 하나는 재고가 충분한 경우, 반환되는 응답 메시지를 확인할 수 있습니다:

보시다시피, 응답 메시지에서는 첫 번째 제품 "iPhone 15 pro"의 재고 부족은 표시되지 않고, 두 번째 제품 "iPhone 14 pro"의 재고 부족만 표시됩니다. 이는 반복 과정에서 첫 번째 제품은 재고가 충분하여 가로채지 않았고, 두 번째 제품은 재고가 부족하여 주문 제출을 가로챘기 때문입니다.

#외부 호출

작업 전 이벤트 자체는 요청 처리 단계에 주입되므로 HTTP API 호출을 통해 트리거되는 것도 지원합니다.

작업 버튼에 로컬로 바인딩된 워크플로우의 경우 다음과 같이 호출할 수 있습니다(posts 컬렉션 생성 버튼을 예로 들어):

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "title": "Hello, world!",
    "content": "This is a test post."
  }'
  "http://localhost:3000/api/posts:create?triggerWorkflows=workflowKey"

여기서 URL 매개변수 triggerWorkflows는 워크플로우의 키이며, 여러 워크플로우 키는 쉼표로 구분됩니다. 이 키는 워크플로우 캔버스 상단의 워크플로우 이름에 마우스를 올리면 얻을 수 있습니다:

위 호출이 이루어지면 해당 posts 컬렉션의 작업 전 이벤트가 트리거됩니다. 해당 워크플로우가 동기적으로 처리된 후, 데이터가 정상적으로 생성되고 반환됩니다.

설정된 워크플로우가 "종료 노드"에 도달하면 인터페이스 작업과 동일한 로직으로 요청이 가로채지고 데이터는 생성되지 않습니다. 종료 노드의 상태가 실패로 설정된 경우 반환되는 응답 상태 코드는 400이며, 성공 시에는 200입니다.

만약 종료 노드 전에 "응답 메시지" 노드도 설정된 경우, 생성된 메시지는 응답 결과에 반환됩니다. 오류 시 구조는 다음과 같습니다:

{
  "errors": [
    {
      "message": "message from 'Response message' node"
    }
  ]
}

“종료 노드”가 성공으로 설정되었을 때의 메시지 구조는 다음과 같습니다:

{
  "messages": [
    {
      "message": "message from 'Response message' node"
    }
  ]
}

만약 작업 전 이벤트가 전역 모드로 설정된 경우, HTTP API 호출 시 URL 매개변수 triggerWorkflows를 사용하여 해당 워크플로우를 지정할 필요가 없습니다. 해당 컬렉션 작업을 직접 호출하면 트리거됩니다.

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "title": "Hello, world!",
    "content": "This is a test post."
  }'
  "http://localhost:3000/api/posts:create"