Bài 27 — XML serialization của BPMN file — Business Process Mapping and BPMN

Mở đầu — vì sao bài này quan trọng

Khi bạn vẽ một quy trình bằng Camunda Modeler, Bizagi hay draw.io, thứ bạn nhìn thấy là những hình tròn, hình thoi, mũi tên đẹp đẽ. Nhưng đó chỉ là phần "mặt tiền". Bên dưới, mỗi file .bpmn thực chất là một tài liệu XML — văn bản thuần túy mà máy tính đọc, lưu trữ và trao đổi. Nếu bạn mở file .bpmn bằng Notepad hay VS Code, bạn sẽ thấy hàng trăm dòng tag <bpmn:...>.

Tại sao một Business Process Analyst lại cần hiểu lớp XML này, trong khi đã có công cụ vẽ kéo-thả? Có ba lý do rất thực tế.

Thứ nhất, tính tương thích giữa các tool. Chuẩn BPMN 2.0 do OMG (Object Management Group) ban hành kèm theo một XML schema chính thức. Nghĩa là một file vẽ bằng Bizagi về lý thuyết phải mở được bằng Camunda. Nhưng "về lý thuyết" và "thực tế" thường lệch nhau, và khi lệch, bạn phải mở XML ra để biết tại sao.

Thứ hai, automation và tích hợp. Khi quy trình của bạn được đưa vào một process engine để chạy thật (deploy), engine không quan tâm hình vẽ đẹp hay xấu — nó đọc XML. Nếu XML thiếu thuộc tính, sai cú pháp, engine sẽ từ chối hoặc chạy sai. Nhiều bug "khó hiểu" trong hệ thống BPM thực chất nằm ở vài dòng XML.

Thứ ba, version control và làm việc nhóm. File .bpmn là text nên có thể đưa vào Git. Bạn có thể so sánh hai phiên bản (diff), review thay đổi như review code. Đây là điều bạn không làm được với file ảnh hay file nhị phân.

Bài này không biến bạn thành lập trình viên. Mục tiêu là giúp bạn đọc hiểu cấu trúc một file BPMN XML, biết phần nào là logic quy trình và phần nào là thông tin hình vẽ, và xử lý được những tình huống thực tế khi file không mở được giữa các tool.

Khái niệm cốt lõi

File `.bpmn` là gì

File .bpmn (đôi khi có đuôi .bpmn20.xml) là một tài liệu XML tuân theo schema do OMG định nghĩa. XML — Extensible Markup Language — là cách biểu diễn dữ liệu có cấu trúc bằng các cặp thẻ (tag) lồng nhau. Mỗi phần tử trong quy trình của bạn — một task, một gateway, một mũi tên — đều trở thành một phần tử XML có tên, có ID và có thuộc tính.

Điểm mấu chốt cần nhớ: vì là chuẩn mở, bất kỳ tool nào tuân thủ BPMN 2.0 đều có thể đọc và ghi cùng một file. Đây chính là giá trị lớn nhất của việc chuẩn hóa: bạn không bị khóa chặt vào một nhà cung cấp.

Cấu trúc cơ bản của một file BPMN

Một file BPMN luôn có khung sườn như sau:

<?xml version="1.0" encoding="UTF-8"?>
<bpmn:definitions
    xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
    xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI"
    xmlns:dc="http://www.omg.org/spec/DD/20100524/DC"
    xmlns:di="http://www.omg.org/spec/DD/20100524/DI"
    targetNamespace="http://example.com/quy-trinh">
  <bpmn:process id="Process_DonHang" name="Xử lý đơn hàng" isExecutable="true">
    <!-- Logic quy trình nằm ở đây -->
  </bpmn:process>
  <bpmndi:BPMNDiagram id="Diagram_1">
    <!-- Thông tin hình vẽ nằm ở đây -->
  </bpmndi:BPMNDiagram></bpmn:definitions>

Hãy tách bạch từng phần.

<bpmn:definitions> là phần tử gốc (root) bao bọc toàn bộ file. Phần xmlns: (XML namespace) khai báo các "từ điển" mà file sử dụng. Đây là điểm hay gây nhầm: namespace giống như họ của các tag. bpmn: là namespace cho logic quy trình, bpmndi: là cho thông tin hình vẽ (DI = Diagram Interchange). Mỗi namespace trỏ tới một URL — nhưng đừng nhầm, URL này chỉ là định danh duy nhất, không phải địa chỉ để tải về. Nó chỉ cần giống hệt giữa các tool để chúng "hiểu nhau".

targetNamespace là namespace riêng của file bạn — giống như đặt tên không gian cho quy trình của chính bạn để không đụng độ với quy trình khác.

Hai thế giới: Logic và Diagram

Đây là khái niệm quan trọng nhất của bài. Một file BPMN gồm hai phần tách rời:

Phần ngữ nghĩa (semantic) nằm trong <bpmn:process>: mô tả quy trình làm gì — có những task nào, gateway rẽ nhánh ra sao, các phần tử nối với nhau thế nào. Process engine chỉ đọc phần này.

Phần hình vẽ (diagram interchange) nằm trong <bpmndi:BPMNDiagram>: mô tả quy trình trông như thế nào — mỗi hình nằm ở tọa độ x, y nào, to bao nhiêu, mũi tên uốn qua những điểm nào.

Vì sao OMG tách hai phần? Vì một quy trình logic có thể được vẽ theo nhiều cách hình học khác nhau mà ý nghĩa không đổi. Tách ra giúp engine bỏ qua phần hình vẽ khi chạy, và giúp tool vẽ lại được sơ đồ đúng vị trí khi mở file.

Các phần tử logic thường gặp

Bên trong <bpmn:process>, bạn sẽ gặp:

<bpmn:startEvent id="Start_1" name="Nhận đơn">
  <bpmn:outgoing>Flow_1</bpmn:outgoing>
</bpmn:startEvent>
<bpmn:task id="Task_KiemTra" name="Kiểm tra tồn kho">
  <bpmn:incoming>Flow_1</bpmn:incoming>
  <bpmn:outgoing>Flow_2</bpmn:outgoing>
</bpmn:task>
<bpmn:exclusiveGateway id="Gateway_1" name="Còn hàng?">
  <bpmn:incoming>Flow_2</bpmn:incoming>
  <bpmn:outgoing>Flow_Co</bpmn:outgoing>
  <bpmn:outgoing>Flow_Khong</bpmn:outgoing>
</bpmn:exclusiveGateway><bpmn:sequenceFlow id="Flow_1" sourceRef="Start_1" targetRef="Task_KiemTra" />

Hãy chú ý cách các phần tử liên kết với nhau. Có hai cơ chế:

sequenceFlow (mũi tên) khai báo sourceRef (nguồn) và targetRef (đích) — đây là "nguồn sự thật" về việc cái gì nối với cái gì.
Mỗi task/event/gateway lại có thẻ con <incoming> và <outgoing> liệt kê ID của các flow đi vào/đi ra. Đây là thông tin lặp lại để engine duyệt nhanh hơn.

Quy tắc vàng: mỗi phần tử có một id duy nhất. Các flow tham chiếu tới nhau bằng id. Nếu một id bị trùng hoặc một targetRef trỏ tới id không tồn tại, file sẽ hỏng.

Phần Diagram Interchange (DI)

<bpmndi:BPMNDiagram id="Diagram_1">
  <bpmndi:BPMNPlane id="Plane_1" bpmnElement="Process_DonHang">
    <bpmndi:BPMNShape id="Shape_Start" bpmnElement="Start_1">
      <dc:Bounds x="150" y="100" width="36" height="36" />
    </bpmndi:BPMNShape>
    <bpmndi:BPMNEdge id="Edge_Flow1" bpmnElement="Flow_1">
      <di:waypoint x="186" y="118" />
      <di:waypoint x="250" y="118" />
    </bpmndi:BPMNEdge>
  </bpmndi:BPMNPlane>
</bpmndi:BPMNDiagram>

Mỗi BPMNShape gắn với một phần tử logic qua thuộc tính bpmnElement (trỏ về id của task/event). <dc:Bounds> cho biết tọa độ và kích thước. BPMNEdge là mũi tên, với các waypoint là các điểm gấp khúc. Nếu phần DI bị thiếu cho một phần tử, tool mở file ra sẽ thấy "phần tử lơ lửng" hoặc tự đặt nó ở góc (0,0).

Tình huống thực tế

Tình huống 1 — Công ty fintech Việt chuyển file giữa Bizagi và Camunda

Một startup fintech tại TP.HCM (gọi là VietPay) có đội nghiệp vụ dùng Bizagi Modeler để vẽ quy trình duyệt khoản vay, còn đội kỹ thuật dùng Camunda để chạy thật. Khi đội nghiệp vụ gửi file .bpmn cho đội tech, Camunda báo lỗi: "Cannot deploy, no executable process found".

Mở file XML ra, đội tech phát hiện thẻ process là <bpmn:process id="..." name="..." mà thiếu isExecutable="true" — Bizagi mặc định xuất ra isExecutable="false" vì nó coi sơ đồ là tài liệu mô tả, không phải để chạy. Camunda thì bỏ qua mọi process không executable. Chỉ cần sửa một thuộc tính, file deploy được ngay.

Bài học: nhiều lỗi liên-tool không nằm ở logic mà ở một thuộc tính nhỏ. Biết đọc XML giúp bạn chẩn đoán trong 5 phút thay vì đổ lỗi cho nhau cả buổi họp. VietPay sau đó thêm một bước "chuẩn hóa XML" trước khi bàn giao: kiểm tra isExecutable, kiểm tra ID hợp lệ.

Tình huống 2 — Đưa BPMN vào Git để review như code

Một công ty gia công phần mềm ở Đà Nẵng quản lý hơn 200 quy trình cho khách hàng Nhật. Trước đây họ lưu sơ đồ dưới dạng ảnh PNG và file Visio. Mỗi lần khách yêu cầu đổi quy trình, không ai biết chính xác cái gì đã đổi — phải so sánh ảnh bằng mắt.

Họ chuyển sang lưu file .bpmn trong Git. Vì là XML text, mỗi lần commit, công cụ diff hiện rõ: dòng <bpmn:userTask id="Task_Duyet" name="Duyệt cấp 2"> được thêm vào, một sequenceFlow được đổi targetRef. Người review chỉ cần đọc diff là biết thay đổi nghiệp vụ.

Tuy nhiên họ gặp một rắc rối: mỗi lần chỉ kéo nhẹ một hình, tọa độ trong phần DI thay đổi, tạo ra hàng chục dòng diff "nhiễu" dù logic không đổi. Họ giải quyết bằng quy ước: diff logic là quan trọng, diff tọa độ trong <bpmndi:> thì bỏ qua. Một số đội còn dùng tool để "format" XML nhất quán trước khi commit, giảm nhiễu.

Bài học: XML mở ra khả năng quản lý phiên bản chuyên nghiệp cho quy trình, nhưng bạn cần phân biệt thay đổi ngữ nghĩa với thay đổi hình vẽ để review hiệu quả.

Tình huống 3 — Mất phần hình vẽ khi xuất file

Một ngân hàng (tình huống giả định dựa trên thực tế phổ biến) có team dùng một tool sinh BPMN tự động từ mô tả nghiệp vụ. Tool này xuất ra XML đầy đủ phần <bpmn:process> nhưng không sinh phần <bpmndi:BPMNDiagram>. Khi nhân viên nghiệp vụ mở file bằng Camunda Modeler, họ thấy một canvas trống trơn — dù file chứa đầy đủ logic.

Nguyên nhân: thiếu phần DI nên tool không biết vẽ hình ở đâu. Một số tool hiện đại có chức năng "auto-layout" để tự sinh DI, nhưng tool cũ thì không. Giải pháp của họ là dùng bpmn-js (thư viện của Camunda) chạy auto-layout để bổ sung phần DI.

Bài học: một file BPMN "hợp lệ về logic" vẫn có thể "vô hình" nếu thiếu DI. Khi bàn giao file cho người dùng cuối, luôn kiểm tra cả hai phần đều có mặt.

Hướng dẫn từng bước

Dưới đây là quy trình thực hành để bạn tự đọc và kiểm tra một file BPMN XML.

Bước 1 — Mở file bằng trình soạn thảo text. Dùng VS Code, Notepad++ hoặc bất kỳ editor nào. Đừng dùng Word. Nếu file dài và rối, bật tính năng "Format Document" để XML xuống dòng và thụt lề gọn gàng.

Bước 2 — Tìm phần tử gốc <bpmn:definitions>. Xác nhận có các khai báo xmlns:bpmn và xmlns:bpmndi. Ghi nhớ tiền tố namespace mà file dùng — đôi khi là bpmn:, đôi khi là bpmn2: hoặc không tiền tố. Điều này ảnh hưởng cách bạn tìm kiếm trong file.

Bước 3 — Định vị <bpmn:process>. Kiểm tra hai thuộc tính: id (phải có) và isExecutable. Nếu bạn định deploy lên engine, isExecutable phải là true.

Bước 4 — Đọc các phần tử logic theo dòng chảy. Bắt đầu từ <bpmn:startEvent>, tìm outgoing của nó, rồi lần theo sequenceFlow có id tương ứng để biết nó nối tới đâu qua targetRef. Cứ thế đi đến <bpmn:endEvent>. Đây chính là cách "đọc quy trình bằng văn bản".

Bước 5 — Kiểm tra tính toàn vẹn của tham chiếu. Với mỗi sequenceFlow, xác nhận sourceRef và targetRef đều trỏ tới những id thật sự tồn tại trong file. Đây là lỗi phổ biến nhất khiến file hỏng.

Bước 6 — Xem phần DI nếu cần. Mở <bpmndi:BPMNDiagram>, kiểm tra mỗi phần tử logic quan trọng có một BPMNShape hoặc BPMNEdge tương ứng (qua thuộc tính bpmnElement). Nếu thiếu, hình sẽ không hiển thị.

Bước 7 — Validate bằng tool. Cách chắc chắn nhất: mở lại file bằng một BPMN modeler (Camunda Modeler miễn phí là lựa chọn tốt). Nếu tool mở được và hiển thị đúng, file của bạn ổn. Nếu tool báo lỗi, thông báo lỗi thường chỉ thẳng dòng XML có vấn đề.

Lỗi thường gặp & mẹo

Lỗi 1 — Nhầm namespace URL là đường dẫn tải về. Nhiều người thấy http://www.omg.org/spec/BPMN/... rồi cố mở bằng trình duyệt, thấy không tải được nên tưởng file hỏng. Đó chỉ là định danh, không phải link. Đừng đụng vào.

Lỗi 2 — Sửa tay làm trùng id. Khi copy-paste một task trong XML để nhân bản, người ta quên đổi id. Hai phần tử cùng id khiến engine bối rối và file trở nên không hợp lệ. Mẹo: mọi id phải là duy nhất trong toàn file.

Lỗi 3 — Quên isExecutable="true" khi muốn deploy. Như tình huống VietPay. Luôn kiểm tra thuộc tính này nếu file sẽ chạy trên engine.

Lỗi 4 — Tham chiếu mồ côi (orphan reference). Xóa một task nhưng quên xóa sequenceFlow trỏ vào nó, để lại targetRef chỉ tới id không còn tồn tại. Luôn xóa cả flow đi kèm.

Lỗi 5 — Chỉnh tay phá vỡ cú pháp XML. Quên đóng tag, sai dấu ngoặc kép, ký tự đặc biệt như & chưa được mã hóa thành &. XML rất khó tính. Mẹo: sau khi sửa tay, luôn mở lại bằng modeler để validate.

Mẹo lớn nhất: trong 95% trường hợp, đừng sửa XML bằng tay. Hãy sửa trong tool vẽ rồi xuất lại. Chỉ chạm vào XML khi (a) chẩn đoán lỗi liên-tool, (b) cần sửa hàng loạt bằng script, hoặc (c) tool không cho bạn truy cập một thuộc tính nào đó. Hiểu XML để đọc và chẩn đoán quan trọng hơn nhiều so với để viết tay.

Mẹo phụ: khi gửi file cho đối tác dùng tool khác, hãy gửi kèm một ảnh PNG xuất ra. Nếu file XML có trục trặc DI, ít nhất họ vẫn thấy được sơ đồ tham chiếu.

Bài tập thực hành

Đọc ngược từ XML ra sơ đồ. Lấy đoạn XML trong phần "Các phần tử logic thường gặp" ở trên (start event → task kiểm tra tồn kho → gateway "Còn hàng?"). Chỉ nhìn XML, hãy vẽ tay lại sơ đồ quy trình trên giấy. Sau đó nhập đúng đoạn đó vào Camunda Modeler và so sánh với hình bạn vẽ.

Tự tạo và mổ xẻ file. Tải Camunda Modeler miễn phí. Vẽ một quy trình đơn giản 5 phần tử (start → task → exclusive gateway → 2 task → end). Lưu file. Mở file .bpmn đó bằng VS Code. Tô màu (highlight) bằng mắt: phần nào là <bpmn:process>, phần nào là <bpmndi:>. Đếm xem có bao nhiêu sequenceFlow.

Phá rồi sửa. Trong file vừa tạo, dùng VS Code đổi một targetRef của một sequenceFlow sang một id không tồn tại. Lưu lại, mở bằng Camunda Modeler và quan sát lỗi. Sau đó sửa lại cho đúng. Bài tập này giúp bạn quen với cảm giác chẩn đoán lỗi tham chiếu.

Thử tính tương thích. Nếu có điều kiện, xuất một file từ draw.io rồi mở bằng Camunda Modeler (và ngược lại). Ghi lại xem có thuộc tính nào bị mất, có cảnh báo nào xuất hiện. Đây là kỹ năng cực kỳ thực tế trong môi trường nhiều tool.

Tóm tắt

File .bpmn không phải là một hình ảnh — nó là một tài liệu XML tuân theo chuẩn mở của OMG, và chính tính mở này cho phép các tool khác nhau đọc-ghi cùng một file. Cấu trúc của nó gồm phần tử gốc <bpmn:definitions> bao bọc hai thế giới tách biệt: phần logic (<bpmn:process>) mô tả quy trình làm gì và là thứ duy nhất mà process engine quan tâm, và phần hình vẽ (<bpmndi:BPMNDiagram>) mô tả quy trình trông như thế nào với tọa độ và kích thước.

Mỗi phần tử có một id duy nhất, và các mũi tên sequenceFlow liên kết chúng qua sourceRef/targetRef. Hiểu được điều này giúp bạn đọc một quy trình ngay từ văn bản, chẩn đoán lỗi liên-tool (như thiếu isExecutable), quản lý phiên bản quy trình bằng Git, và xử lý sự cố mất hình vẽ do thiếu phần DI.

Nguyên tắc cuối cùng cần khắc cốt: hiểu XML để đọc và chẩn đoán, đừng vội sửa tay. Công cụ vẽ vẫn là nơi bạn nên làm việc chính; XML là lớp giúp bạn nhìn sâu khi mọi thứ trục trặc. Một Business Process Analyst biết mở nắp capo và đọc được động cơ XML bên dưới sẽ luôn tự tin hơn người chỉ biết lái xe bằng vô-lăng kéo-thả.

Bài 27 — XML serialization của BPMN file