KI-basierte Bearbeitung von EspoCRM: Struktur und Funktionsweise

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.
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.

    Hauptverzeichnis für Customizations: custom/Espo/Custom/Resources/
        Unterordner: metadata/ (für Definitionsdateien wie entityDefs, clientDefs).
        Weitere Unterordner: layouts/ (für UI-Layouts), i18n/ (für Übersetzungen, falls relevant).
    Spezifische Dateitypen und Pfade:
        entityDefs/{EntityType}.json: Definiert Entitäten (z. B. Account, Contact oder custom wie Project). Pfad: custom/Espo/Custom/Resources/metadata/entityDefs/Account.json.
            Kontrolliert: Felder, Beziehungen (Links), Indizes, Collections (z. B. Sortierung in Listen).
        clientDefs/{EntityType}.json: Definiert Frontend-Konfigurationen für Entitäten. Pfad: custom/Espo/Custom/Resources/metadata/clientDefs/Account.json.
            Kontrolliert: Views (z. B. Edit-View), Controller, Modelle, Setup-Handler für dynamische UI-Anpassungen.
        layouts/{EntityType}/{LayoutType}.json: Definiert UI-Layouts (z. B. Detail-View, List-View). Pfad: custom/Espo/Custom/Resources/layouts/Account/detail.json.
            LayoutTypes: detail, list, edit, kanban, etc.
        fields/{FieldType}.json: Globale Feld-Definitionen (z. B. für Address oder Phone). Pfad: custom/Espo/Custom/Resources/metadata/fields/address.json.
            Kontrolliert: Feldtypen, Views für spezifische Felder (z. B. custom View für Phone mit Click-to-Call).
        scopes/{EntityType}.json: Definiert Entity-Scopes (z. B. ob eine Entität importierbar ist). Pfad: custom/Espo/Custom/Resources/metadata/scopes/Project.json.
        Andere (weniger häufig): aclDefs/ für Zugriffsrechte, selectDefs/ für Filter, recordDefs/ für Record-spezifische Logik.

Falls die KI ein neues Modul erstellt: custom/Espo/Modules/{ModuleName}/Resources/metadata/ – ähnliche Struktur, aber modular getrennt.
docs.espocrm.com
2. Dateiformate und JSON-Strukturen

Alle Dateien sind im JSON-Format. Die KI muss gültiges JSON parsen und schreiben (z. B. mit Bibliotheken wie json in Python). Strukturen sind hierarchisch: Objekte für Felder/Links, Arrays für Optionen/Listen.

    entityDefs/{EntityType}.json (Format-Beispiel für eine Entität wie Account):
    JSON

{
  "fields": {
    "name": {
      "type": "varchar",
      "required": true,
      "len": 255
    },
    "status": {
      "type": "enum",
      "options": ["Active", "Inactive"],
      "default": "Active"
    },
    "employeeCount": {
      "type": "int"
    }
  },
  "links": {
    "account": {
      "type": "belongsTo",
      "entity": "Account",
      "foreign": "projects"
    },
    "teams": {
      "type": "hasMany",
      "entity": "Team",
      "relationName": "EntityTeam"
    }
  },
  "collection": {
    "sortBy": "createdAt",
    "asc": false,
    "boolFilters": ["onlyMy"]
  },
  "indexes": {
    "name": {
      "columns": ["name"]
    }
  }
}

    Felder (fields): Schlüssel = Feldname, Wert = Objekt mit type (z. B. varchar, enum, link), required (bool), options (Array für Enums), etc.
    Links: Beziehungen (belongsTo für 1:1, hasMany für 1:N, etc.).
    Collection: Für Listen-Views (Sortierung, Filter).
    Auslösen: Hinzufügen eines Felds triggert bei Rebuild eine Datenbankänderung (neue Spalte in der Tabelle). Beziehungen erstellen Middle-Tables bei Many-to-Many.
    **WICHTIG - Bidirektionale Relationships**: Bei hasMany-Relationships (z. B. viele Contacts zu einer Entität) müssen **beide Seiten** definiert werden:
        - In Entität A: Link mit `relationName` und `foreign` (zeigt auf Link-Namen in Entität B)
        - In Entität B (z. B. Contact): Link mit **derselben** `relationName` und `foreign` (zeigt auf Link-Namen in Entität A)
        - Beispiel: `CVmhMietverhltnis` hat Link `contactsMietverhltnis` mit relationName `cVmhMietverhltnisContact`; `Contact` hat Link `cVmhMietverhltnisesContact` mit derselben relationName und foreign `contactsMietverhltnis`.
        - Fehlt eine Seite, gibt EspoCRM 404-Fehler "Link does not exist" zurück.
    docs.espocrm.com

clientDefs/{EntityType}.json (Format-Beispiel):
JSON

{
  "controller": "controllers/record",
  "collection": "collection",
  "model": "model",
  "views": {
    "list": "views/record/list",
    "detail": "views/record/detail",
    "edit": "views/record/edit"
  },
  "recordViews": {
    "list": "views/record/list",
    "kanban": "custom:views/record/kanban"
  },
  "viewSetupHandlers": {
    "record/detail": ["custom:handlers/my-detail-handler"]
  }
}

    Views/RecordViews: Pfade zu JS-Views (z. B. "custom:views/account/detail" für custom View).
    ViewSetupHandlers: Arrays von Handlern für dynamische Anpassungen (z. B. Feld-Updates).
    Auslösen: Ändert Frontend-Rendering (z. B. neue View-Modi wie Kanban).
    forum.espocrm.com

layouts/{EntityType}/detail.json (Format-Beispiel für Detail-View):
JSON

[
  {
    "label": "Overview",
    "rows": [
      [
        {"name": "name"},
        {"name": "assignedUser"}
      ],
      [
        {"name": "description"}
      ]
    ]
  },
  {
    "label": "Details",
    "rows": [
      [{"name": "createdAt"}]
    ]
  }
]

    Arrays von Panels (Objekte mit label und rows), rows sind Arrays von Zellen (Objekte mit name für Felder).
    Auslösen: Ändert Feldanordnung in Views; unterstützt Parameter wie width, notSortable.
    docs.espocrm.com

    Spezielle Features:
        APPEND: In Arrays als erstes Element einfügen, um bestehende Werte zu erweitern (z. B. options: ["APPEND", "NewOption"]).
        layoutAvailabilityList: Array für Feld-Sichtbarkeit in Layouts (z. B. ["list", "detail"]).
        layoutIgnoreList: Zu ignorierende Layouts.

3. Auslösen von Änderungen und Rebuild-Prozess

    Was Änderungen auslösen:
        Datei-Änderungen: Werden bei Merging berücksichtigt – rekursiv, also überschreiben Customs Core.
        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).
    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")).
        Effekt: Mergt alle Metadata, aktualisiert DB-Schema, cached Views. Ohne Rebuild bleiben Änderungen unsichtbar.
        docs.espocrm.com

4. Best Practices für KI-Implementation

    Workflow: 1. Datei lesen/parsen. 2. Modifizieren (z. B. Feld hinzufügen). 3. Validieren (JSON-Schema prüfen). 4. Speichern. 5. Rebuild triggern.
    Sicherheit: Backups erstellen, Änderungen loggen. Vermeide Core-Änderungen.
    Automatisierung: KI könnte Skripte generieren (z. B. Python mit json und os für Dateizugriff) oder direkt integriert werden (z. B. in einem Custom-Modul mit PHP-Aufrufen).
    Grenzen: Keine out-of-the-box Automatisierung in Docs; Community erwähnt Skripte für Massen-Edits, aber nichts KI-spezifisch.

5. Projektziele und Zukunftsvision: "Vermieterhelden"

Das Projekt "Vermieterhelden" ist ein maßgeschneidertes Backend-System auf Basis von EspoCRM für eine Anwaltskanzlei, spezialisiert auf die Durchführung und Verwaltung von immobilienrechtlichen Klagen (z. B. Räumungsklagen, Mietinkasso). Der aktuelle Fokus liegt auf der strukturierten Verwaltung von Stammdaten (Entitäten wie Mietverhältnisse, Mietobjekte, Beteiligte, Dokumente und Klagen) und der Abbildung von rechtlichen Workflows (z. B. automatisierte Tasks bei Statusänderungen, Fristen-Überwachung).

Zukünftige Ziele:
- **Customer Portal**: Integration eines Mandanten-Portals, damit Klienten (Mieter/Vermieter) selbst auf relevante Daten zugreifen können (z. B. Status von Klagen, Dokumente hochladen). Dies nutzt EspoCRMs eingebaute Portal-Funktionalität für Self-Service.
- **KI-Integration über Middleware**: Automatisierung von Prozessen via Webhooks und externer Middleware. Beispiele:
  - Automatische Analyse von Dokumenten (z. B. Verträge scannen und Felder extrahieren).
  - Intelligente Fristen-Erinnerungen basierend auf rechtlichen Regeln (z. B. Kündigungsfristen berechnen).
  - Workflow-Optimierung (z. B. Vorschläge für nächste Schritte in Klage-Prozessen).
  - Die KI soll über APIs/Webhooks angebunden werden, ohne EspoCRMs Core zu modifizieren, um Stabilität zu wahren.
- **Erweiterte Features**: Mehrsprachigkeit, Mandanten-Isolation für mehrere Kanzlei-Teams, Integration mit externen Systemen (z. B. Gerichts-APIs, Buchhaltung).

Die KI kann diese Ziele unterstützen, indem sie JSON-Strukturen analysiert, Änderungen vorschlägt (z. B. neue Felder für Compliance) und Workflows modelliert. Das System soll skalierbar und benutzerfreundlich sein, um die Effizienz in der Rechtsbranche zu steigern.

6. Bearbeitung von Entitäten und Layouts

Um EspoCRM anzupassen, bearbeite JSON-Dateien im custom/-Verzeichnis. Änderungen bleiben bei Updates erhalten, da sie Core-Dateien nicht überschreiben.

    Entitäten bearbeiten:
        Pfad: custom/Espo/Custom/Resources/metadata/entityDefs/{EntityType}.json (z. B. CVmhErstgespraech.json).
        Struktur: JSON-Objekt mit "fields" (Felder definieren), "links" (Beziehungen), "collection" (Sortierung/Filter), "indexes" (Performance).
        Beispiel: Feld hinzufügen – Füge in "fields" ein neues Objekt ein, z. B. {"type": "varchar", "required": true}.
        Beispiel: Feld entfernen – Lösche den entsprechenden Schlüssel aus "fields".
        Hinweis: Änderungen wirken sich auf die Datenbank aus (z. B. neue Spalten bei Rebuild).

    Layouts bearbeiten:
        Pfad: custom/Espo/Custom/Resources/layouts/{EntityType}/{LayoutType}.json (z. B. detail.json für Detail-View).
        Struktur: Array von Panels, jedes mit "label" und "rows" (Arrays von Zellen mit {"name": "feldname"}).
        Beispiel: Feld hinzufügen – Füge {"name": "neuesFeld"} in eine "rows"-Zeile ein.
        Beispiel: Feld entfernen – Lösche die entsprechende Zelle aus "rows".
        LayoutTypes: detail, list, edit, etc. – Passe Views an, um UI zu optimieren.

    Rebuild durchführen:
        Nach Änderungen muss ein Rebuild ausgeführt werden, um Caches zu leeren und Metadata neu zu mergen.
        CLI-Befehl (im Docker-Container): docker exec espocrm php /var/www/html/command.php Rebuild
        Alternative: Web-Interface > Administration > Clear Cache & Rebuild.

7. Panel-Labels und Übersetzungen

Um Relationship-Panels und Links korrekt zu beschriften, müssen Labels in den i18n-Sprachdateien definiert werden.

    **Wichtig - Labels in allen Sprachen definieren**:
        - Labels müssen in **allen installierten Sprachen** definiert werden (z. B. de_DE UND en_US)
        - Fehlende Labels in einer Sprache können dazu führen, dass die Beschriftung nicht funktioniert
        - Selbst wenn die Hauptsprache de_DE ist, sollten en_US Labels immer mit definiert werden

    **Labels müssen in zwei Sektionen stehen**:
        - `fields`: Für die Anzeige als Feld
        - `links`: Für die Anzeige in Relationship-Panels
        - Beide Sektionen müssen identische Werte haben

    Pfade:
        - `custom/Espo/Custom/Resources/i18n/de_DE/{EntityType}.json` (deutsch)
        - `custom/Espo/Custom/Resources/i18n/en_US/{EntityType}.json` (englisch)

    Struktur (Beispiel CBeteiligte.json):
    ```json
    {
      "fields": {
        "address": "Adresse",
        "vmhvermieterbeteiligte": "Vermieter",
        "vmhmieterbeteiligte": "Mieter",
        "vmhRumungsklagesKlaeger": "Kläger"
      },
      "links": {
        "calls": "Anrufe",
        "tasks": "Aufgaben",
        "vmhvermieterbeteiligte": "Vermieter",
        "vmhmieterbeteiligte": "Mieter",
        "vmhRumungsklagesKlaeger": "Kläger"
      },
      "labels": {
        "Create CBeteiligte": "Beteiligte erstellen"
      }
    }
    ```

    Best Practice:
        - Bei jeder neuen Relationship immer beide Sprachen (de_DE und en_US) aktualisieren
        - Link-Namen in fields UND links eintragen
        - Nach Änderungen Rebuild durchführen
        - Das Admin UI macht dies automatisch, manuelle Änderungen müssen beide Dateien berücksichtigen
        Effekt: Aktualisiert DB-Schema, Views und entfernt alte Caches. Ohne Rebuild sind Änderungen unsichtbar.
        Hinweis: Führe den Befehl auf dem Host aus, da der Container den PHP-Zugang hat.

    **Tooltips für Felder definieren**:
        - Tooltips sind Hilfe-Texte, die beim Hovern über das Info-Icon neben einem Feld erscheinen
        - Tooltips werden in einem separaten `tooltips`-Objekt in den i18n-Dateien definiert
        - Das Feld muss in der entityDef mit `"tooltip": true` markiert sein, damit das Icon angezeigt wird

    Aktivierung in entityDef (entityDefs/{EntityType}.json):
    ```json
    {
      "fields": {
        "lage": {
          "type": "varchar",
          "required": false,
          "maxLength": 255,
          "tooltip": true,
          "isCustom": true
        }
      }
    }
    ```

    Definition in i18n-Dateien (i18n/de_DE/{EntityType}.json):
    ```json
    {
      "fields": {
        "lage": "Lage"
      },
      "links": {},
      "labels": {},
      "tooltips": {
        "lage": "Lage innerhalb des Objekts (z.B. EG links, 1. OG rechts)"
      }
    }
    ```

    Best Practice:
        - Tooltip-Texte sollten kurz und prägnant sein (1-2 Sätze)
        - Tooltips in allen Sprachen definieren (de_DE, en_US, etc.)
        - Nach Änderungen Rebuild durchführen
        - Tooltips werden nur angezeigt, wenn `"tooltip": true` in der entityDef gesetzt ist

## 8. Custom Scripts und Tools

Um die Entwicklung und Wartung zu erleichtern, wurden benutzerdefinierte Scripts im `custom/scripts/`-Ordner abgelegt. Diese Scripts überleben EspoCRM-Updates, da sie außerhalb der Core-Dateien liegen.

### Verfügbare Scripts:

#### workflow_manager.php
- **Zweck**: Verwaltung von BPMN-Workflows in EspoCRM. Ermöglicht das Lesen, Bearbeiten, Löschen, Ausführen und Testen von Workflows direkt über die Datenbank.
- **Bedienung**:
  - Ausführen im EspoCRM-Container: `docker exec espocrm php /var/www/html/custom/scripts/workflow_manager.php <aktion> [parameter]`
  - Aktionen:
    - `list`: Listet alle verfügbaren Workflows auf (ID und Name).
    - `read <id>`: Zeigt detaillierte Informationen zu einem Workflow (inkl. JSON-Data).
    - `delete <id>`: Löscht einen Workflow (mit Bestätigung).
    - `edit <id> <json_data>`: Bearbeitet die Workflow-Data (übergib gültiges JSON).
    - `execute <workflow_id> <record_id>`: Führt einen Workflow manuell für einen Record aus (simuliert Trigger).
    - `test <id>`: Testet Workflow-Bedingungen (simuliert Auswertung).
- **Beispiele**:
  - `docker exec espocrm php /var/www/html/custom/scripts/workflow_manager.php list`
  - `docker exec espocrm php /var/www/html/custom/scripts/workflow_manager.php read 68df9eb6b8d460186`
  - `docker exec espocrm php /var/www/html/custom/scripts/workflow_manager.php execute 68df9eb6b8d460186 some_record_id`
- **Hinweise**:
  - Sichere Backups vor Lösch- oder Edit-Operationen.
  - Für komplexe Änderungen die EspoCRM-UI verwenden.
  - Execute simuliert nur einfache Aktionen; für vollständige Ausführung EspoCRM-API nutzen.

## 8. Troubleshooting

### 404-Fehler "Link does not exist"
- **Symptom**: HTTP 404-Fehler in Logs: "Link does not exist" beim Versuch, eine Relationship anzuzeigen oder zu verknüpfen.
- **Ursache**: Bei hasMany-Relationships fehlt die Definition auf einer Seite der Beziehung. EspoCRM benötigt bidirektionale Link-Definitionen.
- **Lösung**: 
  - Prüfe beide entityDefs-Dateien (z.B. `CBeteiligte.json` UND `Contact.json`).
  - Stelle sicher, dass beide Seiten den Link mit derselben `relationName` definieren.
  - Das `foreign`-Attribut muss jeweils auf den Link-Namen der Gegenseite zeigen.
  - Beispiel:
    ```json
    // In CBeteiligte.json:
    "contactsBeteiligte": {
      "type": "hasMany",
      "relationName": "cBeteiligteContact",
      "foreign": "cBeteiligteContact",
      "entity": "Contact"
    }
    
    // In Contact.json:
    "cBeteiligteContact": {
      "type": "hasMany",
      "relationName": "cBeteiligteContact",
      "foreign": "contactsBeteiligte",
      "entity": "CBeteiligte"
    }
    ```
  - Nach Korrektur: `docker exec espocrm php /var/www/html/command.php Rebuild` ausführen.

### 500-Fehler bei Layout-Änderungen
- **Symptom**: HTTP 500-Fehler beim Versuch, Layouts in der EspoCRM-UI zu bearbeiten (z.B. "Permission denied for custom/Espo/Custom/Resources/layouts/...").
- **Ursache**: Das `custom/`-Verzeichnis gehört `root:root`, aber der EspoCRM-Container läuft als `www-data`-User, der keine Schreibrechte hat.
- **Lösung**: 
  - Führe auf dem Host aus: `chown -R www-data:www-data /var/lib/docker/volumes/vmh-espocrm_espocrm/_data/custom`
  - Dies gibt `www-data` Schreibrechte für Custom-Dateien.
- **Prävention**: Stelle sicher, dass neue Custom-Dateien mit korrekten Berechtigungen erstellt werden (z.B. via Docker-Container als `www-data`).

### Allgemeine Tipps
- Nach Änderungen immer `docker exec espocrm php /var/www/html/command.php Rebuild` ausführen.
- Logs prüfen: `tail -n 100 /var/lib/docker/volumes/vmh-espocrm_espocrm/_data/data/logs/espo-YYYY-MM-DD.log`
- Bei Relationship-Problemen: Logs nach "404" und "Link does not exist" durchsuchen: `tail -n 500 /var/lib/docker/volumes/vmh-espocrm_espocrm/_data/data/logs/espo-$(date +%Y-%m-%d).log | grep -A 3 "404\|Link does not exist"`
- Bei DB-Problemen: Custom-Scripts wie `workflow_manager.php` verwenden.

## 9. Portal-Freigabe-System

Um Entitäten für Portalnutzer (Contact-Entität) freizugeben, wurde ein konsistentes Freigabe-System implementiert:

### Implementierte Portal-Relationships:
- **CVmhMietverhltnis** → `contactsMietverhltnis` (relationName: `cVmhMietverhltnisContact`)
- **CBeteiligte** → `contactsBeteiligte` (relationName: `cBeteiligteContact`)
- **CMietobjekt** → `contactsMietobjekt` (relationName: `cMietobjektContactPortal`)
- **CAdressen** → `contactsAdressen` (relationName: `cAdressenContact`)
- **CVmhRumungsklage** → `contactsRumungsklage` (relationName: `cVmhRumungsklageContact`)

### Pattern für neue Portal-Relationships:

1. **entityDefs der Hauptentität** (z.B. `CBeteiligte.json`):
```json
"contactsBeteiligte": {
  "type": "hasMany",
  "relationName": "cBeteiligteContact",
  "foreign": "cBeteiligteContact",
  "entity": "Contact",
  "audited": false,
  "isCustom": true
}
```

2. **entityDefs von Contact** (`Contact.json`):
```json
"cBeteiligteContact": {
  "type": "hasMany",
  "relationName": "cBeteiligteContact",
  "foreign": "contactsBeteiligte",
  "entity": "CBeteiligte",
  "audited": false,
  "isCustom": true
}
```

3. **clientDefs der Hauptentität** (`CBeteiligte.json`):
```json
"relationshipPanels": {
  "contactsBeteiligte": {
    "layout": null,
    "selectPrimaryFilterName": "portalUsers"
  }
}
```

4. **bottomPanelsDetail Layout** (Tab-Ansicht):
```json
{
  "_tabBreak_0": {
    "index": 0,
    "tabBreak": true,
    "tabLabel": "Freigabe für"
  },
  "contactsBeteiligte": {
    "dynamicLogicVisible": null,
    "style": "warning",
    "dynamicLogicStyled": null,
    "sticked": true,
    "index": 1
  }
}
```

### Wichtige Hinweise:
- `selectPrimaryFilterName: "portalUsers"` filtert automatisch auf Portal-User
- Tab "Freigabe für" sollte immer der erste Tab im Bottom-Panel sein (index: 0)
- Style "warning" hebt das Panel visuell hervor
- Nach Änderungen immer Rebuild durchführen und beide Seiten der Relationship definieren