Khai báo & Khởi tạo Biến Quy trình

1. Biến Quy trình (Process Variables) là gì?

Trước khi đi vào cách thực hiện, hãy cùng định nghĩa rõ khái niệm này.

Process Variables là các cặp key-value chứa dữ liệu được liên kết với một thực thể quy trình (process instance) cụ thể. Hãy tưởng tượng mỗi khi một quy trình được khởi chạy, Camunda sẽ tạo ra một đối tượng Map (hoặc Dictionary trong các ngôn ngữ khác) dành riêng cho thực thể đó. Bạn có thể lưu trữ, truy xuất và sửa đổi dữ liệu trong "bản đồ" này tại bất kỳ điểm nào trong suốt vòng đời của quy trình.

• Phạm vi (Scope): Một biến chỉ tồn tại và có thể truy cập được trong phạm vi của process instance mà nó thuộc về. Các instance khác nhau của cùng một quy trình sẽ có các bộ biến riêng.
• Kiểu dữ liệu: Biến có thể lưu trữ các kiểu dữ liệu nguyên thủy (String, Integer, Boolean, Double,...) hoặc các đối tượng phức tạp hơn như JSON và thậm chí là các đối tượng Java được tuần tự hóa (serialized Java Objects).

Hiểu và sử dụng biến là chìa khóa để điều khiển luồng đi của quy trình, hiển thị dữ liệu cho người dùng, và tích hợp với các hệ thống khác.

2. Cách 1: Khởi tạo biến qua giao diện Camunda Modeler

Đây là cách nhanh nhất và tiện lợi nhất để bạn kiểm thử quy trình của mình với các dữ liệu đầu vào khác nhau. Trong bài học trước, bạn đã học cách deploy và bắt đầu một quy trình từ Modeler. Bây giờ, chúng ta sẽ thêm một bước nhỏ: cung cấp biến ngay lúc bắt đầu.

Khi bạn nhấn nút "Start current diagram" (biểu tượng ▶️), một hộp thoại sẽ hiện ra. Bên cạnh việc chọn cluster, bạn sẽ thấy một mục để thêm biến dưới dạng JSON.

Hoạt động thực hành 1:

1. Tạo và Deploy: Mở Camunda Modeler, tạo một quy trình rất đơn giản: Start Event -> User Task -> End Event. Đặt ID cho quy trình (ví dụ: data_init_test) và tên cho User Task (ví dụ: Review Data). Deploy quy trình này lên Camunda Run engine đang chạy của bạn.
2. Khởi tạo với Biến: Nhấn nút Start current diagram. Trong hộp thoại hiện ra, tại mục "Variables (JSON)", hãy nhập vào một đối tượng JSON như sau:

   {
     "orderId": "A-12345",
     "amount": 99.99,
     "isRush": true
   }
   

3. Nhấn Start.
4. Kiểm tra trong Cockpit: Mở Camunda Cockpit (http://localhost:8080/camunda/app/cockpit/), tìm đến process instance vừa chạy. Nhấp vào nó và chuyển sang tab Variables. Bạn sẽ thấy ba biến orderId, amount, và isRush đã được tạo với các giá trị tương ứng.

Cách làm này, mặc dù chỉ dùng để thử nghiệm, lại cực kỳ hữu ích để nhanh chóng kiểm tra logic của các gateway hoặc service task phụ thuộc vào dữ liệu đầu vào mà không cần viết một dòng code nào.

3. Cách 2: Khởi tạo biến một cách có lập trình (Programmatically)

Trong các ứng dụng thực tế, quy trình thường được khởi tạo bởi một sự kiện khác trong hệ thống (ví dụ: người dùng nhấn nút "Đặt hàng" trên website, một API được gọi). Trong những trường hợp này, bạn cần khởi tạo quy trình và truyền biến vào bằng code.

3.1. Khởi tạo qua REST API

Đây là cách phổ biến trong kiến trúc microservices, nơi các dịch vụ giao tiếp với nhau qua API. Camunda cung cấp một bộ REST API phong phú để tương tác với engine. Để bắt đầu một quy trình và truyền biến, bạn sẽ gửi một request POST đến endpoint của Camunda.

Đối với Camunda 7, endpoint sẽ có dạng:
POST /rest/process-definition/key/{process-definition-key}/start

Và body của request sẽ là một JSON chứa các biến:

{
  "variables": {
    "orderId": {
      "value": "B-67890",
      "type": "String"
    },
    "customerName": {
      "value": "Jane Doe",
      "type": "String"
    }
  }
}

Bạn có thể dùng các công cụ như curl hoặc Postman để thử gọi API này và xem một process instance mới được tạo ra với các biến đã cho.

Lưu ý: Đối với Camunda 8, API có hơi khác một chút. Bạn có thể tham khảo tài liệu về Process instance creation để thấy sự khác biệt. Ví dụ được đề cập trong tài liệu này (resource ID LINK) sử dụng API của Camunda 8.

3.2. Khởi tạo bằng Java Code (trong một Service Task)

Một kịch bản rất phổ biến là quy trình được bắt đầu mà không có dữ liệu đầu vào, và tác vụ đầu tiên ngay sau Start Event là một Service Task có nhiệm vụ tải hoặc khởi tạo dữ liệu cần thiết.

Trong bài học trước, bạn đã học cách liên kết một Service Task với một lớp Java. Bây giờ chúng ta sẽ viết code bên trong lớp Java đó để tạo ra các biến. Lớp này sẽ implement interface JavaDelegate.

Video sau đây sẽ minh họa chính xác cách làm này.

Như bạn thấy trong video, phương thức setVariable rất đơn giản:
delegateExecution.setVariable("weatherOkay", a_boolean_value);

Hoạt động thực hành 2:

1. Sửa đổi Quy trình: Mở lại dự án Spring Boot tích hợp Camunda bạn đã tạo ở Module 2. Sửa đổi file BPMN của bạn. Thêm một Service Task ngay sau Start Event và trước User Task.
2. Cấu hình Service Task:
   • Đặt tên cho nó, ví dụ: "Initialize Variables".
   • Trong Properties Panel, tab "General", mục "Implementation", chọn Java Class.
   • Nhập vào tên đầy đủ của lớp Java bạn sẽ tạo (ví dụ: com.example.camunda.InitVariablesDelegate).
3. Tạo lớp JavaDelegate:
   • Tạo lớp InitVariablesDelegate trong package tương ứng.
   • Cho nó implement JavaDelegate và override phương thức execute.
   • Bên trong execute, hãy tạo một vài biến. Ví dụ:

     import org.camunda.bpm.engine.delegate.DelegateExecution;
     import org.camunda.bpm.engine.delegate.JavaDelegate;
     import org.springframework.stereotype.Component;
     import java.util.Date;
     
     @Component("initVariablesDelegate") // Tên bean để có thể gọi bằng Expression
     public class InitVariablesDelegate implements JavaDelegate {
     
         @Override
         public void execute(DelegateExecution execution) throws Exception {
             long orderId = new Date().getTime(); // Tạo một ID đơn giản
             execution.setVariable("orderId", "C-" + orderId);
             execution.setVariable("initializedAt", new Date());
             System.out.println("Variables initialized: orderId=" + execution.getVariable("orderId"));
         }
     }
     

4. Chạy và Kiểm tra: Chạy ứng dụng Spring Boot của bạn. Engine sẽ tự động deploy quy trình. Dùng Tasklist để bắt đầu một instance mới. Sau đó, vào Cockpit và kiểm tra các biến của instance đó. Bạn sẽ thấy các biến orderId và initializedAt đã được tạo bởi lớp Java của bạn.

4. Kiểm tra lại trong Cockpit

Dù bạn khởi tạo biến bằng cách nào, Cockpit luôn là nơi đáng tin cậy để xác minh kết quả.

Video sau đây cho thấy cách xem các biến đã được tạo ra trong một instance đã chạy xong.

Tổng kết

Hôm nay, bạn đã học được một khái niệm nền tảng trong Camunda: biến quy trình. Chúng là phương tiện để lưu trữ và truyền tải dữ liệu, làm cho quy trình của bạn trở nên linh hoạt và mạnh mẽ.

Các điểm chính cần nhớ:

• Process Variables là các cặp key-value gắn liền với một process instance.
• Bạn có thể khởi tạo chúng ngay lúc bắt đầu quy trình bằng nhiều cách:
  • Qua giao diện của Modeler (để kiểm thử nhanh).
  • Qua REST API (để tích hợp hệ thống).
  • Bằng Java code trong một JavaDelegate (để thực thi logic nghiệp vụ khởi tạo).
• Camunda Cockpit là công cụ không thể thiếu để xem và gỡ lỗi các biến trong một quy trình đang chạy hoặc đã hoàn thành.

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

Bây giờ bạn đã biết cách "bơm" dữ liệu vào một quy trình. Nhưng làm thế nào để dữ liệu đó "chảy" từ tác vụ này sang tác vụ khác? Làm sao để một Service Task có thể đọc được biến do một User Task tạo ra, và ngược lại?

Trong bài học tiếp theo, chúng ta sẽ giải quyết chính xác câu hỏi đó khi tìm hiểu về cách truyền biến giữa các tác vụ (tasks) trong một quy trình.