#Sự kiện thao tác tùy chỉnh

#Giới thiệu

NocoBase tích hợp sẵn các thao tác dữ liệu phổ biến (thêm, xóa, sửa, truy vấn, v.v.). Khi các thao tác này không thể đáp ứng các nhu cầu nghiệp vụ phức tạp, có thể sử dụng sự kiện thao tác tùy chỉnh trong luồng công việc và liên kết sự kiện này với nút "Kích hoạt luồng công việc" trên khối trang. Sau khi người dùng nhấp vào, một luồng công việc thao tác tùy chỉnh sẽ được kích hoạt.

#Tạo luồng công việc

Khi tạo luồng công việc, chọn "Sự kiện thao tác tùy chỉnh":

#Cấu hình bộ kích hoạt

#Loại ngữ cảnh

v.1.6.0+

Sự khác biệt về loại ngữ cảnh sẽ quyết định luồng công việc này có thể được liên kết với các nút của khối nào:

• Không có ngữ cảnh: Tức là sự kiện toàn cục, có thể liên kết với các nút thao tác trên bảng thao tác, khối dữ liệu;
• Dữ liệu một hàng: Có thể liên kết với các nút thao tác trên các khối dữ liệu như hàng dữ liệu bảng, biểu mẫu, chi tiết, v.v.;
• Dữ liệu nhiều hàng: Có thể liên kết với các nút thao tác hàng loạt của bảng.

#Bộ sưu tập

Khi loại ngữ cảnh là dữ liệu một hàng hoặc dữ liệu nhiều hàng, cần chọn bộ sưu tập để liên kết mô hình dữ liệu:

#Dữ liệu liên kết sẽ được sử dụng

Nếu cần sử dụng dữ liệu liên kết của hàng dữ liệu kích hoạt trong luồng công việc, có thể chọn các trường liên kết sâu tại đây:

Các trường này sẽ tự động được tải trước vào ngữ cảnh của luồng công việc sau khi sự kiện được kích hoạt, để sử dụng trong luồng công việc.

#Cấu hình thao tác

Tùy thuộc vào loại ngữ cảnh được cấu hình trong luồng công việc, cấu hình nút thao tác trong các khối khác nhau cũng sẽ có sự khác biệt.

#Không có ngữ cảnh

v1.6.0+

Trong bảng thao tác và các khối dữ liệu khác, đều có thể thêm nút "Kích hoạt luồng công việc":

Sau khi thêm nút, liên kết với luồng công việc không có ngữ cảnh đã tạo trước đó, lấy nút trong bảng thao tác làm ví dụ:

#Bản ghi một hàng

Trong bất kỳ khối dữ liệu nào, đều có thể thêm nút "Kích hoạt luồng công việc" vào thanh thao tác cho dữ liệu một hàng, chẳng hạn như biểu mẫu, hàng dữ liệu bảng, chi tiết, v.v.:

Sau khi thêm nút, liên kết với luồng công việc đã tạo trước đó:

Sau đó nhấp vào nút này để kích hoạt sự kiện thao tác tùy chỉnh đó:

#Bản ghi nhiều hàng

v1.6.0+

Trong thanh thao tác của khối bảng, khi thêm nút "Kích hoạt luồng công việc" sẽ có một tùy chọn bổ sung, chọn loại ngữ cảnh là "Không có ngữ cảnh" hoặc "Dữ liệu nhiều hàng":

Khi chọn "Không có ngữ cảnh", tức là sự kiện toàn cục, chỉ có thể liên kết với luồng công việc loại không có ngữ cảnh.

Khi chọn "Dữ liệu nhiều hàng", có thể liên kết với luồng công việc loại dữ liệu nhiều hàng, có thể dùng cho các thao tác hàng loạt sau khi chọn nhiều dữ liệu (hiện tại chỉ bảng hỗ trợ). Lúc này phạm vi luồng công việc có thể chọn chỉ là các luồng công việc được cấu hình khớp với bộ sưu tập của khối dữ liệu hiện tại:

Khi nhấp vào nút kích hoạt, phải chọn một số hàng dữ liệu trong bảng, nếu không luồng công việc sẽ không được kích hoạt:

#Ví dụ

Ví dụ, chúng ta có một bộ sưu tập "Mẫu", đối với các mẫu "Đã thu thập" (trạng thái), cần cung cấp một thao tác "Gửi kiểm tra". Gửi kiểm tra sẽ kiểm tra thông tin cơ bản của mẫu trước, sau đó tạo một dữ liệu "Hồ sơ kiểm tra", rồi sửa trạng thái mẫu thành "Đã gửi kiểm tra". Chuỗi quy trình này không thể hoàn thành thông qua các lần nhấp nút "thêm, xóa, sửa, truy vấn" đơn giản, lúc này có thể sử dụng sự kiện thao tác tùy chỉnh để thực hiện.

Trước tiên, tạo một bộ sưu tập "Mẫu" và một bộ sưu tập "Hồ sơ kiểm tra", nhập dữ liệu thử nghiệm cơ bản vào bộ sưu tập Mẫu:

Sau đó tạo một luồng công việc "Sự kiện thao tác tùy chỉnh". Nếu cần phản hồi kịp thời từ quy trình thao tác, có thể chọn chế độ đồng bộ (trong chế độ đồng bộ không thể sử dụng các nút loại bất đồng bộ như xử lý thủ công):

Trong cấu hình bộ kích hoạt, bộ sưu tập chọn "Mẫu":

Dựa trên yêu cầu nghiệp vụ, sắp xếp logic trong quy trình, ví dụ: chỉ cho phép gửi kiểm tra khi tham số chỉ số lớn hơn 90, nếu không sẽ hiển thị thông báo về vấn đề liên quan:

Sau khi cấu hình và kích hoạt luồng công việc, quay lại giao diện bảng, thêm nút "Kích hoạt luồng công việc" vào cột thao tác của bảng:

Sau đó, trong menu cấu hình của nút, chọn liên kết luồng công việc và mở cửa sổ cấu hình bật lên:

Thêm luồng công việc đã được kích hoạt trước đó:

Sau khi gửi, thay đổi văn bản nút thành tên thao tác, ví dụ như "Gửi kiểm tra". Quá trình cấu hình đã hoàn tất.

Khi sử dụng, chọn bất kỳ dữ liệu mẫu nào trong bảng và nhấp vào nút "Gửi kiểm tra" để kích hoạt sự kiện thao tác tùy chỉnh. Đúng như logic đã sắp xếp trước đó, nếu tham số chỉ số của mẫu nhỏ hơn 90, sau khi nhấp sẽ hiển thị thông báo như sau:

Nếu tham số chỉ số lớn hơn 90, quy trình sẽ thực hiện bình thường, tạo dữ liệu "Hồ sơ kiểm tra" và thay đổi trạng thái của mẫu thành "Đã gửi kiểm tra":

Đến đây, một sự kiện thao tác tùy chỉnh đơn giản đã hoàn tất. Tương tự, đối với các nghiệp vụ có thao tác phức tạp như xử lý đơn hàng, gửi báo cáo, v.v., đều có thể được thực hiện thông qua sự kiện thao tác tùy chỉnh.

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

Việc kích hoạt sự kiện thao tác tùy chỉnh không chỉ giới hạn ở các thao tác trên giao diện người dùng, mà còn có thể được kích hoạt thông qua gọi HTTP API. Đặc biệt, sự kiện thao tác tùy chỉnh cung cấp một loại thao tác mới để kích hoạt luồng công việc cho tất cả các thao tác bộ sưu tập: trigger, có thể sử dụng API thao tác tiêu chuẩn của NocoBase để tiến hành gọi.

#Không có ngữ cảnh

Luồng công việc không có ngữ cảnh cần thực hiện thao tác kích hoạt đối với tài nguyên workflows:

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' \
  "http://localhost:3000/api/workflows:trigger?triggerWorkflows=workflowKey"

#Bản ghi một hàng

Tương tự như luồng công việc được kích hoạt bởi nút trong ví dụ, có thể được gọi như sau:

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' \
  "http://localhost:3000/api/samples:trigger/<:id>?triggerWorkflows=workflowKey"

Vì thao tác này dành cho một bản ghi đơn lẻ, nên khi gọi trên dữ liệu đã có, bạn cần chỉ định ID của hàng dữ liệu, thay thế phần <:id> trong URL.

Nếu gọi cho một biểu mẫu (như thêm mới hoặc cập nhật), đối với biểu mẫu thêm dữ liệu mới có thể không cần truyền ID, nhưng cần truyền dữ liệu đã gửi, làm dữ liệu ngữ cảnh thực thi:

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "title": "Sample 1",
    "id": 91
  }'
  "http://localhost:3000/api/samples:trigger?triggerWorkflows=workflowKey"

Đối với biểu mẫu cập nhật, bạn cần truyền cả ID của hàng dữ liệu và dữ liệu cập nhật:

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' -d \
  '{
    "title": "Sample 1",
    "id": 91
  }'
  "http://localhost:3000/api/samples:trigger/<:id>?triggerWorkflows=workflowKey"

Nếu cả ID và dữ liệu được truyền cùng lúc, hàng dữ liệu tương ứng với ID sẽ được tải trước, sau đó các thuộc tính từ đối tượng dữ liệu được truyền sẽ được sử dụng để ghi đè lên hàng dữ liệu gốc nhằm có được ngữ cảnh dữ liệu kích hoạt cuối cùng.

Ngoài ra, tham số URL triggerWorkflows là khóa (key) của luồng công việc; nhiều 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 ở đầu canvas luồng công việc:

Sau khi gọi thành công, sự kiện thao tác tùy chỉnh cho bộ sưu tập samples tương ứng sẽ được kích hoạt.

#Bản ghi nhiều hàng

Tương tự như cách gọi bản ghi một hàng, nhưng dữ liệu truyền vào chỉ cần nhiều tham số khóa chính (filterByTk[]), và không cần truyền phần data:

curl -X POST -H 'Authorization: Bearer <your token>' -H 'X-Role: <roleName>' \
  "http://localhost:3000/api/samples:trigger?filterByTk[]=1&filterByTk[]=2&triggerWorkflows=workflowKey"

Lệnh gọi này sẽ kích hoạt sự kiện thao tác tùy chỉnh ở chế độ bản ghi nhiều hàng, và sử dụng dữ liệu có id là 1 và 2 làm dữ liệu trong ngữ cảnh bộ kích hoạt.