Ánh xạ dữ liệu cho Service Task

1. Nguyên tắc cơ bản của Input/Output Mapping

Về cơ bản, Input/Output Mapping hoạt động như một lớp "adapter" giữa phạm vi biến toàn cục của quy trình (process scope) và phạm vi biến cục bộ của một tác vụ (task-local scope).

• Input Mapping (Ánh xạ đầu vào): Trước khi một tác vụ (ví dụ: Service Task) được thực thi, cơ chế ánh xạ sẽ lấy giá trị từ các biến quy trình, xử lý chúng nếu cần, và tạo ra các biến cục bộ chỉ tồn tại trong phạm vi của tác vụ đó. Logic bên trong tác vụ (ví dụ: code Java của bạn) sẽ chỉ làm việc với các biến cục bộ này.
• Output Mapping (Ánh xạ đầu ra): Sau khi tác vụ hoàn thành, cơ chế ánh xạ sẽ lấy các giá trị từ các biến cục bộ (có thể là kết quả tính toán), xử lý chúng nếu cần, và cập nhật hoặc tạo mới các biến trong phạm vi toàn cục của quy trình.

Cách làm này mang lại lợi ích rõ ràng, đặc biệt với kinh nghiệm lập trình của bạn:

• Tính đóng gói: Logic nghiệp vụ của bạn bên trong một JavaDelegate giờ đây chỉ phụ thuộc vào các "tham số" được truyền vào, chứ không phải toàn bộ trạng thái của quy trình.
• Tính linh hoạt và tái sử dụng: Bạn có thể dễ dàng tái sử dụng một Service Task trong nhiều quy trình khác nhau bằng cách ánh xạ các biến quy trình tương ứng vào các tham số đầu vào mà tác vụ đó mong đợi.
• Chuyển đổi dữ liệu: Bạn có thể thực hiện các phép biến đổi dữ liệu đơn giản (ghép chuỗi, tính toán cơ bản) ngay tại lớp ánh xạ mà không cần thay đổi code Java.

2. Cấu hình Input/Output Mapping trong Camunda Modeler

Để hiểu rõ hơn, hãy xem cách thực hiện việc này trong Camunda Modeler.

Như bạn đã đọc, việc cấu hình được thực hiện trong tab Input/Output của Properties Panel.

Trong tab này, bạn có hai phần chính: Input Parameters và Output Parameters.

Input Parameters

Đối với mỗi tham số đầu vào, bạn cần định nghĩa:

• Name: Tên của biến cục bộ sẽ được tạo ra trong phạm vi của tác vụ.
• Type: Cách giá trị được gán. Các loại phổ biến là:
  • Text: Gán một chuỗi ký tự tĩnh.
  • Expression: Gán giá trị của một biểu thức EL. Đây là cách phổ biến nhất, ví dụ: ${orderId} để lấy giá trị của biến quy trình orderId.
  • Script: Viết một đoạn script ngắn (ví dụ: JavaScript, Groovy) để tính toán và trả về giá trị.
• Value: Giá trị hoặc biểu thức tương ứng với Type đã chọn.

Output Parameters

Đối với mỗi tham số đầu ra, bạn cần định nghĩa:

• Name: Tên của biến quy trình sẽ được tạo hoặc cập nhật.
• Type: Tương tự như Input Parameters.
• Source: Giá trị sẽ được gán cho biến quy trình. Giá trị này thường là tên của một biến cục bộ đã được tạo ra bởi logic của tác vụ, ví dụ: ${localResult}.

3. Ví dụ thực tế: Ánh xạ cho Service Task gọi API

Một trong những ứng dụng phổ biến nhất của Service Task là gọi một REST API bên ngoài. Input/Output mapping trở nên cực kỳ hữu ích trong kịch bản này để chuẩn bị request và xử lý response.

Camunda cung cấp một http-connector tích hợp sẵn, cho phép bạn thực hiện các lệnh gọi HTTP mà không cần viết code Java. Hãy xem cách Input/Output mapping được sử dụng trong trường hợp này.

Ví dụ trên cho thấy sức mạnh của việc ánh xạ:

• Đầu vào: Chúng ta không truyền thẳng đối tượng claims vào connector. Thay vào đó, chúng ta biến đổi nó thành chuỗi JSON, là định dạng mà API endpoint mong đợi.
• Đầu ra: Lệnh gọi HTTP trả về một chuỗi. Chúng ta không lưu chuỗi thô này vào biến quy trình. Thay vào đó, chúng ta biến đổi nó trở lại thành một đối tượng JSON có cấu trúc bằng hàm S(response) của SPIN, giúp các bước tiếp theo trong quy trình dễ dàng xử lý hơn.

4. Thực hành: Áp dụng Input/Output Mapping vào quy trình của bạn

Bây giờ, hãy quay lại quy trình xử lý đơn hàng của chúng ta và áp dụng kỹ thuật này.

Ở bài học trước, ProcessResultDelegate của bạn đang truy cập trực tiếp các biến quy trình như orderId và approved bằng execution.getVariable("..."). Chúng ta sẽ thay đổi điều này để nó nhận các tham số đầu vào một cách tường minh.

Yêu cầu:

1. Cấu hình Service Task "Xử lý Kết quả" để truyền vào hai biến cục bộ: localOrderId và statusMessage.
2. localOrderId sẽ được ánh xạ từ biến quy trình orderId.
3. statusMessage sẽ là một chuỗi được tạo động dựa trên giá trị của biến approved.
4. Cập nhật code của ProcessResultDelegate để đọc các biến cục bộ mới này thay vì các biến quy trình.
5. Cấu hình một tham số đầu ra để lưu thời gian xử lý vào một biến quy trình mới là processingTimestamp.

Các bước thực hiện:

1. Mở Camunda Modeler: Mở file BPMN của bạn.

2. Cấu hình Input Parameters:

   • Chọn Service Task "Xử lý Kết quả".
   • Trong Properties Panel, đi đến tab Input/Output.
   • Trong phần Input Parameters, nhấn nút + để thêm một tham số mới:
     • Name: localOrderId
     • Type: Expression
     • Value: ${orderId}
   • Thêm một tham số đầu vào khác:
     • Name: statusMessage
     • Type: Script
     • Script Format: javascript
     • Script Type: Inline Script
     • Script: approved ? "Đơn hàng đã được duyệt thành công." : "Trạng thái đơn hàng không hợp lệ.";
       (Biểu thức tam phân này sẽ tạo ra một thông điệp dựa trên biến quy trình approved).

3. Cập nhật Java Delegate:

   • Mở lớp ProcessResultDelegate.java trong IDE của bạn.
   • Thay đổi nội dung của phương thức execute như sau:

   @Override
   public void execute(DelegateExecution execution) throws Exception {
       // Lấy các biến cục bộ đã được ánh xạ
       String orderId = (String) execution.getVariable("localOrderId");
       String message = (String) execution.getVariable("statusMessage");
   
       System.out.println("--- Xử lý kết quả cho đơn hàng ---");
       System.out.println("ID Đơn hàng: " + orderId);
       System.out.println("Thông điệp: " + message);
   
       // Tạo một biến cục bộ để ánh xạ ra ngoài
       String timestamp = java.time.Instant.now().toString();
       execution.setVariable("timestamp", timestamp);
   
       System.out.println("Thời gian xử lý: " + timestamp);
       System.out.println("---------------------------------");
   }
   

   Lưu ý rằng bây giờ chúng ta đang gọi execution.getVariable("localOrderId"), không phải "orderId". Đồng thời, chúng ta tạo một biến cục bộ mới tên là timestamp.

4. Cấu hình Output Parameters:

   • Quay lại Camunda Modeler, vẫn ở tab Input/Output của Service Task.
   • Trong phần Output Parameters, thêm một tham số mới:
     • Name: processingTimestamp (đây là tên biến quy trình mới sẽ được tạo)
     • Type: Expression
     • Source: ${timestamp} (đây là tên biến cục bộ chúng ta đã tạo trong code Java)

5. Deploy và kiểm tra:

   • Deploy lại ứng dụng Spring Boot của bạn.
   • Bắt đầu một process instance mới.
   • Tại User Task, claim task, tạo biến approved là true và complete.
   • Kiểm tra log console. Bạn sẽ thấy các thông điệp được in ra từ ProcessResultDelegate, sử dụng đúng các giá trị đã được ánh xạ.
   • Vào Camunda Cockpit, xem lại process instance vừa hoàn thành. Trong tab Variables, bạn sẽ thấy một biến mới tên là processingTimestamp đã được tạo ra với giá trị là thời gian xử lý.

Bài thực hành này minh họa toàn bộ vòng đời của việc ánh xạ: truyền dữ liệu vào, xử lý, và truyền kết quả ra.

5. Tóm tắt và xem trước

Trong bài học này, bạn đã học được một trong những kỹ thuật quan trọng nhất để quản lý dữ liệu trong Camunda một cách chuyên nghiệp.

Những điểm chính cần nhớ:

• Input/Output Mapping hoạt động như một "hợp đồng dữ liệu" cho các tác vụ, giúp tăng tính đóng gói, linh hoạt và tái sử dụng.
• Input Mapping tạo ra các biến cục bộ cho tác vụ từ các biến quy trình.
• Output Mapping cập nhật các biến quy trình từ kết quả xử lý bên trong tác vụ.
• Bạn có thể sử dụng Expression hoặc Script để thực hiện các phép biến đổi dữ liệu đơn giản ngay tại lớp ánh xạ.
• Kỹ thuật này cực kỳ hữu ích khi tích hợp với các hệ thống bên ngoài, chẳng hạn như gọi REST API thông qua HTTP Connector.

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

Chúng ta đã làm việc với các kiểu dữ liệu cơ bản như String, Boolean và Number. Nhưng trong các ứng dụng thực tế, dữ liệu thường phức tạp hơn nhiều, ví dụ như các đối tượng Customer, Order, Product với nhiều thuộc tính.

Trong bài học tiếp theo, chúng ta sẽ khám phá cách lưu trữ và truy xuất các đối tượng Java phức tạp (POJOs) dưới dạng biến quy trình. Bạn sẽ học cách Camunda tuần tự hóa (serialize) các đối tượng này và cách bạn có thể tương tác với chúng trong quy trình, bao gồm cả việc sử dụng Input Mapping để trích xuất các thuộc tính cụ thể từ một đối tượng lớn.