Enhance documentation and workflow management in EspoCRM

- Update README.md to include a table of contents and detailed sections on workflow management and custom scripts. - Remove deprecated 'runWorkflow' field from CVmhErstgespraech localization files. - Add 'runWorkflow' field to detail layout for CVmhErstgespraech. - Update workflow_manager.php to improve workflow listing and management functionality. - Adjust cache timestamps in config.php. - Create CUSTOM_DIRECTORY.md to outline the custom directory structure and best practices. - Add README.md for workflow definitions with usage examples and JSON format specifications. - Introduce new workflow definitions for 'vmh-erstberatung-abschließen' and its backup.
2026-01-20 23:58:29 +01:00
parent e878125489
commit 8c83e54650
12 changed files with 637 additions and 70 deletions
--- a/README.md
+++ b/README.md
@@ -1,8 +1,26 @@
 KI-basierte Bearbeitung von EspoCRM: Struktur und Funktionsweise

+## Inhaltsverzeichnis
+1. [Überblick](#überblick)
+2. [Relevante Dateipfade und Verzeichnisstruktur](#1-relevante-dateipfade-und-verzeichnisstruktur)
+3. [Workflow-Verwaltung](#workflow-verwaltung)
+4. [Auslösen von Änderungen und Rebuild-Prozess](#auslösen-von-änderungen-und-rebuild-prozess)
+
+## Überblick
+
 Unter der Annahme, dass die KI direkten Zugriff auf das Dateisystem des EspoCRM-Servers hat (z. B. via SSH, API-Integration oder lokales Scripting), kann sie EspoCRM modifizieren, indem sie JSON-basierte Metadata-Dateien bearbeitet. EspoCRM ist modular aufgebaut und speichert Konfigurationen für Entitäten, Felder, Beziehungen, Views und Layouts in diesen Dateien. Änderungen erfolgen idealerweise im custom/-Verzeichnis, um Core-Dateien nicht zu überschreiben und Upgrades zu erleichtern. Die KI würde Dateien lesen, parsen (z. B. als JSON), modifizieren und speichern – gefolgt von einem Rebuild-Prozess, um die Änderungen anzuwenden.

 EspoCRM basiert auf PHP (Backend) und Backbone.js (Frontend), mit einer rekursiven Merging-Mechanik: Custom-Dateien überschreiben oder erweitern Core-Definitionen. Keine integrierte KI-Schnittstelle existiert, aber mit Dateizugriff kann die KI automatisierte Anpassungen vornehmen, z. B. Felder hinzufügen, Views anpassen oder Beziehungen definieren. Nachfolgend detaillierte Infos basierend auf der offiziellen Dokumentation und Community-Beiträgen.
+
+### Custom Scripts & Tools
+
+**Workflow-Verwaltung:**
+- `custom/scripts/workflow_manager.php` - Zentrale Schnittstelle für Workflow-Verwaltung (Import/Export/List/Delete)
+- `custom/scripts/check_and_rebuild.sh` - Validierungs- und Rebuild-Script
+
+**Workflow-Definitionen:**
+- `custom/workflows/*.json` - Versionierte Workflow-Definitionen (Simple & BPM)
+- `custom/workflows/README.md` - Workflow-Format-Dokumentation
 1. Relevante Dateipfade und Verzeichnisstruktur

 Alle relevanten Dateien liegen im JSON-Format und werden in einer hierarchischen Struktur organisiert. Die KI sollte immer im custom/Espo/Custom/Resources/metadata/-Ordner arbeiten, da Änderungen hier persistent sind und nicht bei Updates verloren gehen. Core-Dateien (z. B. unter application/Espo/Resources/metadata/) dienen als Referenz, aber sollten nicht modifiziert werden.
@@ -148,6 +166,177 @@ JSON
        Datenbank-Effekte: Neue Felder/Links in entityDefs erzeugen Tabellen/Spalten (bei Rebuild).
        Frontend-Effekte: clientDefs/Layouts ändern UI sofort nach Rebuild (z. B. neue Panels, Views).
        Fehlerquellen: Ungültiges JSON oder falsche Typen können zu Fehlern führen (z. B. fehlende required-Felder).
+
+## Workflow-Verwaltung
+
+EspoCRM bietet zwei Arten von Workflows für Automatisierung:
+
+### Simple Workflows (Regel-basiert)
+- Trigger-basierte Workflows für einfache Automationen
+- **Trigger-Typen:** 
+  - `afterRecordSaved` - Nach Erstellen oder Aktualisieren
+  - `afterRecordCreated` - Nur nach Erstellen
+  - `afterRecordUpdated` - Nur nach Aktualisieren
+  - `manual` - Manuell ausgeführt
+  - `scheduled` - Zeitgesteuert
+- **Bedingungen:** 
+  - Vergleiche: `equals`, `notEquals`, `greaterThan`, `lessThan`, `contains`, `isEmpty`
+  - Änderungen: `changed`, `notChanged`, `wasEqual`
+- **Aktionen:** 
+  - `sendEmail` - E-Mail versenden
+  - `createEntity` - Record erstellen
+  - `updateEntity` - Record aktualisieren
+  - `relateTo` / `unrelateFrom` - Verknüpfungen
+  - `createNotification` - Benachrichtigung
+
+### BPM Flowcharts (Komplex)
+- Visuelle Workflows mit BPMN 2.0-Standard
+- Start-Events: Signal, Conditional, Timer
+- Gateways (Exclusive, Inclusive, Parallel), Tasks, End-Events
+- Für komplexe, mehrstufige Geschäftsprozesse
+
+### Workflow-Dateien
+Workflow-Definitionen werden im Ordner `custom/workflows/` als JSON abgelegt:
+- **`custom/workflows/*.json`** - Workflow-Definitionen (Simple oder BPM)
+- **`custom/workflows/README.md`** - Dokumentation zu Formaten und Verwendung
+
+### Workflow Manager Script
+**Zentrale Schnittstelle:** `custom/scripts/workflow_manager.php`
+
+Dieses Script ermöglicht die Verwaltung aller Workflows (Simple und BPM) über die Kommandozeile:
+
+#### Verfügbare Aktionen
+
+**1. Alle Workflows auflisten**
+```bash
+docker exec espocrm php /var/www/html/custom/scripts/workflow_manager.php list
+```
+Zeigt beide Workflow-Typen (BPM Flowcharts und Simple Workflows) mit Status, ID, Name und Entity.
+
+**2. Workflow-Details anzeigen**
+```bash
+docker exec espocrm php /var/www/html/custom/scripts/workflow_manager.php read <workflow-id>
+```
+Gibt alle Details eines Workflows als JSON aus.
+
+**3. Workflow importieren**
+```bash
+docker exec espocrm php /var/www/html/custom/scripts/workflow_manager.php import /var/www/html/custom/workflows/workflow.json
+```
+Importiert einen Workflow aus einer JSON-Datei. Unterstützt sowohl Simple Workflows als auch BPM Flowcharts. Erstellt automatisch eine neue ID.
+
+**4. Workflow exportieren**
+```bash
+docker exec espocrm php /var/www/html/custom/scripts/workflow_manager.php export <workflow-id> /var/www/html/custom/workflows/exported.json
+```
+Exportiert einen Workflow in eine JSON-Datei für Backup oder Migration.
+
+**5. Workflow löschen**
+```bash
+docker exec espocrm php /var/www/html/custom/scripts/workflow_manager.php delete <workflow-id>
+```
+Löscht einen Workflow (mit Bestätigung). Funktioniert für beide Workflow-Typen.
+
+### JSON-Formate
+
+#### Simple Workflow Format
+```json
+{
+    "type": "simple",
+    "name": "workflow-name",
+    "entity_type": "EntityName",
+    "trigger_type": "afterRecordSaved",
+    "is_active": true,
+    "description": "Beschreibung der Funktion",
+    "conditions_all": [
+        {
+            "comparison": "equals",
+            "fieldToCompare": "fieldName",
+            "value": "expectedValue",
+            "subjectType": "value"
+        }
+    ],
+    "conditions_any": [],
+    "conditions_formula": null,
+    "actions": [
+        {
+            "type": "sendEmail",
+            "from": "specifiedEmailAddress",
+            "fromEmailAddress": "sender@example.com",
+            "to": "targetEntity",
+            "emailTemplateId": null,
+            "doNotStore": false
+        }
+    ]
+}
+```
+
+**Wichtige Felder:**
+- `comparison` - Vergleichsoperator (siehe Bedingungen oben)
+- `fieldToCompare` - Feldname für Bedingung
+- `subjectType` - Typ des Vergleichswerts (`value`, `field`, etc.)
+- `from` / `to` - E-Mail-Empfänger (`targetEntity`, `specifiedEmailAddress`, `system`)
+
+#### BPM Flowchart Format
+```json
+{
+    "type": "bpm",
+    "name": "flowchart-name",
+    "target_type": "EntityName",
+    "is_active": true,
+    "description": "Beschreibung",
+    "data": {
+        "list": [
+            {
+                "type": "eventStartSignal",
+                "id": "start1",
+                "signalName": "@signalName"
+            }
+        ]
+    },
+    "elements_data_hash": {},
+    "event_start_all_id_list": []
+}
+```
+
+### Best Practices
+
+1. **Versionierung:** Workflows als JSON-Dateien im `custom/workflows/` Verzeichnis versionieren
+2. **Naming Convention:** Beschreibende Namen mit Präfix (z.B. `vmh-erstberatung-abschliessen.json`)
+3. **Testen:** Nach Import immer über Admin-Interface testen
+4. **Backup:** Regelmäßig Export für wichtige Workflows durchführen
+5. **Dokumentation:** Description-Feld aussagekräftig füllen
+
+### Beispiel-Workflows
+
+**`custom/workflows/vmh-erstberatung-abschliessen.json`**
+- Sendet E-Mail bei Status-Wechsel zu "Warte auf Mandatierung"
+- Trigger: afterRecordSaved
+- Bedingungen: Status = "Warte auf Mandatierung" UND Status hat sich geändert
+- Aktion: E-Mail an targetEntity senden
+
+**Anwendungsbeispiel:**
+```bash
+# Alle Workflows exportieren (Backup)
+docker exec espocrm php /var/www/html/custom/scripts/workflow_manager.php list | grep ID | \
+  awk '{print $3}' | while read id; do
+    docker exec espocrm php /var/www/html/custom/scripts/workflow_manager.php export "${id%,}" \
+      "/var/www/html/custom/workflows/backup-${id%,}.json"
+done
+
+# Workflow aus Datei (re-)importieren
+docker exec espocrm php /var/www/html/custom/scripts/workflow_manager.php import \
+  /var/www/html/custom/workflows/vmh-erstberatung-abschliessen.json
+```
+
+### Workflow-Entwicklung mit KI
+
+Für KI-gestützte Workflow-Erstellung:
+1. Workflow-Definition im `custom/workflows/` Verzeichnis als JSON ablegen
+2. Mit `import` Befehl in EspoCRM einspielen
+3. Im Admin-Interface testen und bei Bedarf anpassen
+4. Mit `export` Befehl aktualisierten Workflow sichern
+5. JSON-Datei im Repository committen
    Rebuild auslösen:
        Manuell: Administration > Clear Cache & Rebuild (löscht Caches und merged Metadata neu).
        Programmatisch (für KI): Die KI kann den Cache-Ordner löschen (data/cache/) oder ein PHP-Skript ausführen, das den Rebuild triggert (z. B. via EspoCRMs CLI: php command.php Rebuild). Keine direkte API, aber machbar mit Dateizugriff (z. B. exec("php rebuild.php")).