BPMN Diff Tool¶

Visual side-by-side comparison of BPMN process versions with granular XML-level change detection. Essential for safe deployments, code reviews, and audit trails.

Overview¶

The BPMN Diff Tool provides precise comparison of two process versions, highlighting every change from visual layout to technical attributes. It combines visual diagram comparison with deep XML analysis.

Key Features¶

🎨 Visual Side-by-Side Comparison - Interactive diagrams with color-coded changes
🔍 Granular XML Diff - Attribute-level change detection
📊 Interactive Change Table - Hover to highlight, click to zoom
📄 HTML Report Generation - Export complete analysis
📁 Flexible Input - Compare database versions or local files

How It Works¶

Comparison Process¶

graph LR
    A[Select Versions] --> B[Load BPMN XML]
    B --> C[Parse & Compare]
    C --> D[Visual Diff]
    C --> E[XML Analysis]
    D --> F[Interactive View]
    E --> F
    F --> G[Generate Report]

Hold "Alt" / "Option" to enable pan & zoom

Change Detection:

Visual comparison using bpmn-js-differ library
Deep XML parsing with lxml
Extension elements analysis (Camunda-specific)
Attribute-level change tracking

Color Coding:

🟢 Green - Added elements
🔴 Red - Removed elements
🟡 Yellow - Modified elements (properties changed)
🔵 Blue - Layout changes (position/size only)

Quick Start¶

Step 1: Access Diff Tool¶

Navigate to /diff or click BPMN Diff in the main menu.

Step 2: Select Versions¶

Option A: Database Versions

Left Panel:
  BPMN Name: order-to-cash
  Version: 2

Right Panel:
  BPMN Name: order-to-cash
  Version: 3

Option B: Local File vs Database

Left Panel:
  Upload: order-to-cash-dev.bpmn (from local)

Right Panel:
  BPMN Name: order-to-cash
  Version: 3 (production)

Step 3: View Changes¶

Automatic highlighting when both versions load
Changes summary displays: Added (green), Removed (red), Changed (yellow)
Interactive table at bottom lists all changes

Step 4: Analyze Details¶

For modified elements:

Click element on diagram → shows attribute table
Hover table row → highlights element
Click "View Full XML Diff" → opens detailed modal

Interface Guide¶

Diagram Panels¶

Left & Right Panels:

Collapsible headers (click ± icon)
Dropdown for database selection
Drag-and-drop file upload
Synchronized zoom/pan

Controls:

Mouse wheel: Zoom
Click-drag: Pan
Click header: Collapse/expand

Changes Overview¶

Bottom Panel:

Toggle visibility: Click "List of Changes"
Summary: + 3 − 2 ✎ 5 (Added, Removed, Changed)
Checkbox: Show/hide layout changes

Change Table:

#	Name	Type	Change
0	Validate Payment	ServiceTask	Changed
1	Send Email	SendTask	Added

Interactions:

Hover row → Highlights element on diagram
Click row → Zooms to element
Click "View Full XML Diff" → Opens modal

Shows side-by-side comparison:

<!-- Left (Old) -->                    <!-- Right (New) -->
<serviceTask                           <serviceTask
  id="Activity_1"                        id="Activity_1"
  name="Validate"                        name="Validate Payment"
  camunda:class="ValidateTask">          camunda:class="PaymentValidator">

Red highlighting: Removed/changed (left)
Green highlighting: Added/changed (right)
Uses diff2html for formatting

Use Cases¶

Pre-Deployment Validation¶

Scenario: Compare local dev file with production

// 1. Develop locally: order-to-cash-v4.bpmn
// 2. Open diff tool
// 3. Upload local file (left)
// 4. Select production v3 (right)
// 5. Review all changes
// 6. Generate report for deployment ticket

Catches:

Unintended configuration changes
Missing error handlers
Changed service task classes
New variables not in deployment script

Code Review¶

Scenario: Review BPMN changes in pull request

Export both versions from Git
Load in diff tool
Generate HTML report
Attach to PR
Reviewers see visual + technical changes

Post-Deployment Audit¶

Scenario: Verify deployment correctness

-- Get versions before/after deployment
SELECT key_, version_, deploy_time_ 
FROM act_re_procdef 
WHERE key_ = 'order-to-cash'
ORDER BY version_ DESC 
LIMIT 2;

Compare in diff tool → confirm expected changes only.

Troubleshooting¶

Scenario: Process broke after deployment

Load broken version (current)
Load previous working version
Identify differences
Focus on changed service tasks, expressions
Rollback or hotfix specific changes

Comparison Modes¶

Database vs Database¶

Use when: Comparing deployed versions

Setup:

Left: Select process + version from dropdown
Right: Select same/different process + version

Example:

Left: order-to-cash v2
Right: order-to-cash v3

Local File vs Database¶

Use when: Pre-deployment validation

Setup:

Left: Upload .bpmn file (drag or click)
Right: Select production version

File Requirements:

Max size: 10MB
Format: .bpmn or .xml
Valid BPMN 2.0 structure

Drag & Drop:

Drag file over left/right panel
Dashed border appears
Drop to upload

Understanding Changes¶

Change Types¶

Added Elements (🟢)¶

New activities, gateways, events added to process

Example:

New service task "Send Notification"
New error boundary event
New subprocess

Removed Elements (🔴)¶

Elements present in old version but deleted

Example:

Removed manual task "Review Document"
Deleted timer event
Removed connector configuration

Changed Elements (🟡)¶

Elements exist in both but properties differ

Common Changes:

Service task class: OldValidator → NewValidator
Expression: ${status == 'pending'} → ${status == 'approved'}
Assignee: ${manager} → ${senior_manager}
Input/output mappings modified
Listener configurations changed

Layout Changes (🔵)¶

Element moved or resized, no property changes

Why track:

Visual clarity in diagrams
Optional in reports (can hide)
Usually not critical

XML Diff Details¶

When you click "View Full XML Diff" on a changed element:

Shows:

Complete XML structure
Every attribute change
Extension elements (Camunda-specific)
Nested configurations

Example Output:

extensionElements.camunda:inputParameter[@name='paymentMethod']
  Old: creditCard
  New: paymentGateway

extensionElements.camunda:executionListener[@event='start']
  Old: null
  New: com.example.PaymentStartListener

Extension Elements Analysis¶

Diff tool deeply compares:

Input/Output Parameters:

<camunda:inputParameter name="amount">
  Old: ${price}
  New: ${price + tax}
</camunda:inputParameter>

Execution Listeners:

<camunda:executionListener event="start" class="...">
  Added: com.example.AuditListener

Connector Configurations:

<camunda:connector>
  <camunda:inputParameter name="url">
    Old: http://api.example.com/v1
    New: http://api.example.com/v2
  </camunda:inputParameter>
</camunda:connector>

Report Generation¶

Creating Reports¶

Load and compare two versions
Wait for changes to display
Click "View Diff Report" button
Review in modal
Click "Generate Report"

Report Contents¶

Header:

Comparison: process-name v2 vs v3
Generated timestamp
Summary: Added, Removed, Changed counts

Table:

Element	Type	Version A	Version B
Validate Payment	ServiceTask	Changed: class=OldValidator	Changed: class=NewValidator
Send Email	SendTask	-	Added

For Each Change:

Element name and ID
Element type (ServiceTask, Gateway, etc.)
Old values (left column)
New values (right column)
Detailed attribute changes

Report Format¶

HTML Export:

<!DOCTYPE html>
<html>
<head>
    <title>BPMN Changes Report - order-to-cash v2 vs v3</title>
    <style>/* Embedded styles for standalone viewing */</style>
</head>
<body>
    <h1>BPMN Changes Report</h1>
    <!-- Complete formatted report -->
</body>
</html>

File name: BPMN_Changes_Report_{processA}_v{versionA}_vs_{processB}_v{versionB}_{timestamp}.html

Use cases:

Attach to JIRA tickets
Email to stakeholders
Archive for compliance
Include in deployment documentation

Shareable Links¶

Diff tool supports URL parameters for direct loading:

Format:

/diff?bpmn_name_a={process}&bpmn_version_a={version}&bpmn_name_b={process}&bpmn_version_b={version}

Example:

https://champa.example.com/diff?bpmn_name_a=order-to-cash&bpmn_version_a=2&bpmn_name_b=order-to-cash&bpmn_version_b=3

Benefits:

Share exact comparison with team
Bookmark common comparisons
Include in documentation
Embed in tickets

Automatic URL Update:

URL updates when you select versions
Browser back/forward works
Refresh preserves selection

API Usage¶

Get BPMN Content¶

GET /diff/api/bpmn_content?process_key={key}&version={version}
Authorization: Bearer <token>

Response: Raw BPMN XML

Example:

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8088/diff/api/bpmn_content?process_key=order-to-cash&version=3"

Upload File¶

POST /diff/api/upload
Authorization: Bearer <token>
Content-Type: multipart/form-data

Request:

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@order-to-cash-dev.bpmn" \
  "http://localhost:8088/diff/api/upload"

Response:

{
  "success": true,
  "filename": "tmp_20250115_103000_order-to-cash-dev.bpmn"
}

Note: Use returned filename with version=0 in comparison.

Configuration¶

File Upload Limits¶

File: diff_tool.py

# Default limits
MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB
ALLOWED_EXTENSIONS = ['.bpmn', '.xml']

# Temp directory
TEMP_DIR = 'tmp'

Security¶

File Upload:

Filename sanitization (alphanumeric + ._ only)
Timestamped unique names
Directory traversal prevention
File type validation

Database Access:

Requires diff_tool_data permission
Per-user authentication via require_auth
No direct SQL injection vectors

Troubleshooting¶

"Could not retrieve BPMN data"¶

Cause: Process/version not found in database or temp file expired

Solutions:

-- Verify version exists
SELECT * FROM act_re_procdef 
WHERE key_ = 'your-process' AND version_ = 3;

-- Check deployment
SELECT * FROM act_re_deployment 
ORDER BY deploy_time_ DESC LIMIT 10;

For uploaded files: Re-upload (temp files cleaned periodically)

Changes not displaying¶

Cause: XML normalization issues or layout-only changes

Check:

Enable "Show Layout Changes" checkbox
Verify changes exist: Open XML in text editor
Look for whitespace/formatting differences

Fix:

# XML normalization handles:
- Line ending differences (\r\n vs \n)
- Whitespace variations
- Tab vs space
- Blank lines

Symptom: Click "View Full XML Diff" - nothing happens

Solutions:

Check browser console for JavaScript errors
Verify diff2html library loaded
Refresh page
Try "Open in New Page" link instead

Best Practices¶

Pre-Deployment Workflow¶

# 1. Export from dev
git show HEAD:processes/order-to-cash.bpmn > order-to-cash-dev.bpmn

# 2. Open diff tool
# 3. Upload dev file (right)
# 4. Select production version (left)

# 5. Review checklist:

✓ Service task classes exist in classpath
✓ New variables added to deployment script
✓ Listener classes compiled and deployed
✓ External task topics configured
✓ Timer expressions validated
✓ No unintended deletions

# 6. Generate report
# 7. Attach to deployment ticket

Code Review Process¶

For Reviewers:

Request BPMN diff report in PR
Review visual changes first
Check modified elements table
Focus on:
Service task class changes
Expression modifications
New error handling
Security implications

For Developers:

Generate diff report before PR
Add summary to PR description
Highlight breaking changes
Document migration steps if needed

Version Comparison Strategy¶

Comparing adjacent versions:

v2 vs v3 - See incremental changes

Comparing across multiple versions:

v1 vs v5 - See cumulative evolution

Comparing branches:

main vs feature-branch

Integration Examples¶

CI/CD Pipeline¶

# .github/workflows/bpmn-validation.yml
- name: Generate BPMN Diff
  run: |
    # Upload new version
    curl -X POST -F "file=@process.bpmn" \
      http://champa/diff/api/upload

    # Compare (TODO: Add automation endpoint)
    # Manual review for now

JIRA Integration¶

## BPMN Changes

Comparison: order-to-cash v2 → v3

[View Interactive Diff](http://champa/diff?bpmn_name_a=order-to-cash&bpmn_version_a=2&bpmn_name_b=order-to-cash&bpmn_version_b=3)

### Summary

- 3 Added elements
- 1 Removed element
- 5 Changed elements

See attached HTML report for details.

FAQ¶

Q: Can I compare processes from different Camunda instances? A: Not directly. Export XML from both, upload as files.

Q: Does it show subprocess changes? A: Yes, if subprocess BPMN is embedded. Call activities need separate comparison.

Q: How long are uploaded files kept? A: They are stored in tmp folder and may be deleted according to defined policy.

Q: Can I compare BPMN 1.x processes? A: No, only BPMN 2.0 supported.

Q: Does it compare process instance data? A: No, only process definitions (BPMN XML).

Next Steps¶

Process Intelligence - Analyze process execution
AI Analysis - Get insights on changes impact

Last updated: 2025-01-15 | Edit on GitHub

BPMN Diff Tool¶

Overview¶

Key Features¶

How It Works¶

Comparison Process¶

Quick Start¶

Step 1: Access Diff Tool¶

Step 2: Select Versions¶

Step 3: View Changes¶

Step 4: Analyze Details¶

Interface Guide¶

Diagram Panels¶

Changes Overview¶

XML Diff Modal¶

Use Cases¶

Pre-Deployment Validation¶

Code Review¶

Post-Deployment Audit¶

Troubleshooting¶

Comparison Modes¶

Database vs Database¶

Local File vs Database¶

Understanding Changes¶

Change Types¶

Added Elements (🟢)¶

Removed Elements (🔴)¶

Changed Elements (🟡)¶

Layout Changes (🔵)¶

XML Diff Details¶

Extension Elements Analysis¶

Report Generation¶

Creating Reports¶

Report Contents¶

Report Format¶

URL Sharing¶

Shareable Links¶

API Usage¶

Get BPMN Content¶

Upload File¶

Configuration¶

File Upload Limits¶

Security¶

Troubleshooting¶

"Could not retrieve BPMN data"¶

Changes not displaying¶

Modal not opening¶

Best Practices¶

Pre-Deployment Workflow¶

Code Review Process¶

Version Comparison Strategy¶

Integration Examples¶

CI/CD Pipeline¶

JIRA Integration¶

FAQ¶

Next Steps¶