bpmn-to-drawio

What this skill does

# BPMN to Draw.io Converter

## Overview

This skill converts BPMN 2.0 XML files into Draw.io native format (.drawio) using the `bpmn2drawio` Python tool. The tool provides:

- Automatic Graphviz-based layout for files without DI coordinates
- Four built-in themes with custom YAML branding support
- Visual markers for gateways (X, +, O) and task/event icons
- Complete swimlane support with proper hierarchy
- Model validation with error recovery

## Conversion Workflow

Follow these steps in order. The workflow automatically handles dependency installation.

### Step 1: Set Up Tool Path

The tool is bundled in the plugin's `tools/bpmn2drawio/` directory. Use `${CLAUDE_PLUGIN_ROOT}` for the plugin path (auto-set for marketplace-installed plugins):

```bash
# Use CLAUDE_PLUGIN_ROOT (auto-set for marketplace-installed plugins)
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-/path/to/plugins/bpmn-plugin}"
TOOL_SRC="$PLUGIN_DIR/tools/bpmn2drawio/src"
```

### Step 2: Check and Install Python Dependencies

Check for required Python packages and install any that are missing:

```bash
# Check which packages are missing
python -c "import lxml" 2>/dev/null || echo "lxml: MISSING"
python -c "import networkx" 2>/dev/null || echo "networkx: MISSING"
python -c "import yaml" 2>/dev/null || echo "pyyaml: MISSING"
python -c "import pygraphviz" 2>/dev/null || echo "pygraphviz: MISSING (requires Graphviz)"
```

**If any packages are missing (except pygraphviz), ask the user:**
> "The following Python packages are missing: [list]. Install them now with `pip install [packages]`?"

If user approves:
```bash
pip install lxml networkx pyyaml
```

**Note:** `pygraphviz` is handled separately in Step 3 because it requires Graphviz.

### Step 3: Check Graphviz and pygraphviz

**CRITICAL:** Graphviz is required for automatic layout. Check BEFORE any processing:

```bash
# Check for Graphviz
dot -V 2>/dev/null && echo "Graphviz: OK" || echo "Graphviz: MISSING"
```

**If Graphviz is missing**, display this standardized error:

```text
Error: Required dependency 'graphviz' not found

/bpmn-to-drawio requires Graphviz for automatic diagram layout.

Installation instructions:
  Windows: choco install graphviz
  macOS:   brew install graphviz
  Linux:   sudo apt install graphviz libgraphviz-dev

After installing Graphviz, also install the Python bindings:
  pip install pygraphviz

After installing, run the command again.

Note: If your BPMN file already has layout coordinates, you can skip
Graphviz and use: /bpmn-to-drawio input.bpmn output.drawio --layout=preserve
```

**Important Decision Point:**

Before showing the error, check if the BPMN file has DI coordinates (Step 4):
- If `HAS_DI=true`: Offer the `--layout=preserve` alternative
- If `HAS_DI=false`: Graphviz is required, display the full error

**If user wants to install Graphviz**, guide them through:

```bash
# Detect OS and install
if [[ "$OSTYPE" == "linux-gnu"* ]]; then
    sudo apt-get update && sudo apt-get install -y graphviz libgraphviz-dev
elif [[ "$OSTYPE" == "darwin"* ]]; then
    brew install graphviz
elif [[ "$OSTYPE" == "msys" ]] || [[ "$OSTYPE" == "cygwin" ]] || [[ -n "$WINDIR" ]]; then
    choco install graphviz -y
fi
```

**After Graphviz is installed, install pygraphviz:**
```bash
pip install pygraphviz
```

### Step 4: Analyze Source BPMN

Check if the BPMN file has existing layout coordinates:

```bash
# Check for DI coordinates
grep -q "bpmndi:BPMNDiagram" input.bpmn && echo "HAS_DI=true" || echo "HAS_DI=false"
```

Also check for complexity:
- `<bpmn:participant>` - Multiple pools
- `<bpmn:lane>` - Swimlanes present

**Layout decision:**
- If `HAS_DI=true`: Can use `--layout=preserve` (Graphviz optional)
- If `HAS_DI=false`: Must use `--layout=graphviz` (Graphviz required)

### Step 5: Run Conversion

**With Graphviz available (auto-layout):**
```bash
PYTHONPATH="$TOOL_SRC" python -m bpmn2drawio input.bpmn output.drawio
```

**Without Graphviz (preserve existing layout):**
```bash
PYTHONPATH="$TOOL_SRC" python -m bpmn2drawio input.bpmn output.drawio --layout=preserve
```

**With theme:**
```bash
PYTHONPATH="$TOOL_SRC" python -m bpmn2drawio input.bpmn output.drawio --theme=blueprint
```

**Verbose output for debugging:**
```bash
PYTHONPATH="$TOOL_SRC" python -m bpmn2drawio input.bpmn output.drawio --verbose
```

### Step 6: Validate Output

Verify the conversion succeeded:

```bash
# Check file was created and has content
ls -la output.drawio
head -30 output.drawio
```

---

## CLI Reference

### Command Syntax

```text
bpmn2drawio <input.bpmn> <output.drawio> [options]
```

### Arguments

| Argument | Required | Description |
|----------|----------|-------------|
| `input` | Yes | Input BPMN 2.0 XML file |
| `output` | Yes | Output Draw.io file path |

### Options

| Option | Values | Default | Description |
|--------|--------|---------|-------------|
| `--theme` | `default`, `blueprint`, `monochrome`, `high_contrast` | `default` | Color theme |
| `--config` | file path | — | Custom brand configuration YAML |
| `--layout` | `graphviz`, `preserve` | `graphviz` | Layout algorithm |
| `--direction` | `LR`, `TB`, `RL`, `BT` | `LR` | Flow direction |
| `--no-grid` | flag | — | Disable grid in output |
| `--page-size` | `A4`, `letter`, `auto` | `auto` | Page size |
| `-v`, `--verbose` | flag | — | Verbose output |
| `--version` | flag | — | Show version |

### Direction Options

| Value | Description | Best For |
|-------|-------------|----------|
| `LR` | Left to Right | Standard process flows |
| `TB` | Top to Bottom | Hierarchical processes |
| `RL` | Right to Left | RTL language support |
| `BT` | Bottom to Top | Reverse hierarchy |

---

## Themes

### Built-in Themes

| Theme | Description | Use Case |
|-------|-------------|----------|
| `default` | Standard BPMN colors (green start, red end, blue tasks, yellow gateways) | General use |
| `blueprint` | Professional blue monochrome | Technical documentation |
| `monochrome` | Black, white, gray | Printing, high contrast |
| `high_contrast` | Accessibility-focused | Vision accessibility |

### Custom Theme Configuration

Create a YAML configuration file for brand colors:

```yaml
# brand-config.yaml
colors:
  # Events
  start_event_fill: "#c8e6c9"
  start_event_stroke: "#2e7d32"
  end_event_fill: "#ffcdd2"
  end_event_stroke: "#c62828"

  # Tasks
  task_fill: "#e3f2fd"
  task_stroke: "#1565c0"
  user_task_fill: "#fff8e1"
  user_task_stroke: "#ff8f00"
  service_task_fill: "#f3e5f5"
  service_task_stroke: "#7b1fa2"

  # Gateways
  gateway_fill: "#fff9c4"
  gateway_stroke: "#f9a825"

  # Swimlanes
  pool_fill: "#fafafa"
  pool_stroke: "#616161"
  lane_fill: "#ffffff"
  lane_stroke: "#9e9e9e"

# Lane colors by function (pattern matching)
lane_colors:
  sales:
    patterns: ["sales", "commercial"]
    fill: "#dae8fc"
    stroke: "#6c8ebf"
  finance:
    patterns: ["finance", "billing"]
    fill: "#ffe6cc"
    stroke: "#d79b00"
  legal:
    patterns: ["legal", "compliance"]
    fill: "#d5e8d4"
    stroke: "#82b366"
```

Use with:
```bash
bpmn2drawio input.bpmn output.drawio --config=brand-config.yaml
```

---

## Dependencies

Dependencies are checked and installed automatically during the conversion workflow (Steps 2-3).

### Python Packages
- `lxml` - XML parsing
- `networkx` - Graph algorithms
- `pyyaml` - YAML configuration parsing
- `pygraphviz` - Graphviz Python bindings (requires Graphviz)

### System Dependencies
- **Graphviz** - Required for automatic layout generation
  - Not needed if BPMN file already has DI coordinates (use `--layout=preserve`)

### Manual Installation (if needed)

**Python packages:**
```bash
pip install lxml networkx pyyaml pygraphviz
```

**Graphviz:**
- Ubuntu/Debian: `sudo apt-get install graphviz libgraphviz-dev`
- macOS: `brew install graphviz`
- Windows: `choco install graphviz`

---

## Python API

For programmatic use within scripts:

```python
from bpmn2drawio import Converter, parse_bpmn, validate_model

# Simple conversion
conve