#Sự kiện Trước Thao tác

#Giới thiệu

Plugin Sự kiện Trước Thao tác cung cấp một cơ chế chặn các thao tác. Cơ chế này được kích hoạt sau khi yêu cầu tạo mới, cập nhật hoặc xóa một bản ghi được gửi đi, nhưng trước khi yêu cầu đó được xử lý.

Nếu một nút “Kết thúc luồng công việc” được thực thi trong luồng công việc đã kích hoạt, hoặc nếu bất kỳ nút nào khác thực thi thất bại (do lỗi hoặc không hoàn thành), thao tác trên biểu mẫu sẽ bị chặn. Ngược lại, thao tác dự kiến sẽ được thực thi bình thường.

Khi sử dụng cùng với nút “Thông báo phản hồi”, bạn có thể cấu hình thông báo phản hồi trả về cho client, cung cấp các thông tin gợi ý phù hợp. Sự kiện Trước Thao tác có thể được dùng để thực hiện xác thực nghiệp vụ hoặc kiểm tra logic, nhằm chấp thuận hoặc chặn các yêu cầu thao tác tạo mới, cập nhật và xóa do client gửi đi.

#Cấu hình Kích hoạt

#Tạo Kích hoạt

Khi tạo một luồng công việc, hãy chọn loại “Sự kiện Trước Thao tác”:

#Chọn bộ sưu tập

Trong bộ kích hoạt của một luồng công việc chặn, điều đầu tiên cần cấu hình là bộ sưu tập tương ứng với thao tác:

Sau đó, chọn chế độ chặn. Bạn có thể chọn chỉ chặn các nút thao tác đã liên kết với luồng công việc này, hoặc chặn tất cả các thao tác đã chọn cho bộ sưu tập này (không phân biệt đến từ biểu mẫu nào và không cần liên kết với luồng công việc tương ứng):

#Chế độ Chặn

Hiện tại, các loại thao tác được hỗ trợ bao gồm “Tạo mới”, “Cập nhật” và “Xóa”. Bạn có thể chọn nhiều loại thao tác cùng lúc.

#Cấu hình Thao tác

Nếu bạn đã chọn chế độ “Chỉ kích hoạt chặn khi biểu mẫu liên kết với luồng công việc này được gửi” trong cấu hình kích hoạt, bạn cần quay lại giao diện biểu mẫu và liên kết luồng công việc này với nút thao tác tương ứng:

Trong cấu hình liên kết luồng công việc, hãy chọn luồng công việc tương ứng. Thông thường, ngữ cảnh dữ liệu kích hoạt mặc định là “Toàn bộ dữ liệu biểu mẫu” là đủ:

#Điều kiện để chặn

Trong “Sự kiện Trước Thao tác”, có hai điều kiện sẽ khiến thao tác tương ứng bị chặn:

1. Luồng công việc thực thi đến bất kỳ nút “Kết thúc luồng công việc” nào. Tương tự như hướng dẫn trước đó, khi dữ liệu kích hoạt luồng công việc không đáp ứng các điều kiện đã đặt trước trong nút “Điều kiện”, nó sẽ đi vào nhánh “Không” và thực thi nút “Kết thúc luồng công việc”. Tại thời điểm này, luồng công việc sẽ kết thúc và thao tác được yêu cầu sẽ bị chặn.
2. Bất kỳ nút nào trong luồng công việc thực thi thất bại, bao gồm lỗi thực thi nút hoặc các trường hợp ngoại lệ khác. Trong trường hợp này, luồng công việc sẽ kết thúc với trạng thái tương ứng và thao tác được yêu cầu cũng sẽ bị chặn. Ví dụ, nếu luồng công việc gọi dữ liệu bên ngoài thông qua “Yêu cầu HTTP” và yêu cầu đó thất bại, luồng công việc sẽ kết thúc với trạng thái thất bại, đồng thời cũng sẽ chặn yêu cầu thao tác tương ứng.

Sau khi các điều kiện chặn được đáp ứng, thao tác tương ứng sẽ không còn được thực thi. Ví dụ, nếu việc gửi đơn hàng bị chặn, dữ liệu đơn hàng tương ứng sẽ không được tạo.

#Các tham số liên quan của thao tác tương ứng

Trong luồng công việc loại “Sự kiện Trước Thao tác”, đối với các thao tác khác nhau, bộ kích hoạt có các dữ liệu khác nhau có thể được sử dụng làm biến trong luồng công việc:

#Xuất Thông báo phản hồi

Sau khi cấu hình bộ kích hoạt, bạn có thể tùy chỉnh logic phán đoán liên quan trong luồng công việc. Thông thường, bạn sẽ sử dụng chế độ phân nhánh của nút “Điều kiện” để quyết định có “Kết thúc luồng công việc” hay không và trả về “Thông báo phản hồi” đã đặt trước, dựa trên kết quả phán đoán điều kiện nghiệp vụ cụ thể:

Đến đây, cấu hình của luồng công việc tương ứng đã hoàn tất. Bạn có thể thử gửi một dữ liệu không đáp ứng cấu hình điều kiện trong luồng công việc để kích hoạt logic chặn của bộ chặn. Lúc này, bạn sẽ thấy thông báo phản hồi được trả về:

#Trạng thái Thông báo phản hồi

Nếu nút “Kết thúc luồng công việc” được cấu hình để thoát với trạng thái “Thành công”, và khi nút này được thực thi, yêu cầu thao tác vẫn sẽ bị chặn, nhưng thông báo phản hồi trả về sẽ hiển thị với trạng thái “Thành công” (thay vì “Lỗi”):

#Ví dụ

Kết hợp với các hướng dẫn cơ bản ở trên, chúng ta hãy lấy một kịch bản “Gửi đơn hàng” làm ví dụ. Giả sử chúng ta cần kiểm tra tồn kho của tất cả các sản phẩm mà người dùng đã chọn khi họ gửi đơn hàng. Nếu tồn kho của bất kỳ sản phẩm nào không đủ, việc gửi đơn hàng sẽ bị chặn và một thông báo gợi ý tương ứng sẽ được trả về. Luồng công việc sẽ lặp lại để kiểm tra từng sản phẩm cho đến khi tất cả các sản phẩm đều có đủ tồn kho, sau đó sẽ tiếp tục và tạo dữ liệu đơn hàng cho người dùng.

Các bước khác tương tự như trong hướng dẫn. Tuy nhiên, vì một đơn hàng liên quan đến nhiều sản phẩm, ngoài việc thêm mối quan hệ nhiều-nhiều “Đơn hàng” <-- m:1 -- “Chi tiết đơn hàng” -- 1:m --> “Sản phẩm” khi mô hình hóa dữ liệu, bạn còn cần thêm một nút “Lặp” vào luồng công việc “Sự kiện Trước Thao tác” để lặp lại kiểm tra xem tồn kho của từng sản phẩm có đủ hay không:

Đối tượng cho vòng lặp được chọn là mảng “Chi tiết đơn hàng” từ dữ liệu đơn hàng đã gửi:

Nút điều kiện trong luồng công việc lặp được sử dụng để xác định xem tồn kho của đối tượng sản phẩm hiện tại trong vòng lặp có đủ hay không:

Các cấu hình khác tương tự như trong phần sử dụng cơ bản. Khi đơn hàng cuối cùng được gửi, nếu bất kỳ sản phẩm nào có tồn kho không đủ, việc gửi đơn hàng sẽ bị chặn và một thông báo gợi ý tương ứng sẽ được trả về. Khi thử nghiệm, hãy thử gửi một đơn hàng với nhiều sản phẩm, trong đó một sản phẩm có tồn kho không đủ và một sản phẩm khác có đủ tồn kho. Bạn có thể thấy thông báo phản hồi được trả về:

Có thể thấy, thông báo phản hồi không chỉ ra rằng sản phẩm đầu tiên “iPhone 15 pro” thiếu tồn kho, mà chỉ chỉ ra rằng sản phẩm thứ hai “iPhone 14 pro” thiếu tồn kho. Điều này là do trong vòng lặp, sản phẩm đầu tiên có đủ tồn kho nên không bị chặn, trong khi sản phẩm thứ hai thiếu tồn kho nên đã chặn việc gửi đơn hàng.

#Gọi từ bên ngoài

Bản thân Sự kiện Trước Thao tác được đưa vào giai đoạn xử lý yêu cầu, vì vậy nó cũng hỗ trợ kích hoạt thông qua các lệnh gọi HTTP API.

Đối với các luồng công việc được liên kết cục bộ với một nút thao tác, bạn có thể gọi chúng như sau (lấy nút tạo của bộ sưu tập posts làm ví dụ):

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"

Trong đó, tham số URL triggerWorkflows là khóa (key) của luồng công việc; nhiều khóa luồng công việc được phân tách bằng dấu phẩy. Khóa này có thể được lấy bằng cách di chuột qua tên luồng công việc ở phía trên cùng của canvas luồng công việc:

Sau khi lệnh gọi trên được thực hiện, Sự kiện Trước Thao tác cho bộ sưu tập posts tương ứng sẽ được kích hoạt. Sau khi luồng công việc tương ứng được xử lý đồng bộ, dữ liệu sẽ được tạo và trả về bình thường.

Nếu luồng công việc đã cấu hình đi đến “nút kết thúc”, logic sẽ tương tự như thao tác trên giao diện: yêu cầu sẽ bị chặn và không có dữ liệu nào được tạo. Khi trạng thái của nút kết thúc được cấu hình là thất bại, mã trạng thái phản hồi trả về sẽ là 400; nếu thành công, nó sẽ là 200.

Nếu nút “Thông báo phản hồi” cũng được cấu hình trước nút kết thúc, thông báo được tạo cũng sẽ được trả về trong kết quả phản hồi, trong đó cấu trúc khi có lỗi là:

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

Cấu trúc thông báo khi “nút kết thúc” được cấu hình là thành công là:

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

Nếu Sự kiện Trước Thao tác được cấu hình ở chế độ toàn cục, khi gọi HTTP API, bạn không cần sử dụng tham số URL triggerWorkflows để chỉ định luồng công việc tương ứng, mà chỉ cần gọi trực tiếp thao tác của bộ sưu tập tương ứng là có thể kích hoạt.

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"