Projektwissen/.agents/skills/sn-bpmn/Anleitung.md

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

python .agents/skills/sn-bpmn/md_to_bpmn.py <prozess.md> <ausgabe.bpmn>

Beispiel (aus dem Workspace-Root):

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:

python scripts/vorschau.py entwuerfe/<name>.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: <Name des Prozesses>

Schritte

Jeder Schritt ist eine Zeile der Form:

<ID> <Typ>: <Beschriftung>

• 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: <Start|Zwischenereignis|Ende> <Kind>: <Beschriftung>. Mögliche <Kind>-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 ~> <Name> einen ausgehenden, <~ <Name> 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.

Der Konverter zeichnet Nachrichtenflüsse senkrecht vom Schritt hinunter zum externen Pool. Steht darunter ein anderes Element, weicht der Fluss vorher in einen freien Gang aus (mit Lanes neben der Spalte, ohne Lanes rechts neben dem Diagramm).

Verzweigungen / Sprünge

Unter einem Schritt können beliebig viele Pfeil-Zeilen stehen:

S3 Gateway XOR: Antrag vollständig?
  Ja -> S4
  Nein -> S3a

• <Bezeichnung> -> <Ziel-ID> – beschriftete Kante (z. B. für Ja/Nein-Zweige)
• -> <Ziel-ID> – 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 an allen Elementen vorbei zurückgeführt: mit Lanes über einen Kanal am Boden des eigenen Pools, ohne Lanes seitlich am Diagramm.

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.