BPMN Diagram Skill

This skill converts BPMN 2.0 XML into PNG diagram images using the bpmn-js rendering toolkit.

Prerequisites

Before first use, ensure dependencies are installed:

cd ~/.claude/skills/bpmn-diagram/scripts && ./setup.sh

Or for project-local skills:

cd .claude/skills/bpmn-diagram/scripts && ./setup.sh

Usage

Input Formats

The skill accepts BPMN 2.0 XML in two ways:

1. File path: Path to an existing .bpmn or .xml file
2. Inline XML: Raw BPMN XML content provided directly

Rendering a Diagram

From a file:

node scripts/render-bpmn.js /path/to/diagram.bpmn /path/to/output.png

From inline XML:

1. First, write the BPMN XML to a temporary file
2. Then run the render script
3. The PNG will be created at the specified output path

Script Options

Option	Description	Default
--scale=N	Image scale factor (e.g., 2 for 2x resolution)	1
--min-dimensions=WxH	Minimum output dimensions in pixels	800x600

Example with options:

node scripts/render-bpmn.js input.bpmn output.png --scale=2 --min-dimensions=1200x800

Workflow

When a user requests a BPMN diagram:

1. Identify the input: Determine if XML is inline or in a file
2. Validate the XML: Check for valid BPMN 2.0 structure
   • Must have <definitions> root element with BPMN namespace
   • Should contain <bpmndi:BPMNDiagram> for visual layout
3. Prepare input file: If inline XML, write to a temp .bpmn file
4. Execute render script: Run node scripts/render-bpmn.js
5. Report result: Provide the output PNG path to the user

BPMN 2.0 XML Structure

Valid BPMN 2.0 XML must follow this structure:

<?xml version="1.0" encoding="UTF-8"?>
<definitions
    xmlns="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"
    id="Definitions_1"
    targetNamespace="http://bpmn.io/schema/bpmn">

  <!-- Process definition -->
  <process id="Process_1" isExecutable="false">
    <!-- BPMN elements: events, tasks, gateways, flows -->
  </process>

  <!-- Diagram interchange (visual layout) -->
  <bpmndi:BPMNDiagram id="BPMNDiagram_1">
    <bpmndi:BPMNPlane id="BPMNPlane_1" bpmnElement="Process_1">
      <!-- Shape and edge definitions for visual rendering -->
    </bpmndi:BPMNPlane>
  </bpmndi:BPMNDiagram>

</definitions>

Error Handling

Error	Cause	Solution
"Not valid XML"	Malformed XML syntax	Check XML structure, escape special characters
"Not BPMN 2.0 format"	Missing <definitions> root	Ensure proper BPMN namespace and root element
"No diagram layout"	Missing <bpmndi:BPMNDiagram>	Add diagram interchange section or use auto-layout
"Render failed"	Canvas/dependencies issue	Ensure setup.sh was run, check system dependencies
"File not found"	Invalid input path	Verify file path exists

Known Limitations

This skill uses a pure Node.js rendering approach with jsdom and canvas, which has some limitations compared to browser-based rendering:

1. SVG Transform Positioning: Some complex transform operations may not be perfectly positioned
2. Text Rendering: Font rendering depends on system fonts available
3. Complex Diagrams: Very large or complex diagrams may have rendering artifacts

For production use with complex diagrams, consider:

• Using bpmn-to-image with Puppeteer (requires Chrome/Chromium)
• Running the rendering in an actual browser environment

Common BPMN Elements

See references/bpmn-elements.md for a complete reference of supported BPMN 2.0 elements.

Quick Reference

Events:

• startEvent, endEvent, intermediateCatchEvent, intermediateThrowEvent

Activities:

• task, userTask, serviceTask, scriptTask, sendTask, receiveTask
• subProcess, callActivity

Gateways:

• exclusiveGateway (XOR), parallelGateway (AND), inclusiveGateway (OR)
• eventBasedGateway, complexGateway

Flows:

• sequenceFlow, messageFlow, association

Swimlanes:

• participant (Pool), lane

Example

Input (simple-process.bpmn):

<?xml version="1.0" encoding="UTF-8"?>
<definitions xmlns="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"
             id="Definitions_1">
  <process id="Process_1" isExecutable="false">
    <startEvent id="Start_1" name="Start"/>
    <task id="Task_1" name="Do Something"/>
    <endEvent id="End_1" name="End"/>
    <sequenceFlow id="Flow_1" sourceRef="Start_1" targetRef="Task_1"/>
    <sequenceFlow id="Flow_2" sourceRef="Task_1" targetRef="End_1"/>
  </process>
  <bpmndi:BPMNDiagram id="BPMNDiagram_1">
    <bpmndi:BPMNPlane id="BPMNPlane_1" bpmnElement="Process_1">
      <bpmndi:BPMNShape id="Start_1_di" bpmnElement="Start_1">
        <dc:Bounds x="152" y="102" width="36" height="36"/>
      </bpmndi:BPMNShape>
      <bpmndi:BPMNShape id="Task_1_di" bpmnElement="Task_1">
        <dc:Bounds x="240" y="80" width="100" height="80"/>
      </bpmndi:BPMNShape>
      <bpmndi:BPMNShape id="End_1_di" bpmnElement="End_1">
        <dc:Bounds x="392" y="102" width="36" height="36"/>
      </bpmndi:BPMNShape>
      <bpmndi:BPMNEdge id="Flow_1_di" bpmnElement="Flow_1">
        <di:waypoint x="188" y="120"/>
        <di:waypoint x="240" y="120"/>
      </bpmndi:BPMNEdge>
      <bpmndi:BPMNEdge id="Flow_2_di" bpmnElement="Flow_2">
        <di:waypoint x="340" y="120"/>
        <di:waypoint x="392" y="120"/>
      </bpmndi:BPMNEdge>
    </bpmndi:BPMNPlane>
  </bpmndi:BPMNDiagram>
</definitions>

Command:

node scripts/render-bpmn.js simple-process.bpmn simple-process.png

Output: simple-process.png - A PNG image of the rendered BPMN diagram