Generate BPMN (Business Process Model and Notation) diagrams in Modelio using AI. Describe your business process in plain language and get a complete, runnable Modelio macro.

This project enables you to:

• Describe a business process in plain language and have Claude, ChatGPT, or Gemini generate the Modelio macro
• Automatically create BPMN diagrams with lanes, tasks, gateways, data objects, and flows
• Customize layout with configurable spacing, task dimensions, and positioning

• ✅ Support for all common BPMN elements (Start/End Events, User/Service/Manual Tasks, Gateways)
• ✅ Data Objects with input/output associations to tasks
• ✅ Automatic swim lane creation and element positioning
• ✅ Sequence flows with labels for gateway decisions
• ✅ Configurable task dimensions and spacing
• ✅ Robust element unmasking with fallback mechanisms
• ✅ Two-file architecture for faster, more reliable AI generation
• ✅ NEW: Auto-stacking - Same lane + same column elements automatically stacked (v3.2)
• ✅ Export/Import - Clone or migrate existing diagrams between projects
• ✅ Extended element types - Script, Business Rule, Send/Receive tasks, additional gateways and events

• Modelio 5.0 or later
• Access to Claude, ChatGPT with GPT-4o, or Gemini
• Also works with Qwen via LM Studio—see the guide here

Copy BPMN_Helpers.py to your Modelio macros folder:

Replace 5.4 with your Modelio version. Create the macros folder if it doesn't exist.

Copy the contents of CLAUDE_INSTRUCTIONS.md into:

Tip for ChatGPT/Gemini: Start with: "You are generating Modelio Jython BPMN macros. Follow these instructions exactly."

Tell the AI what you need:

Create a BPMN diagram for an expense approval process with 3 lanes: 
Employee, Manager, and Finance. 

The employee submits an expense report, the manager reviews and 
approves or rejects it, and finance processes the payment.

1. Copy the generated Python script
2. Open Modelio and select a Package in the model explorer
3. Go to Views → Script
4. Paste the script and click Run

Your BPMN diagram will appear automatically!

Modelio-Automation/
├── README.md                 # This file
├── BPMN_Helpers.py           # Helper library (install to Modelio)
├── BPMN_Export.py            # Export macro (install to Modelio) - NEW in v3.x
├── CLAUDE_INSTRUCTIONS.md    # AI instructions for macro generation
├── docs/
│   ├── QUICK_START.md        # Detailed setup guide
│   ├── API_REFERENCE.md      # Configuration options
│   ├── APPROACHES.md         # Architecture comparison
│   └── images/
├── examples/
│   └── ExpenseApprovalProcess.py
├── lm_studio/
│    └── LMStudio_Qwen_Guide_with_helpers.md
└── v1/                       # Previous single-file version with examples

┌────────────────────────────────┐
│  BPMN_Helpers.py               │  ← Install once in Modelio
│  (500+ lines of tested code)   │
└────────────────────────────────┘
              ▲
              │ execfile()
              │
┌────────────────────────────────┐
│  YourProcess.py                │  ← AI generates this (~100 lines)
│  (Pure configuration)          │
└────────────────────────────────┘

Benefits:

• ⚡ Fast generation - AI only generates configuration, not 500+ lines of helpers
• ✅ Reliable - Helper code is tested; only config varies
• 🔧 Maintainable - Fix bugs once in helper library
• 📖 Readable - Process structure is clear and declarative

CONFIG = {
    "name": "ExpenseApproval",
    "lanes": ["Employee", "Manager", "Finance"],
    "elements": [
        ("Submit Expense", START, "Employee"),
        ("Review", USER_TASK, "Manager"),
        ("Approved?", EXCLUSIVE_GW, "Manager"),
        ("Process Payment", SERVICE_TASK, "Finance"),
        ("Rejected", END, "Manager"),
        # ...
    ],
    "flows": [
        ("Submit Expense", "Review", ""),
        ("Approved?", "Process Payment", "Yes"),
        ("Approved?", "Rejected", "No"),
    ],
    "layout": {
        "Submit Expense": 0,
        "Review": 1,
        "Approved?": 2,
        "Process Payment": 3,    # Same column = auto-stacked (v3.2)
        "Rejected": 3,           # Automatically 90px below
        # ...
    },
    # Optional: Data Objects
    "data_objects": [
        ("Expense Report", "Employee", 0),
    ],
    "data_associations": [
        ("Submit Expense", "Expense Report"),
        ("Expense Report", "Review"),
    ],
}

When a BPMN diagram is created, Modelio automatically "unmasks" elements. However:

• Auto-unmask is non-deterministic - sometimes all elements appear, sometimes only some
• The helper library handles this with automatic fallback to manual unmasking
• Manual unmask is done at the correct Y position inside each lane

CONFIG = {
    # Required
    "name": "ProcessName",
    "lanes": [...],
    "elements": [...],
    "flows": [...],
    "layout": {...},
    
    # Optional - Data Objects (v2.1+)
    "data_objects": [...],      # List of (name, lane, column)
    "data_associations": [...], # List of (source, target)
    
    # Optional - Layout Settings (with defaults)
    "SPACING": 150,        # Horizontal spacing between columns
    "START_X": 80,         # Starting X position
    "TASK_WIDTH": 120,     # Width for task elements
    "TASK_HEIGHT": 60,     # Height for task elements
    "DATA_WIDTH": 40,      # Width for data objects
    "DATA_HEIGHT": 50,     # Height for data objects
    "DATA_OFFSET_X": 90,   # Data object X offset (near right side of task)
    "DATA_OFFSET_Y": 10,   # Data object Y gap below source task
    "WAIT_TIME_MS": 50,    # Time between unmask attempts
    "MAX_ATTEMPTS": 3,     # Maximum unmask attempts
}

# Format: (name, lane, column)
"data_objects": [
    ("Draft Document", "Author", 1),
    ("Final Report", "Reviewer", 3),
]

# Format: (source, target) - direction is auto-detected
"data_associations": [
    ("Write Document", "Draft Document"),  # Task → Data (task produces data)
    ("Draft Document", "Review Task"),     # Data → Task (task consumes data)
]

Running the ExpenseApprovalProcess example produces:

==================================================================
BPMN PROCESS CREATION
==================================================================
Process Name: ExpenseApproval_83950

== PHASE 1: CREATE PROCESS & LANES ==============================
[1] Process: ExpenseApproval_83950
[2] Lanes: Employee, Manager, Finance

== PHASE 2: CREATE ELEMENTS =====================================
[3] Employee: 7 elements
[4] Manager: 5 elements
[5] Finance: 7 elements
  Total: 19 elements

== PHASE 4: WAIT FOR AUTO-UNMASK ================================
  [Attempt 1] Found: 7/19 | Missing: Review Expense...
  [Unmask] Review Expense -> Y=161 (Manager): OK
  ...

== PHASE 5: REPOSITION ELEMENTS =================================
  Repositioned: 19/19

== PHASE 6: CREATE FLOWS ========================================
  Created 20 sequence flows

== PHASE 7: CREATE DATA OBJECTS =================================
  Created 2 data objects

== PHASE 8: CREATE DATA ASSOCIATIONS ============================
  Created 4 data associations

==================================================================
COMPLETE
==================================================================

• Quick Start Guide - Detailed setup walkthrough
• API Reference - All configuration options
• Approaches Comparison - Architecture details

Contributions are welcome! Please feel free to submit issues and pull requests.

• Modelio - Open source modeling environment
• Anthropic Claude - AI assistant for code generation
• Modelio development team for insights on auto-unmask behavior
• MATISSE - Project co-funded by the European Union under the Key Digital Technologies Joint Undertaking and participating national authorities (Grant Agreement ID: 101140216)

• v3.2 (Dec 2025) - Auto-stacking for same-lane/same-column elements (90px spacing)
• v3.1 (Dec 2025) - Fixed data association export, Y-offset layout support, data objects below source task
• v3.0 (Dec 2025) - Export/Import feature, lane-relative positioning, extended element types
• v2.5 (Dec 2025) - Clarified BPMN rules - Events CAN have data associations, Gateways CANNOT
• v2.4 (Dec 2025) - Simplified data objects by removing position parameter (always below)
• v2.3 (Dec 2025) - Simplified data associations by auto-detecting direction
• v2.2 (Dec 2025) - Fixed Data Association semantics, lane-by-lane data object positioning
• v2.1 (Dec 2025) - Added Data Objects and Data Associations support
• v2.0 (Dec 2025) - Two-file architecture with helper library
• v1.0 (Dec 2025) - Single-file approach with inline helpers

• v0.9.1 - Guards for gateway conditions
• v0.9.0 - Configurable task dimensions
• v0.8.3 - Manual unmask inside correct lane Y position
• v0.8.0 - Auto-unmask discovery and waiting mechanism

Apache License 2.0 - See LICENSE