Truy vấn Task theo User và Group bằng Camunda REST API

1. Mục tiêu: Từ Dữ liệu Task đến Giao diện Người dùng

Hãy tưởng tượng một giao diện quản lý công việc (task list) điển hình. Người dùng mong muốn có thể lọc và xem các task theo nhiều tiêu chí khác nhau, chẳng hạn như:

• Các task được gán trực tiếp cho tôi.
• Các task mà nhóm của tôi có thể làm.
• Các task chưa có ai nhận.

Để cung cấp dữ liệu cho một giao diện như vậy, ứng dụng của bạn cần giao tiếp với Camunda engine. Với nền tảng là một developer, bạn sẽ thấy quen thuộc với phương thức giao tiếp phổ biến nhất trong các hệ thống hiện đại: REST API.

2. Tổng quan về Camunda REST API

Camunda Platform 7 cung cấp một bộ REST API toàn diện, cho phép các ứng dụng bên ngoài tương tác với engine một cách đầy đủ. Bạn có thể làm mọi thứ, từ việc deploy một quy trình, bắt đầu một instance, cho đến truy vấn dữ liệu lịch sử và tất nhiên, quản lý các user task.

Endpoint gốc (base URL) cho REST API của một Camunda engine chạy local với cấu hình mặc định là:
http://localhost:8080/engine-rest

Mọi lời gọi API sẽ được xây dựng dựa trên URL này. Ví dụ, để tương tác với các task, bạn sẽ làm việc với các endpoint bắt đầu bằng /task.

Với kinh nghiệm lập trình của bạn, việc đọc và hiểu tài liệu API sẽ rất trực quan. Bạn có thể tham khảo toàn bộ tài liệu về Camunda 7 REST API tại trang chủ của Camunda. Đây là nguồn thông tin vô giá trong suốt quá trình làm việc với Camunda.

3. Truy vấn Task cơ bản với GET /task

Endpoint chính để lấy danh sách các task là GET /task. Bản thân lời gọi này sẽ trả về tất cả các task đang hoạt động trong engine, điều này thường không hữu ích. Sức mạnh thực sự của nó nằm ở việc sử dụng các tham số truy vấn (query parameters) để lọc kết quả.

Video sau đây từ Camunda sẽ minh họa cách sử dụng REST API (thông qua công cụ Postman) để deploy, bắt đầu và truy vấn một task trong quy trình.

Như bạn đã thấy trong video, bằng cách thêm ?processDefinitionKey=... vào URL, chúng ta có thể thu hẹp kết quả. Bây giờ, hãy áp dụng nguyên tắc tương tự cho mục tiêu của chúng ta: lọc theo người dùng và nhóm.

a. Lấy các task được gán trực tiếp cho một người dùng (assignee)

Để lấy danh sách các task được gán trực tiếp cho một người dùng cụ thể (ví dụ: người dùng có ID là demo), bạn sử dụng tham số assignee.

Lời gọi API (GET):

http://localhost:8080/engine-rest/task?assignee=demo

Engine sẽ trả về một mảng JSON chứa các đối tượng task. Mỗi đối tượng sẽ có thuộc tính assignee là "demo".

b. Lấy các task mà một người dùng có thể nhận (candidateUser)

Nếu một task có danh sách candidateUsers (ví dụ: john, mary), bạn có thể tìm các task mà john có thể nhận bằng tham số candidateUser.

Lời gọi API (GET):

http://localhost:8080/engine-rest/task?candidateUser=john

Kết quả trả về sẽ là các task chưa được gán (assignee là null) nhưng john nằm trong danh sách ứng viên.

c. Lấy các task mà một nhóm có thể nhận (candidateGroup)

Đây là trường hợp sử dụng phổ biến nhất cho các hàng đợi công việc của phòng ban. Để lấy tất cả các task mà bất kỳ thành viên nào của nhóm management có thể nhận, bạn sử dụng tham số candidateGroup.

Lời gọi API (GET):

http://localhost:8080/engine-rest/task?candidateGroup=management

Tương tự như candidateUser, các task này sẽ chưa được gán (assignee là null) và sẵn sàng để một thành viên trong nhóm management nhận (claim) và xử lý.

4. Xây dựng danh sách "Công việc của tôi" hoàn chỉnh

Trong một ứng dụng thực tế, một người dùng (ví dụ: john) thường muốn xem một danh sách hợp nhất bao gồm:

1. Các task được gán trực tiếp cho john.
2. Các task mà john có thể nhận vì anh ấy thuộc các nhóm (ví dụ: management, accounting).

Sử dụng GET /task sẽ yêu cầu nhiều lời gọi API riêng biệt, điều này không hiệu quả. May mắn thay, Camunda cung cấp một phương thức mạnh mẽ hơn là POST /task, cho phép bạn gửi một body JSON chứa các tiêu chí truy vấn phức tạp.

Với POST /task, bạn có thể định nghĩa các điều kiện OR. Đây là cách tiếp cận được khuyến khích cho các developer để xây dựng các truy vấn phức tạp.

Lời gọi API (POST):

http://localhost:8080/engine-rest/task

Body của Request (JSON):

{
  "orQueries": [
    {
      "assignee": "john"
    },
    {
      "candidateGroups": ["management", "accounting"]
    }
  ],
  "unassigned": true
}

Hãy phân tích body này:

• "orQueries": Đây là một mảng các điều kiện, engine sẽ tìm các task khớp với bất kỳ điều kiện nào bên trong.
  • "assignee": "john": Tìm các task được gán cho john.
  • "candidateGroups": ["management", "accounting"]: Tìm các task có candidateGroup là management HOẶC accounting.
• "unassigned": true: Điều này đảm bảo rằng khi xét đến candidateGroups, chúng ta chỉ lấy những task chưa có ai nhận.

Truy vấn POST này hiệu quả hơn nhiều và là kỹ thuật tiêu chuẩn để xây dựng các danh sách công việc cá nhân hóa trong các ứng dụng tùy chỉnh.

Để có thêm một góc nhìn khác về việc sử dụng REST API, bạn có thể tham khảo bài viết sau. Nó sử dụng SwaggerUI, một công cụ tích hợp sẵn trong Camunda Run, để thực hiện các lời gọi API, bao gồm cả việc truy vấn task.

Tổng kết

Qua bài học này, bạn đã nắm được một kỹ năng quan trọng để bắc cầu giữa quy trình và người dùng cuối:

• Camunda REST API là cổng giao tiếp chính để các ứng dụng bên ngoài tương tác với engine.
• Endpoint GET /task cùng với các tham số assignee, candidateUser, và candidateGroup cho phép bạn thực hiện các truy vấn lọc task mạnh mẽ.
• Để xây dựng các truy vấn phức tạp (như danh sách "Công việc của tôi"), phương thức POST /task với body JSON linh hoạt là lựa chọn tối ưu cho developer.

Bạn đã có trong tay công cụ để lấy dữ liệu task. Giờ là lúc biến dữ liệu đó thành một thứ hữu ích cho người dùng.

Xem trước bài học tiếp theo

Trong bài học kế tiếp, "Xây dựng một giao diện web đơn giản để hiển thị danh sách task cho người dùng", chúng ta sẽ áp dụng những gì vừa học. Bạn sẽ bắt đầu viết code để tạo một trang web đơn giản, gọi đến các endpoint API này, và hiển thị danh sách các task mà một người dùng có thể thấy và tương tác. Đây sẽ là bước thực hành "hands-on" đầu tiên trong việc xây dựng một workflow engine hoàn chỉnh cho sản phẩm của bạn.