#작업 후 이벤트

#소개

시스템에서 사용자가 생성하는 모든 데이터 변경은 일반적으로 특정 '작업'을 통해 이루어집니다. 이 작업은 주로 버튼 클릭 형태로 발생하며, 해당 버튼은 폼의 제출 버튼이거나 데이터 블록의 작업 버튼일 수 있습니다. '작업 후 이벤트'는 이러한 버튼 작업에 관련 워크플로우를 연결하여, 사용자 작업이 성공적으로 완료된 후 특정 프로세스가 트리거되도록 합니다.

예를 들어, 데이터를 새로 추가하거나 업데이트할 때, 사용자는 버튼의 "워크플로우 바인딩" 옵션을 설정하여 작업 완료 후 연결된 워크플로우가 트리거되도록 할 수 있습니다.

구현 측면에서, 작업 후 이벤트 처리는 미들웨어 계층(Koa 미들웨어)에서 이루어지므로, NocoBase의 HTTP API 호출을 통해서도 정의된 작업 후 이벤트를 트리거할 수 있습니다.

#설치

내장 플러그인이므로 별도의 설치가 필요하지 않습니다.

#트리거 설정

#워크플로우 생성

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

#실행 모드

작업 후 이벤트의 경우, 생성 시 실행 모드를 "동기" 또는 "비동기"로 선택할 수 있습니다.

사용자 작업 후 즉시 실행되고 결과를 반환해야 하는 프로세스라면 동기 모드를 사용할 수 있으며, 그렇지 않은 경우 기본적으로 비동기 모드가 적용됩니다. 비동기 모드에서는 워크플로우가 트리거된 후 해당 작업이 즉시 완료되며, 워크플로우는 애플리케이션 백그라운드에서 큐 방식으로 순차적으로 실행됩니다.

#컬렉션 설정

워크플로우 캔버스에 진입하여 트리거를 클릭해 설정 팝업을 엽니다. 먼저 바인딩할 컬렉션을 선택해야 합니다.

#트리거 모드 선택

다음으로 트리거 모드를 선택합니다. 트리거 모드에는 로컬 모드와 전역 모드의 두 가지가 있습니다.

각 모드는 다음과 같습니다.

• 로컬 모드는 해당 워크플로우가 바인딩된 작업 버튼에서만 트리거됩니다. 이 워크플로우가 바인딩되지 않은 버튼을 클릭해도 트리거되지 않습니다. 용도가 다른 폼에서 동일한 프로세스를 트리거할지 여부를 고려하여 이 워크플로우를 바인딩할지 결정할 수 있습니다.
• 전역 모드는 컬렉션에 구성된 모든 작업 버튼에서 트리거되며, 어떤 폼에서 발생했는지 구분하지 않고 해당 워크플로우를 바인딩할 필요도 없습니다.

로컬 모드에서 현재 바인딩을 지원하는 작업 버튼은 다음과 같습니다.

• 새로 추가 폼의 "제출" 및 "저장" 버튼
• 업데이트 폼의 "제출" 및 "저장" 버튼
• 데이터 행(테이블, 목록, 칸반 등)의 "데이터 업데이트" 버튼

#작업 유형 선택

전역 모드를 선택한 경우, 작업 유형도 선택해야 합니다. 현재 "데이터 생성 작업"과 "데이터 업데이트 작업"이 지원됩니다. 두 작업 모두 작업 성공 후 워크플로우를 트리거합니다.

#관계 데이터 미리 로드 선택

후속 프로세스에서 트리거된 데이터의 연관 데이터를 사용해야 하는 경우, 미리 로드할 관계 필드를 선택할 수 있습니다.

트리거된 후에는 이러한 연관 데이터를 프로세스에서 직접 사용할 수 있습니다.

#작업 설정

로컬 트리거 모드의 작업의 경우, 워크플로우 설정이 완료되면 사용자 인터페이스로 돌아가 해당 데이터 블록의 폼 작업 버튼에 워크플로우를 바인딩해야 합니다.

"제출" 버튼("데이터 저장" 버튼 포함)에 대해 설정된 워크플로우는 사용자가 해당 폼을 제출하고 데이터 작업이 완료된 후에 트리거됩니다.

버튼 설정 메뉴에서 "워크플로우 바인딩"을 선택하면 바인딩 설정 팝업이 열립니다. 이 팝업에서는 트리거할 워크플로우를 여러 개 설정할 수 있으며, 아무것도 설정하지 않으면 트리거가 필요 없음을 의미합니다. 각 워크플로우에 대해 먼저 트리거할 데이터가 전체 폼 데이터인지, 아니면 폼 내의 특정 관계 필드 데이터인지를 지정해야 합니다. 그 다음, 선택한 데이터 모델에 해당하는 컬렉션에 따라 해당 컬렉션 모델과 일치하도록 설정된 폼 워크플로우를 선택합니다.

#예시

여기서는 새로 추가 작업을 통해 시연해 보겠습니다.

"경비 청구" 시나리오를 가정해 봅시다. 직원이 경비 청구를 제출하면, 금액에 대한 자동 심사와 한도를 초과하는 금액에 대한 수동 심사를 수행해야 합니다. 심사에 성공한 신청만 승인되며, 이후 재무 부서에서 처리됩니다.

먼저, 다음과 같은 필드를 가진 "경비 청구" 컬렉션을 생성할 수 있습니다.

• 프로젝트 이름: 한 줄 텍스트
• 신청자: 다대일 (사용자)
• 금액: 숫자
• 상태: 단일 선택 ("승인됨", "처리 완료")

그 다음 "작업 후 이벤트" 유형의 워크플로우를 생성하고, 트리거에서 컬렉션 모델을 "경비 청구" 컬렉션으로 설정합니다.

워크플로우를 활성화 상태로 설정한 후, 프로세스의 구체적인 처리 노드는 나중에 다시 돌아와서 설정하겠습니다.

다음으로 인터페이스에 "경비 청구" 컬렉션의 테이블 블록을 생성하고, 툴바에 "추가" 버튼을 추가하여 해당 폼 필드를 설정합니다. 그리고 폼의 "제출" 작업 버튼 설정 항목에서 "워크플로우 바인딩" 설정 대화 상자를 열고, 전체 폼 데이터를 컨텍스트로 선택한 다음, 이전에 생성한 워크플로우를 선택합니다.

폼 설정이 완료되면 워크플로우의 로직 구성으로 돌아갑니다. 예를 들어, 금액이 500원보다 클 경우 관리자의 수동 심사를 요청하고, 그렇지 않으면 즉시 승인하며, 심사가 통과된 후에만 경비 청구 기록을 생성하고 재무 부서에서 추가 처리하도록 합니다(생략).

이후 재무 처리 부분을 제외하면, 경비 청구 프로세스 설정이 완료됩니다. 직원이 경비 청구서를 작성하여 제출하면 해당 워크플로우가 트리거됩니다. 경비 금액이 500원 미만이면 자동으로 기록이 생성되고 재무 부서의 추가 처리를 기다리며, 그렇지 않으면 관리자의 심사를 거쳐 승인된 후 마찬가지로 기록이 생성되고 재무 부서로 전달됩니다.

이 예시의 프로세스는 일반 "제출" 버튼에도 설정할 수 있습니다. 특정 비즈니스 시나리오에 따라 먼저 기록을 생성한 후 후속 프로세스를 실행할지 여부를 결정할 수 있습니다.

#외부 호출

작업 후 이벤트는 사용자 인터페이스 작업에만 국한되지 않고, 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 컬렉션의 작업 후 이벤트가 트리거됩니다.

이 작업에서 일대일 관계 데이터(다대다 관계는 현재 미지원)의 이벤트를 트리거해야 하는 경우, 매개변수에서 !를 사용하여 관계 필드의 트리거 데이터를 지정할 수 있습니다.

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

위 호출이 성공하면 해당 categories 컬렉션의 작업 후 이벤트가 트리거됩니다.

#자주 묻는 질문

#작업 전 이벤트와의 차이점

• 작업 전 이벤트: 특정 작업(예: 추가, 업데이트 등)이 실행되기 전에 트리거됩니다. 작업 실행 전에 프로세스에서 요청 데이터를 검증하거나 처리할 수 있으며, 만약 프로세스가 중단되면(요청이 가로채지면) 해당 작업(추가, 업데이트 등)은 실행되지 않습니다.
• 작업 후 이벤트: 사용자 작업이 성공적으로 완료된 후에 트리거됩니다. 이 시점에는 데이터가 성공적으로 제출되어 데이터베이스에 저장되었으며, 성공적인 결과를 바탕으로 관련 프로세스를 계속 처리할 수 있습니다.

아래 그림과 같습니다.

#컬렉션 이벤트와의 차이점

작업 후 이벤트와 컬렉션 이벤트는 데이터 변경 후 트리거되는 프로세스라는 점에서 유사하지만, 구현 수준이 다릅니다. 작업 후 이벤트는 API 수준에서 작동하는 반면, 컬렉션 이벤트는 컬렉션의 데이터 변경에 초점을 맞춥니다.

컬렉션 이벤트는 시스템의 더 깊은 계층에 가깝습니다. 어떤 경우에는 하나의 이벤트로 인한 데이터 변경이 다른 이벤트를 트리거하여 연쇄 반응을 일으킬 수 있습니다. 특히 현재 컬렉션 작업 중에 일부 연관 컬렉션의 데이터도 변경된 경우, 연관 컬렉션 관련 이벤트도 트리거될 수 있습니다.

컬렉션 이벤트 트리거에는 사용자 관련 정보가 포함되지 않습니다. 반면 작업 후 이벤트는 사용자 측에 더 가깝고 사용자 작업의 결과입니다. 워크플로우의 컨텍스트에는 사용자 관련 정보도 포함되므로, 사용자 작업과 관련된 프로세스를 처리하는 데 적합합니다. NocoBase의 향후 설계에서는 트리거에 사용할 수 있는 더 많은 작업 후 이벤트가 확장될 수 있으므로, 사용자 작업으로 인한 데이터 변경 프로세스를 처리할 때는 작업 후 이벤트를 사용하는 것을 더 권장합니다.

또 다른 차이점은 작업 후 이벤트는 특정 폼 버튼에 로컬로 바인딩될 수 있다는 점입니다. 여러 폼이 있는 경우, 일부 폼 제출은 이 이벤트를 트리거하지만 다른 폼은 트리거하지 않을 수 있습니다. 반면 컬렉션 이벤트는 전체 컬렉션의 데이터 변경에 대한 것이므로 로컬로 바인딩할 수 없습니다.