# Markdown → BPMN 2.0 für PICTURE `md_to_bpmn.py` wandelt eine einfache textuelle Prozessbeschreibung (`.md`) in eine standardkonforme BPMN-2.0-XML-Datei um, die sich über den BPMN-Import in PICTURE laden lässt. BPMN 2.0 ist ein offener, seit 2011 stabiler OMG-Standard – das Skript muss dafür kein PICTURE-internes Schema "lernen" und erzeugt keine PICTURE-spezifischen UUIDs. ## Empfohlener Arbeitsablauf bei unstrukturiertem Ausgangstext 1. Rohtext (Fließtext, Stichpunkte, Sitzungsnotizen o. ä.) bereitstellen. 2. Daraus wird eine strukturierte Arbeitsschritt-`.md` in der unten beschriebenen Syntax abgeleitet und zur Prüfung vorgelegt. 3. Fachlich prüfen und in der `.md` direkt anpassen (Reihenfolge, Verzweigungen, Verantwortliche, Formulierungen) – dabei gegen `Modellierregeln.md` abgleichen. 4. Aus der freigegebenen `.md` die BPMN-2.0-Datei erzeugen und in PICTURE importieren. Schritt 2 erfordert Interpretation von Fließtext und ist kein rein mechanischer Schritt – die Qualität hängt von der Klarheit der Quelle und der fachlichen Prüfung in Schritt 3 ab. Die fachlichen BPMN-Modellierregeln stehen in `Modellierregeln.md`. ## Aufruf ```bash python .agents/skills/sn-bpmn/md_to_bpmn.py ``` Beispiel (aus dem Workspace-Root): ```bash python .agents/skills/sn-bpmn/md_to_bpmn.py entwuerfe/antrag-pruefen.md entwuerfe/antrag-pruefen.bpmn ``` Versionierte Modelle in der Prozessbibliothek werden nicht einzeln, sondern gesammelt erzeugt: `python scripts/pruefe_prozesse.py --erzeugen` (siehe `docs/leitfaden/08_prozessbibliothek.md`). Die erzeugte `.bpmn`-Datei kann anschließend über den BPMN-Import-Dialog in PICTURE geladen werden. ### Diagramm vorab prüfen, ohne PICTURE Um zu prüfen, ob `md_to_bpmn.py` selbst korrekt gerechnet hat (Struktur, Anschlusspunkte, Layout) – unabhängig davon, was ein Import-Werkzeug daraus macht – eignet sich ein originalgetreuer BPMN-Viewer. Im Repository liegt einer, offline und ohne Datenübertragung: ```bash python scripts/vorschau.py entwuerfe/.md # oder eine .bpmn ``` Ohne Python: `werkzeuge/vorschau/vorschau.html` im Browser öffnen und die `.bpmn` hineinziehen (Details: `werkzeuge/vorschau/README.md`). Alternativ: - **`demo.bpmn.io`** – im Browser, kein Install nötig: `.bpmn`-Datei per Drag & Drop reinziehen. - **Camunda Modeler** – kostenlose Desktop-App, gleiche Rendering-Engine wie bpmn.io, auch offline. Beide übernehmen importierte Anschlusspunkte originalgetreu, statt sie neu zu berechnen. ## Markdown-Syntax ### Kopfzeile (optional, vor dem ersten Schritt) ``` Prozess: ``` ### Schritte Jeder Schritt ist eine Zeile der Form: ``` : ``` - **ID**: ein kurzes, eindeutiges Kürzel ohne Leerzeichen (z. B. `S1`, `3.3`, `A`) - **Typ** (Groß-/Kleinschreibung egal): | Schreibweise im .md | Erzeugtes BPMN-Element | |--------------------------------------|-------------------------------------| | `Start` | Start-Ereignis | | `Ende` / `End` | End-Ereignis | | `Zwischenereignis` / `Intermediate` | Zwischen-Ereignis (Catch) | | `Task` / `Aufgabe` | Aufgabe (Task) | | `Manuelle Aufgabe` | Manuelle Aufgabe | | `User Aufgabe` | User-Aufgabe | | `Service Aufgabe` | Service-Aufgabe | | `Script Aufgabe` | Script-Aufgabe | | `Geschäftsregel Aufgabe` | Geschäftsregel-Aufgabe | | `Sendeaufgabe` | Aufgabe (sendend) | | `Empfangsaufgabe` | Aufgabe (empfangend) | | `Teilprozess` / `Subprocess` | Geschlossener Teilprozess | | `Aufruf` | Aufruf-Element (Call Activity) | | `Gateway XOR` | Exklusives Gateway (XOR) | | `Gateway OR` / `Gateway ODER` | Inklusives Gateway (OR) | | `Gateway AND` / `Gateway UND` | Paralleles Gateway (AND) | | `Gateway Ereignisbasiert` | Ereignisbasiertes Gateway | | `Hinweis` / `Note` | Textuelle Anmerkung (unverbunden) | | `Datenobjekt` | Datenobjekt (unverbunden) | | `Datenspeicher` | Datenspeicher (unverbunden) | | `Gruppe` | Gruppe (unverbunden) | Vollständige Liste inkl. Bedeutung: `Elementkatalog.md`. ### Typisierte Ereignisse Start-, Zwischen- und Endereignisse können ein zweites Wort für die Art des Ereignisses bekommen: ` : `. Mögliche ``-Wörter: `Nachricht`, `Zeit`, `Eskalation`, `Bedingung`, `Link`, `Fehler`, `Signal`, `Terminierung`. Details und Einschränkungen (z. B. `Terminierung` nur als Endereignis, `Link` nur als Zwischenereignis) stehen in `Elementkatalog.md` und `Modellierregeln.md`. ``` S1 Start Nachricht: Antrag geht ein S9 Zwischenereignis Zeit: 14 Tage Frist abwarten S17 Ende Terminierung: Verfahren beendet ``` Ein Zwischenereignis ist standardmäßig empfangend (Catch); mit einem zusätzlichen dritten Wort `sendend` wird daraus ein auslösendes (Throw-) Ereignis, z. B. `S2 Zwischenereignis Nachricht sendend: Status melden`. ### Geschlossene Pools und Nachrichtenflüsse Externe Beteiligte (Bürger, andere Behörden, …), mit denen nur Nachrichten ausgetauscht werden, vor dem ersten Schritt deklarieren: ``` Extern: Bürger Extern: Landratsamt ``` Unter einem Schritt erzeugt `~> ` einen ausgehenden, `<~ ` einen eingehenden Nachrichtenfluss zu einem so deklarierten Beteiligten: ``` S8 Sendeaufgabe: Bescheid versenden ~> Bürger -> S9 ``` Nachrichtenflüsse sind nur zwischen Pools erlaubt (siehe `Modellierregeln.md`) – das Ziel muss immer ein per `Extern:` deklarierter Name sein, nie eine Schritt-ID im selben Pool. ### Verzweigungen / Sprünge Unter einem Schritt können beliebig viele Pfeil-Zeilen stehen: ``` S3 Gateway XOR: Antrag vollständig? Ja -> S4 Nein -> S3a ``` - ` -> ` – beschriftete Kante (z. B. für Ja/Nein-Zweige) - `-> ` – unbeschriftete Kante (z. B. für parallele AND-Zweige oder einfache Weiterleitung) **Wichtig:** Wenn ein Schritt **keine** Pfeil-Zeile hat, wird automatisch eine Kante zum **nächsten Schritt in der Datei** erzeugt. Ihr müsst also nur dort explizite Pfeile setzen, wo der Ablauf von der reinen Lesereihenfolge abweicht (Verzweigung, Sprung zurück, Zusammenführung). Rücksprünge (Schleifen, z. B. „Nachforderung" zurück zur Prüfung) werden automatisch erkannt und am Rand des Diagramms herumgeführt. ### Verantwortliche / Swimlanes Schreibt ihr am Anfang der Beschriftung eines Schritts einen kurzen Namen gefolgt von einem Doppelpunkt, wird dieser als **Verantwortlicher** erkannt und daraus automatisch eine Swimlane gemacht: ``` V1 Task: Flurneuordnung: Gewannenkonzept festlegen O3 Task: ÖbVI: Waldgrenzen verhandeln O9 Task: LRA: Aufmessung im Ortstermin ``` Aus den drei unterschiedlichen Verantwortlichen entstehen drei Lanes in einem Pool; Schritte ohne Verantwortlichen-Angabe landen gesammelt in einer Lane „Nicht zugeordnet". Ohne jede Verantwortlichen-Angabe entsteht wie bisher ein Diagramm ohne Lanes. Das ist eine Heuristik: Ein Doppelpunkt weit vorn in einer kurzen Beschriftung (max. 30 Zeichen, max. 4 Wörter, kein „?") wird als Verantwortlicher gedeutet. Enthält eine Beschriftung an dieser Stelle zufällig einen Doppelpunkt, der keine Zuständigkeit meint, entsprechend umformulieren. ### Vollständige Beispiele In `beispiele/` neben dieser Datei, reine Syntaxbeispiele (fachlich nicht geprüft): - Ohne Lanes: `beispiele/beispiel_prozess.md` / `beispiele/beispiel_prozess.bpmn` - Mit Lanes und externem Beteiligten: `beispiele/beispiel_lanes.md` / `beispiele/beispiel_lanes.bpmn` Referenzmodell (Test) – ein echter, größerer Prozess, gegen den Änderungen am Konverter geprüft werden (Byte-Vergleich plus Strukturtests in `tests/test_referenzmodelle.py`; die Prüfung „keine Kante durch ein Element“ läuft auch über die Syntaxbeispiele): - `beispiele/referenz_gewannenfestlegung.md` / `.bpmn` – 4 Lanes, externer Pool, 14 Gateways, verschachtelte Varianten; fachlich nicht abgenommen Ein Test hält die `.bpmn` der Beispiele aktuell; nach einer Änderung am Konverter `python scripts/pruefe_prozesse.py --erzeugen` ausführen. ## Einschränkungen der aktuellen Version - Es wird pro `.md`-Datei **ein** Diagramm (ein Prozess) erzeugt, keine mehrstufigen Prozessnetze mit verknüpften Teilprozess-Diagrammen. - `Teilprozess` (geschlossener Teilprozess) und `Aufruf` (Aufruf-Element) werden als Bausteine angelegt, aber **ohne** Inhalt bzw. **ohne** Verknüpfung zu einem Ziel-Prozess – Details bzw. Verknüpfung lassen sich in PICTURE nach dem Import nachtragen. Der **aufgeklappte** Teilprozess (Inhalt inline im selben Diagramm) wird noch nicht unterstützt. - Wiederholungs-Marker (Schleife, Multi-Instanz sequenziell/parallel) werden noch nicht unterstützt; bei Bedarf als `Hinweis` an der betroffenen Aktivität dokumentieren. - Assoziationen (gepunktete Linien) von Datenobjekten/-speichern zu Aktivitäten werden nicht automatisch gezeichnet; Datenobjekt/-speicher landen unverbunden im Diagramm und werden nach dem Import in PICTURE bei Bedarf manuell mit den betroffenen Aktivitäten verbunden. - Das automatische Layout ist ein einfacher Schichten-Algorithmus (ähnlich den meisten BPMN-Auto-Layouts) – bei komplexen Prozessen lohnt sich nach dem Import ein manuelles Nachjustieren einzelner Boxen und Beschriftungen. Das gilt besonders für geschlossene Pools (externe Beteiligte): Sie werden schlicht unterhalb des Hauptpools gestapelt. - Jede Kante bekommt in der erzeugten `.bpmn`-Datei einen eigenen Anschlusspunkt (Modellierregel 4, in `Modellierregeln.md`) statt eines gemeinsamen Mittelpunkts. Bei Task/Ereignis/Datenobjekt usw. werden dazu mehrere Punkte über die tatsächliche Kontur verteilt (Rechteckkante bzw. Kreisbogen). **Ein Gateway bekommt dagegen nur einen der vier festen PICTURE-Eckpunkte (0°/90°/180°/270°) je Kante**, nie einen Punkt dazwischen auf der Rautenkante – mehr als vier Kanten an einem Gateway (eingehend plus ausgehend) können sich damit nicht mehr eindeutig darstellen lassen, siehe Modellierregel 4. Wirkt das Ergebnis in einem Anzeige-Werkzeug trotzdem so, als würden Verzweigungen an einem Punkt zusammenlaufen, zuerst in einem originalgetreuen BPMN-Viewer (z. B. `demo.bpmn.io`, siehe unten) prüfen: Ein Viewer, der importierte Anschlusspunkte respektiert statt sie neu zu berechnen, zeigt die verteilten Punkte korrekt an. - Der BPMN-Import in PICTURE übernimmt die reine Ablaufstruktur zuverlässig; PICTURE-/FIM-spezifische Zusatzfelder (Fallzahl, Bearbeitungszeit, RACI usw.) sind kein Teil des BPMN-Standards und müssten nach dem Import ergänzt werden.