Update EspoCRM Best Practices to version 2.4 with new features and implementation patterns for Custom API Endpoints; remove outdated TESTERGEBNISSE_JUNCTION_TABLE.md file.
This commit is contained in:
@@ -1,12 +1,12 @@
|
||||
# REST API Endpunkte - EspoCRM Custom Entities
|
||||
|
||||
**Version:** 1.3
|
||||
**Datum:** 11. März 2026
|
||||
**Version:** 1.4
|
||||
**Datum:** 12. März 2026
|
||||
**Base URL:** `https://your-crm.com/api/v1`
|
||||
|
||||
**Changelog:**
|
||||
- v1.4 (12. März 2026): Custom API Endpoints mit routes.json Pattern hinzugefügt; Standard Junction Entity API Dokumentation entfernt (nur Custom API Pattern wird verwendet)
|
||||
- v1.3 (11. März 2026): pending_sync Status zu globalem syncStatus hinzugefügt
|
||||
- v1.2 (11. März 2026): syncedHash-Feld zu Junction-Tables hinzugefügt
|
||||
- v1.1 (11. März 2026): Aktivierungsstatus-Feld hinzugefügt (new, active, paused, deactivated)
|
||||
- v1.0 (11. März 2026): Initiale Version
|
||||
|
||||
@@ -31,10 +31,8 @@ Alle API-Requests benötigen einen API-Key im Header:
|
||||
|
||||
1. [CAdvowareAkten (Advoware Akten)](#cadvowareakten-advoware-akten)
|
||||
2. [CAIKnowledge (AI Knowledge Base)](#caiknowledge-ai-knowledge-base)
|
||||
3. [Junction Tables](#junction-tables)
|
||||
- [CAdvowareAktenCDokumente](#cadvowareaktencdokumente-junction)
|
||||
- [CAIKnowledgeCDokumente](#caiknowledgecdokumente-junction)
|
||||
4. [CDokumente (Dokumente)](#cdokumente-dokumente)
|
||||
3. [CDokumente (Dokumente)](#cdokumente-dokumente)
|
||||
4. [Custom API Endpoints für Junction Tables](#-custom-api-endpoints-für-junction-tables-best-practice)
|
||||
5. [Filtering & Sorting](#filtering--sorting)
|
||||
6. [Praktische Beispiele](#praktische-beispiele)
|
||||
|
||||
@@ -177,7 +175,7 @@ GET /api/v1/CAdvowareAkten/{id}/dokumentes
|
||||
}
|
||||
```
|
||||
|
||||
**⚠️ WICHTIG:** Diese Endpoint gibt **KEINE** Junction-Spalten zurück (`hnr`, `syncstatus`, `lastSync`). Nutze dafür den [Junction API Endpoint](#cadvowareaktencdokumente-junction).
|
||||
**⚠️ WICHTIG:** Dieser Endpoint gibt **KEINE** Junction-Spalten zurück (`hnr`, `syncstatus`, `lastSync`). Nutze dafür den [Custom Junction API Endpoint](#-custom-api-endpoints-für-junction-tables-best-practice).
|
||||
|
||||
#### Dokument mit Akte verknüpfen
|
||||
```http
|
||||
@@ -335,7 +333,7 @@ DELETE /api/v1/CAIKnowledge/{id}
|
||||
GET /api/v1/CAIKnowledge/{id}/dokumentes
|
||||
```
|
||||
|
||||
**⚠️ WICHTIG:** Gibt **KEINE** Junction-Spalten zurück. Nutze [CAIKnowledgeCDokumente Junction API](#caiknowledgecdokumente-junction).
|
||||
**⚠️ WICHTIG:** Gibt **KEINE** Junction-Spalten zurück. Nutze [Custom Junction API Endpoint](#-custom-api-endpoints-für-junction-tables-best-practice).
|
||||
|
||||
#### Dokument verknüpfen
|
||||
```http
|
||||
@@ -387,209 +385,6 @@ GET /api/v1/CAIKnowledge?where[0][type]=equals&where[0][attribute]=syncStatus&wh
|
||||
|
||||
---
|
||||
|
||||
## Junction Tables
|
||||
|
||||
### CAdvowareAktenCDokumente (Junction)
|
||||
|
||||
**Entity:** Junction-Tabelle zwischen CAdvowareAkten und CDokumente mit additionalColumns
|
||||
|
||||
**Verfügbare Felder:**
|
||||
- `cAdvowareAktenId` - ID der Akte
|
||||
- `cDokumenteId` - ID des Dokuments
|
||||
- `hnr` - Advoware HNR-Referenz (varchar, 255)
|
||||
- `syncStatus` - Sync-Status (enum: new, changed, synced, deleted)
|
||||
- `syncedHash` - Hash-Wert des synchronisierten Zustands (varchar, 64)
|
||||
- `deleted` - Soft-Delete Flag
|
||||
|
||||
#### Alle Junction-Einträge
|
||||
```http
|
||||
GET /api/v1/CAdvowareAktenCDokumente
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"total": 150,
|
||||
"list": [
|
||||
{
|
||||
"id": "1",
|
||||
"cAdvowareAktenId": "akte-123",
|
||||
"cDokumenteId": "dok-456",
|
||||
"hnr": "42",
|
||||
"syncStatus": "synced",
|
||||
"syncedHash": "a3f5c8b9e2d1...",
|
||||
"deleted": false
|
||||
},
|
||||
{
|
||||
"id": "2",
|
||||
"cAdvowareAktenId": "akte-123",
|
||||
"cDokumenteId": "dok-789",
|
||||
"hnr": "43",
|
||||
"syncStatus": "new",
|
||||
"syncedHash": null,
|
||||
"deleted": false
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Einzelnen Junction-Eintrag abrufen
|
||||
```http
|
||||
GET /api/v1/CAdvowareAktenCDokumente/{id}
|
||||
```
|
||||
|
||||
#### Alle Dokumente einer Akte mit Junction-Spalten
|
||||
```http
|
||||
GET /api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=cAdvowareAktenId&where[0][value]=akte-123
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"total": 5,
|
||||
"list": [
|
||||
{
|
||||
"id": "1",
|
||||
"cAdvowareAktenId": "akte-123",
|
||||
"cDokumenteId": "dok-456",
|
||||
"hnr": "42",
|
||||
"syncStatus": "synced",
|
||||
"syncedHash": "a3f5c8b9e2d1..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Nach HNR filtern
|
||||
```http
|
||||
GET /api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=hnr&where[0][value]=42
|
||||
```
|
||||
|
||||
#### Nach syncStatus filtern
|
||||
```http
|
||||
GET /api/v1/CAdvowareAktenCDokumente?where[0][type]=in&where[0][attribute]=syncStatus&where[0][value][0]=new&where[0][value][1]=changed
|
||||
```
|
||||
|
||||
#### Neuen Junction-Eintrag erstellen (Dokument mit Akte + HNR verknüpfen)
|
||||
```http
|
||||
POST /api/v1/CAdvowareAktenCDokumente
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"cAdvowareAktenId": "akte-123",
|
||||
"cDokumenteId": "dok-999",
|
||||
"hnr": "50",
|
||||
"syncStatus": "new",
|
||||
"syncedHash": null
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"id": "15"
|
||||
}
|
||||
```
|
||||
|
||||
#### Junction-Spalten aktualisieren
|
||||
```http
|
||||
PUT /api/v1/CAdvowareAktenCDokumente/{junctionId}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"syncStatus": "synced",
|
||||
"syncedHash": "a3f5c8b9e2d1f4a6c7b8e9d0f1a2b3c4",
|
||||
"hnr": "51"
|
||||
}
|
||||
```
|
||||
|
||||
#### Junction-Eintrag löschen
|
||||
```http
|
||||
DELETE /api/v1/CAdvowareAktenCDokumente/{id}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### CAIKnowledgeCDokumente (Junction)
|
||||
|
||||
**Entity:** Junction-Tabelle zwischen CAIKnowledge und CDokumente mit additionalColumns
|
||||
|
||||
**Verfügbare Felder:**
|
||||
- `cAIKnowledgeId` - ID des AI Knowledge Entry
|
||||
- `cDokumenteId` - ID des Dokuments
|
||||
- `aiDocumentId` - Externe AI-Dokument-Referenz-ID (varchar, 255)
|
||||
- `syncstatus` - Sync-Status (enum: new, unclean, synced, failed, unsupported)
|
||||
- `lastSync` - Zeitpunkt der letzten Synchronisation (datetime)
|
||||
- `syncedHash` - Hash-Wert des synchronisierten Zustands (varchar, 64)
|
||||
- `deleted` - Soft-Delete Flag
|
||||
|
||||
#### Alle Junction-Einträge
|
||||
```http
|
||||
GET /api/v1/CAIKnowledgeCDokumente
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"total": 80,
|
||||
"list": [
|
||||
{
|
||||
"id": "1",
|
||||
"cAIKnowledgeId": "kb-123",
|
||||
"cDokumenteId": "dok-456",
|
||||
"aiDocumentId": "ai-doc-external-789",
|
||||
"syncstatus": "synced",
|
||||
"lastSync": "2026-03-11 19:00:00",
|
||||
"syncedHash": "b4e2a9c7f3d8...",
|
||||
"deleted": false
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Alle Dokumente eines Knowledge Entry mit Junction-Spalten
|
||||
```http
|
||||
GET /api/v1/CAIKnowledgeCDokumente?where[0][type]=equals&where[0][attribute]=cAIKnowledgeId&where[0][value]=kb-123
|
||||
```
|
||||
|
||||
#### Nach aiDocumentId suchen
|
||||
```http
|
||||
GET /api/v1/CAIKnowledgeCDokumente?where[0][type]=equals&where[0][attribute]=aiDocumentId&where[0][value]=ai-doc-external-789
|
||||
```
|
||||
|
||||
#### Nach syncstatus filtern
|
||||
```http
|
||||
GET /api/v1/CAIKnowledgeCDokumente?where[0][type]=equals&where[0][attribute]=syncstatus&where[0][value]=unclean
|
||||
```
|
||||
|
||||
#### Neuen Junction-Eintrag erstellen
|
||||
```http
|
||||
POST /api/v1/CAIKnowledgeCDokumente
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"cAIKnowledgeId": "kb-123",
|
||||
"cDokumenteId": "dok-999",
|
||||
"aiDocumentId": "ai-doc-new-123",
|
||||
"syncstatus": "new",
|
||||
"syncedHash": null
|
||||
}
|
||||
```
|
||||
|
||||
#### Junction-Spalten aktualisieren
|
||||
```http
|
||||
PUT /api/v1/CAIKnowledgeCDokumente/{junctionId}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"syncstatus": "synced",
|
||||
"lastSync": "2026-03-11T20:30:00+00:00",
|
||||
"syncedHash": "b4e2a9c7f3d8e1a5c6b7d8e9f0a1b2c3"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CDokumente (Dokumente)
|
||||
|
||||
**Entity:** Dokumentenverwaltung
|
||||
@@ -710,49 +505,41 @@ curl -X GET "https://crm.example.com/api/v1/CAdvowareAkten?where[0][type]=equals
|
||||
### Beispiel 2: Alle Dokumente einer Akte mit Junction-Spalten
|
||||
|
||||
```bash
|
||||
# Schritt 1: Hole Akte
|
||||
curl -X GET "https://crm.example.com/api/v1/CAdvowareAkten/akte-123" \
|
||||
# Custom API Endpoint für CAIKnowledge (siehe Custom API Sektion unten)
|
||||
curl -X GET "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/69b1b03582bb6e2da/dokumentes" \
|
||||
-H "X-Api-Key: your-api-key"
|
||||
|
||||
# Schritt 2: Hole Junction-Einträge mit HNR
|
||||
curl -X GET "https://crm.example.com/api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=cAdvowareAktenId&where[0][value]=akte-123&select=cDokumenteId,hnr,syncStatus,syncedHash" \
|
||||
-H "X-Api-Key: your-api-key"
|
||||
# Response enthält alle Dokumente MIT Junction-Spalten in einem Call
|
||||
```
|
||||
|
||||
### Beispiel 3: Dokument mit Akte + HNR verknüpfen
|
||||
### Beispiel 3: Junction-Spalten aktualisieren
|
||||
|
||||
```bash
|
||||
# Via Junction API (empfohlen)
|
||||
curl -X POST "https://crm.example.com/api/v1/CAdvowareAktenCDokumente" \
|
||||
# Via Custom Junction API Endpoint (empfohlen)
|
||||
curl -X PUT "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/kb-123/dokumentes/dok-789" \
|
||||
-H "X-Api-Key: your-api-key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"cAdvowareAktenId": "akte-123",
|
||||
"cDokumenteId": "dok-789",
|
||||
"hnr": "42",
|
||||
"syncStatus": "new",
|
||||
"syncedHash": null
|
||||
"aiDocumentId": "EXTERNAL-AI-123",
|
||||
"syncstatus": "synced",
|
||||
"updateLastSync": true
|
||||
}'
|
||||
```
|
||||
|
||||
### Beispiel 4: Sync-Status aktualisieren nach erfolgreicher Synchronisation
|
||||
|
||||
```bash
|
||||
# Schritt 1: Finde Junction-Eintrag
|
||||
JUNCTION_ID=$(curl -s -X GET "https://crm.example.com/api/v1/CAdvowareAktenCDokumente?where[0][type]=equals&where[0][attribute]=cAdvowareAktenId&where[0][value]=akte-123&where[1][type]=equals&where[1][attribute]=cDokumenteId&where[1][value]=dok-789&select=id" \
|
||||
-H "X-Api-Key: your-api-key" | jq -r '.list[0].id')
|
||||
|
||||
# Schritt 2: Update Junction-Status
|
||||
curl -X PUT "https://crm.example.com/api/v1/CAdvowareAktenCDokumente/$JUNCTION_ID" \
|
||||
# Direktes Update mit Custom API (kein Suchen nötig!)
|
||||
curl -X PUT "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/kb-123/dokumentes/dok-789" \
|
||||
-H "X-Api-Key: your-api-key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"syncStatus": "synced",
|
||||
"syncedHash": "a3f5c8b9e2d1f4a6c7b8e9d0f1a2b3c4"
|
||||
"syncstatus": "synced",
|
||||
"updateLastSync": true
|
||||
}'
|
||||
|
||||
# Schritt 3: Update global status (optional, Hooks machen das automatisch)
|
||||
curl -X PUT "https://crm.example.com/api/v1/CAdvowareAkten/akte-123" \
|
||||
# Update global status (optional, Hooks machen das automatisch)
|
||||
curl -X PUT "https://crm.example.com/api/v1/CAIKnowledge/kb-123" \
|
||||
-H "X-Api-Key: your-api-key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
@@ -765,19 +552,18 @@ curl -X PUT "https://crm.example.com/api/v1/CAdvowareAkten/akte-123" \
|
||||
### Beispiel 5: Suche AI-Dokument via externe ID
|
||||
|
||||
```bash
|
||||
# Finde Junction-Eintrag via aiDocumentId
|
||||
curl -X GET "https://crm.example.com/api/v1/CAIKnowledgeCDokumente?where[0][type]=equals&where[0][attribute]=aiDocumentId&where[0][value]=ai-doc-external-789" \
|
||||
-H "X-Api-Key: your-api-key"
|
||||
|
||||
# Response enthält cDokumenteId zum Abrufen des vollen Dokuments
|
||||
# Custom API gibt alle Dokumente mit Junction-Daten zurück
|
||||
# Clientseitig filtern nach aiDocumentId:
|
||||
curl -X GET "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/kb-123/dokumentes" \
|
||||
-H "X-Api-Key: your-api-key" | jq '.list[] | select(.aiDocumentId=="ai-doc-external-789")'
|
||||
```
|
||||
|
||||
### Beispiel 6: Alle neuen/geänderten Dokumente für Sync
|
||||
|
||||
```bash
|
||||
# Finde alle Junction-Einträge die "new" oder "changed" sind
|
||||
curl -X GET "https://crm.example.com/api/v1/CAdvowareAktenCDokumente?where[0][type]=in&where[0][attribute]=syncStatus&where[0][value][0]=new&where[0][value][1]=changed&select=cAdvowareAktenId,cDokumenteId,hnr,syncStatus,syncedHash" \
|
||||
-H "X-Api-Key: your-api-key"
|
||||
# Custom API gibt alle Dokumente zurück - clientseitig filtern nach syncstatus
|
||||
curl -X GET "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/kb-123/dokumentes" \
|
||||
-H "X-Api-Key: your-api-key" | jq '.list[] | select(.syncstatus=="new" or .syncstatus=="unclean")'
|
||||
```
|
||||
|
||||
### Beispiel 7: Alle aktiven Akten abrufen
|
||||
@@ -840,49 +626,6 @@ curl -X PUT "https://crm.example.com/api/v1/CAdvowareAkten/akte-123" \
|
||||
|
||||
## 🎯 Wichtige Hinweise
|
||||
|
||||
### syncedHash - Änderungserkennung
|
||||
|
||||
**Zweck:** Hash-basierte Versionierung zur Erkennung von Dokumentänderungen zwischen Synchronisationen
|
||||
|
||||
**Verwendung:**
|
||||
```bash
|
||||
# 1. Nach erfolgreicher Synchronisation: Hash berechnen und speichern
|
||||
curl -X PUT "https://crm.example.com/api/v1/CAdvowareAktenCDokumente/123" \
|
||||
-H "X-Api-Key: your-api-key" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"syncStatus": "synced",
|
||||
"syncedHash": "sha256:a3f5c8b9e2d1f4a6c7b8e9d0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0"
|
||||
}'
|
||||
|
||||
# 2. Bei nächster Synchronisation: Aktuellen Hash mit syncedHash vergleichen
|
||||
# Wenn unterschiedlich → Dokument wurde geändert → syncStatus = "changed"
|
||||
```
|
||||
|
||||
**Hash-Berechnung:**
|
||||
```python
|
||||
import hashlib
|
||||
|
||||
# Beispiel: Hash aus Dokument-Metadaten berechnen
|
||||
def calculate_document_hash(document):
|
||||
content = f"{document['name']}|{document['modifiedAt']}|{document['size']}"
|
||||
return hashlib.sha256(content.encode()).hexdigest()
|
||||
```
|
||||
|
||||
**Workflow:**
|
||||
1. **Initial Sync:** syncedHash = NULL, syncStatus = "new"
|
||||
2. **Sync durchgeführt:** syncedHash = berechnet, syncStatus = "synced"
|
||||
3. **Dokument geändert:** Hook setzt syncStatus = "unclean"
|
||||
4. **Nächster Sync:** Vergleiche aktuellen Hash mit syncedHash
|
||||
- Gleich → Keine Änderung, skip
|
||||
- Unterschiedlich → Sync durchführen, neuen Hash speichern
|
||||
|
||||
**Frontend-Anzeige:**
|
||||
Das Feld wird automatisch in der Link-Multiple-Spalte "Dokumente" angezeigt:
|
||||
- In CAdvowareAkten: Spalte "Sync-Hash" zeigt den Hash-Wert
|
||||
- In CAIKnowledge: Spalte "Sync-Hash" zeigt den Hash-Wert
|
||||
- Tooltip: "Hash-Wert des zuletzt synchronisierten Dokument-Zustands (zur Änderungserkennung)"
|
||||
|
||||
### Aktivierungsstatus
|
||||
|
||||
**Zweck:** Steuerung der Synchronisations-Aktivität für Akten und AI Knowledge Entries
|
||||
@@ -893,6 +636,34 @@ Das Feld wird automatisch in der Link-Multiple-Spalte "Dokumente" angezeigt:
|
||||
- `paused` - Synchronisation temporär pausiert, kann wieder aktiviert werden
|
||||
- `deactivated` - Synchronisation dauerhaft deaktiviert
|
||||
|
||||
### Blake3 Hash für Änderungserkennung
|
||||
|
||||
**Zweck:** Dokumentänderungen zwischen Synchronisationen erkennen
|
||||
|
||||
Das `blake3hash` Feld ist direkt am CDokumente Entity verfügbar und wird automatisch vom `CDokumente` Hook berechnet:
|
||||
|
||||
```bash
|
||||
# Custom API gibt blake3hash mit zurück
|
||||
curl -X GET "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/kb-123/dokumentes" \
|
||||
-H "X-Api-Key: your-api-key"
|
||||
|
||||
# Response enthält blake3hash für jedes Dokument:
|
||||
{
|
||||
"list": [{
|
||||
"documentId": "dok-123",
|
||||
"documentName": "contract.pdf",
|
||||
"blake3hash": "b7cb1f2a3fd62f86aabff41a51921d96d10b54371c74d31c917b3c3074a204ca",
|
||||
"syncstatus": "synced"
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
**Änderungserkennung:**
|
||||
1. Bei Sync: Speichere aktuellen `blake3hash` clientseitig oder in eigenem System
|
||||
2. Nächster Sync: Frage Custom API ab, vergleiche `blake3hash`
|
||||
3. Wenn unterschiedlich → Dokument geändert → Re-Sync nötig
|
||||
4. Update `syncstatus` via Custom API PUT Endpoint
|
||||
|
||||
### Globaler syncStatus
|
||||
|
||||
**Zweck:** Übersicht über den Synchronisationszustand aller Dokumente einer Akte/eines AI Knowledge Entries
|
||||
@@ -963,10 +734,10 @@ GET /api/v1/CAdvowareAkten?where[0][type]=in&where[0][attribute]=aktivierungssta
|
||||
|
||||
### Junction-Spalten via REST API
|
||||
|
||||
**✅ RICHTIG:** Nutze Junction-Entity-APIs
|
||||
**✅ RICHTIG:** Nutze Custom API Endpoints
|
||||
```bash
|
||||
GET /api/v1/CAdvowareAktenCDokumente
|
||||
GET /api/v1/CAIKnowledgeCDokumente
|
||||
GET /api/v1/JunctionData/CAIKnowledge/{knowledgeId}/dokumentes
|
||||
# (Siehe Custom API Endpoints Sektion unten)
|
||||
```
|
||||
|
||||
**❌ FALSCH:** Standard Relationship-Endpoints geben additionalColumns NICHT zurück
|
||||
@@ -974,6 +745,381 @@ GET /api/v1/CAIKnowledgeCDokumente
|
||||
GET /api/v1/CAdvowareAkten/{id}/dokumentes # hnr/syncStatus NICHT in Response!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Custom API Endpoints für Junction Tables (Best Practice)
|
||||
|
||||
**Problem:** Die Standard Junction-Entity-API hat folgende Einschränkungen:
|
||||
- ACL-Zugriffsprobleme (oft 403 Forbidden trotz korrekter Konfiguration)
|
||||
- Keine JOIN-Queries → Separater Call für Dokumentdetails nötig
|
||||
- Umständliche Filterung
|
||||
- Hooks können unerwünschte Seiteneffekte haben
|
||||
|
||||
**Lösung:** Custom API Endpoint mit direkten SQL-Queries (seit EspoCRM 7.4+)
|
||||
|
||||
### Implementation (Beispiel: CAIKnowledge Junction API)
|
||||
|
||||
#### 1. Routes definieren
|
||||
|
||||
**Datei:** `custom/Espo/Custom/Resources/routes.json`
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"route": "/JunctionData/CAIKnowledge/:knowledgeId/dokumentes",
|
||||
"method": "get",
|
||||
"actionClassName": "Espo\\Custom\\Api\\JunctionData\\GetDokumentes"
|
||||
},
|
||||
{
|
||||
"route": "/JunctionData/CAIKnowledge/:knowledgeId/dokumentes/:documentId",
|
||||
"method": "put",
|
||||
"actionClassName": "Espo\\Custom\\Api\\JunctionData\\UpdateJunction"
|
||||
},
|
||||
{
|
||||
"route": "/JunctionData/CAIKnowledge/:knowledgeId/dokumentes/:documentId",
|
||||
"method": "post",
|
||||
"actionClassName": "Espo\\Custom\\Api\\JunctionData\\LinkDokument"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Wichtig:**
|
||||
- Nach Änderungen: **Administration → Clear Cache** (erforderlich!)
|
||||
- Route-Parameter mit `:paramName` → verfügbar als `$request->getRouteParam('paramName')`
|
||||
- `actionClassName` mit vollständigem Namespace (doppelte Backslashes!)
|
||||
|
||||
#### 2. Action Class: GET - Alle Dokumente mit Junction-Daten
|
||||
|
||||
**Datei:** `custom/Espo/Custom/Api/JunctionData/GetDokumentes.php`
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
namespace Espo\Custom\Api\JunctionData;
|
||||
|
||||
use Espo\Core\Api\Action;
|
||||
use Espo\Core\Api\Request;
|
||||
use Espo\Core\Api\Response;
|
||||
use Espo\Core\Api\ResponseComposer;
|
||||
use Espo\Core\Exceptions\BadRequest;
|
||||
use Espo\Core\Exceptions\NotFound;
|
||||
use Espo\ORM\EntityManager;
|
||||
|
||||
/**
|
||||
* GET /api/v1/JunctionData/CAIKnowledge/:knowledgeId/dokumentes
|
||||
*
|
||||
* Returns all documents linked to a knowledge entry with junction table data
|
||||
*/
|
||||
class GetDokumentes implements Action
|
||||
{
|
||||
public function __construct(
|
||||
private EntityManager $entityManager
|
||||
) {}
|
||||
|
||||
public function process(Request $request): Response
|
||||
{
|
||||
$knowledgeId = $request->getRouteParam('knowledgeId');
|
||||
|
||||
if (!$knowledgeId) {
|
||||
throw new BadRequest('Knowledge ID is required');
|
||||
}
|
||||
|
||||
// Verify knowledge exists
|
||||
$knowledge = $this->entityManager->getEntityById('CAIKnowledge', $knowledgeId);
|
||||
if (!$knowledge) {
|
||||
throw new NotFound('Knowledge entry not found');
|
||||
}
|
||||
|
||||
$pdo = $this->entityManager->getPDO();
|
||||
|
||||
// Direct SQL query with JOIN - much more efficient!
|
||||
$sql = "
|
||||
SELECT
|
||||
j.id as junctionId,
|
||||
j.c_a_i_knowledge_id as cAIKnowledgeId,
|
||||
j.c_dokumente_id as cDokumenteId,
|
||||
j.ai_document_id as aiDocumentId,
|
||||
j.syncstatus,
|
||||
j.last_sync as lastSync,
|
||||
d.id as documentId,
|
||||
d.name as documentName,
|
||||
d.blake3hash as blake3hash,
|
||||
d.created_at as documentCreatedAt,
|
||||
d.modified_at as documentModifiedAt
|
||||
FROM c_a_i_knowledge_dokumente j
|
||||
INNER JOIN c_dokumente d ON j.c_dokumente_id = d.id
|
||||
WHERE j.c_a_i_knowledge_id = :knowledgeId
|
||||
AND j.deleted = 0
|
||||
AND d.deleted = 0
|
||||
ORDER BY j.id DESC
|
||||
";
|
||||
|
||||
$sth = $pdo->prepare($sql);
|
||||
$sth->execute(['knowledgeId' => $knowledgeId]);
|
||||
|
||||
$results = $sth->fetchAll(\PDO::FETCH_ASSOC);
|
||||
|
||||
return ResponseComposer::json([
|
||||
'total' => count($results),
|
||||
'list' => $results
|
||||
]);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Wichtige Details:**
|
||||
- **Snake_case:** DB-Spaltennamen verwenden `snake_case` (z.B. `last_sync`, nicht `lastSync`)
|
||||
- **Dependency Injection:** Constructor Injection funktioniert automatisch
|
||||
- **PDO direkt:** `$this->entityManager->getPDO()` für rohe SQL-Queries
|
||||
- **Validierung:** Entity-Existenz prüfen für bessere Errors
|
||||
- **ResponseComposer::json():** Moderne Response-Methode
|
||||
|
||||
#### 3. Action Class: PUT - Junction-Spalten aktualisieren
|
||||
|
||||
**Datei:** `custom/Espo/Custom/Api/JunctionData/UpdateJunction.php`
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
namespace Espo\Custom\Api\JunctionData;
|
||||
|
||||
use Espo\Core\Api\Action;
|
||||
use Espo\Core\Api\Request;
|
||||
use Espo\Core\Api\Response;
|
||||
use Espo\Core\Api\ResponseComposer;
|
||||
use Espo\Core\Exceptions\BadRequest;
|
||||
use Espo\Core\Exceptions\NotFound;
|
||||
use Espo\ORM\EntityManager;
|
||||
|
||||
/**
|
||||
* PUT /api/v1/JunctionData/CAIKnowledge/:knowledgeId/dokumentes/:documentId
|
||||
*
|
||||
* Updates junction table columns for an existing relationship
|
||||
*/
|
||||
class UpdateJunction implements Action
|
||||
{
|
||||
public function __construct(
|
||||
private EntityManager $entityManager
|
||||
) {}
|
||||
|
||||
public function process(Request $request): Response
|
||||
{
|
||||
$knowledgeId = $request->getRouteParam('knowledgeId');
|
||||
$documentId = $request->getRouteParam('documentId');
|
||||
$data = $request->getParsedBody();
|
||||
|
||||
if (!$knowledgeId || !$documentId) {
|
||||
throw new BadRequest('Knowledge ID and Document ID are required');
|
||||
}
|
||||
|
||||
$pdo = $this->entityManager->getPDO();
|
||||
|
||||
// Build dynamic UPDATE with only provided fields
|
||||
$setClauses = [];
|
||||
$params = [
|
||||
'knowledgeId' => $knowledgeId,
|
||||
'documentId' => $documentId
|
||||
];
|
||||
|
||||
if (isset($data->aiDocumentId)) {
|
||||
$setClauses[] = "ai_document_id = :aiDocumentId";
|
||||
$params['aiDocumentId'] = $data->aiDocumentId;
|
||||
}
|
||||
|
||||
if (isset($data->syncstatus)) {
|
||||
$allowedStatuses = ['new', 'unclean', 'synced', 'failed', 'unsupported'];
|
||||
if (!in_array($data->syncstatus, $allowedStatuses)) {
|
||||
throw new BadRequest('Invalid syncstatus. Allowed: ' . implode(', ', $allowedStatuses));
|
||||
}
|
||||
$setClauses[] = "syncstatus = :syncstatus";
|
||||
$params['syncstatus'] = $data->syncstatus;
|
||||
}
|
||||
|
||||
if (isset($data->lastSync)) {
|
||||
$setClauses[] = "last_sync = :lastSync";
|
||||
$params['lastSync'] = $data->lastSync;
|
||||
} elseif (isset($data->updateLastSync) && $data->updateLastSync === true) {
|
||||
$setClauses[] = "last_sync = NOW()";
|
||||
}
|
||||
|
||||
if (empty($setClauses)) {
|
||||
throw new BadRequest('No fields to update. Provide: aiDocumentId, syncstatus, or lastSync');
|
||||
}
|
||||
|
||||
$sql = "
|
||||
UPDATE c_a_i_knowledge_dokumente
|
||||
SET " . implode(', ', $setClauses) . "
|
||||
WHERE c_a_i_knowledge_id = :knowledgeId
|
||||
AND c_dokumente_id = :documentId
|
||||
AND deleted = 0
|
||||
";
|
||||
|
||||
$sth = $pdo->prepare($sql);
|
||||
$sth->execute($params);
|
||||
|
||||
if ($sth->rowCount() === 0) {
|
||||
throw new NotFound('Junction entry not found or no changes made');
|
||||
}
|
||||
|
||||
// Return updated data
|
||||
return ResponseComposer::json($this->getJunctionEntry($knowledgeId, $documentId));
|
||||
}
|
||||
|
||||
private function getJunctionEntry(string $knowledgeId, string $documentId): array
|
||||
{
|
||||
$pdo = $this->entityManager->getPDO();
|
||||
|
||||
$sql = "
|
||||
SELECT
|
||||
id as junctionId,
|
||||
c_a_i_knowledge_id as cAIKnowledgeId,
|
||||
c_dokumente_id as cDokumenteId,
|
||||
ai_document_id as aiDocumentId,
|
||||
syncstatus,
|
||||
last_sync as lastSync
|
||||
FROM c_a_i_knowledge_dokumente
|
||||
WHERE c_a_i_knowledge_id = :knowledgeId
|
||||
AND c_dokumente_id = :documentId
|
||||
AND deleted = 0
|
||||
";
|
||||
|
||||
$sth = $pdo->prepare($sql);
|
||||
$sth->execute([
|
||||
'knowledgeId' => $knowledgeId,
|
||||
'documentId' => $documentId
|
||||
]);
|
||||
|
||||
$result = $sth->fetch(\PDO::FETCH_ASSOC);
|
||||
|
||||
if (!$result) {
|
||||
throw new NotFound('Junction entry not found');
|
||||
}
|
||||
|
||||
return $result;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Highlights:**
|
||||
- **Dynamisches UPDATE:** Nur Felder updaten, die im Request Body übergeben wurden
|
||||
- **Validierung:** Enum-Werte prüfen bevor DB-Update
|
||||
- **NOW()-Trick:** `updateLastSync: true` → Automatischer Timestamp
|
||||
- **rowCount():** Prüfen ob wirklich ein Record betroffen war
|
||||
|
||||
#### 4. Praktische API-Verwendung
|
||||
|
||||
**GET: Alle Dokumente mit Junction-Daten abrufen**
|
||||
```bash
|
||||
curl -X GET "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/69b1b03582bb6e2da/dokumentes" \
|
||||
-H "X-Api-Key: e53def10eea27b92a6cd00f40a3e09a4"
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"total": 2,
|
||||
"list": [
|
||||
{
|
||||
"junctionId": 5,
|
||||
"cAIKnowledgeId": "69b1b03582bb6e2da",
|
||||
"cDokumenteId": "6974aba30cd69c723",
|
||||
"aiDocumentId": "NEW-DOC-FROM-API",
|
||||
"syncstatus": "new",
|
||||
"lastSync": "2026-03-12 21:38:24",
|
||||
"documentId": "6974aba30cd69c723",
|
||||
"documentName": "2. dokuments",
|
||||
"blake3hash": null,
|
||||
"documentCreatedAt": "2026-01-24 11:23:15",
|
||||
"documentModifiedAt": "2026-03-03 09:48:14"
|
||||
},
|
||||
{
|
||||
"junctionId": 1,
|
||||
"cAIKnowledgeId": "69b1b03582bb6e2da",
|
||||
"cDokumenteId": "69a68b556a39771bf",
|
||||
"aiDocumentId": "UPDATED-VIA-API-123",
|
||||
"syncstatus": "synced",
|
||||
"lastSync": "2026-03-12 21:37:44",
|
||||
"documentId": "69a68b556a39771bf",
|
||||
"documentName": "hollibolli",
|
||||
"blake3hash": "b7cb1f2a3fd62f86aabff41a51921d96d10b54371c74d31c917b3c3074a204ca",
|
||||
"documentCreatedAt": "2026-03-03 07:18:45",
|
||||
"documentModifiedAt": "2026-03-12 20:19:01"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**PUT: Junction-Spalten aktualisieren**
|
||||
```bash
|
||||
curl -X PUT "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/69b1b03582bb6e2da/dokumentes/69a68b556a39771bf" \
|
||||
-H "X-Api-Key: e53def10eea27b92a6cd00f40a3e09a4" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"aiDocumentId": "EXTERNAL-AI-DOC-123",
|
||||
"syncstatus": "synced",
|
||||
"updateLastSync": true
|
||||
}'
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"junctionId": 1,
|
||||
"cAIKnowledgeId": "69b1b03582bb6e2da",
|
||||
"cDokumenteId": "69a68b556a39771bf",
|
||||
"aiDocumentId": "EXTERNAL-AI-DOC-123",
|
||||
"syncstatus": "synced",
|
||||
"lastSync": "2026-03-12 21:42:15"
|
||||
}
|
||||
```
|
||||
|
||||
**POST: Neues Dokument verknüpfen + Junction-Daten setzen**
|
||||
```bash
|
||||
curl -X POST "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/69b1b03582bb6e2da/dokumentes/6974aba30cd69c723" \
|
||||
-H "X-Api-Key: e53def10eea27b92a6cd00f40a3e09a4" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"aiDocumentId": "NEW-EXTERNAL-DOC",
|
||||
"syncstatus": "new",
|
||||
"updateLastSync": true
|
||||
}'
|
||||
```
|
||||
|
||||
### Vorteile Custom API Endpoints
|
||||
|
||||
✅ **Performance:** JOIN-Queries in einem Call statt mehrere API-Requests
|
||||
✅ **Keine ACL-Probleme:** Direkter DB-Zugriff umgeht ACL-System
|
||||
✅ **Volle Kontrolle:** Exakte Control über SQL und Response-Struktur
|
||||
✅ **Hooks umgehen:** SQL-Updates lösen keine Entity-Hooks aus (wenn gewünscht)
|
||||
✅ **Flexible Responses:** Kann mehrere Entities in einer Response joinen
|
||||
✅ **Type Safety:** Moderne PHP 8+ mit Constructor Property Promotion
|
||||
✅ **Wartbar:** Klare Trennung zwischen Routes, Actions und Business Logic
|
||||
|
||||
### Best Practices
|
||||
|
||||
1. **Immer validieren:** Entity-Existenz prüfen bevor DB-Operations
|
||||
2. **Snake_case beachten:** DB-Spaltennamen verwenden Unterstriche
|
||||
3. **Prepared Statements:** Immer PDO Prepared Statements für SQL-Injection-Schutz
|
||||
4. **Error Handling:** Spezifische Exceptions (BadRequest, NotFound, Forbidden)
|
||||
5. **Documentation:** PHPDoc für jede Action Class mit Endpoint-Beschreibung
|
||||
6. **Testing:** API-Endpoints mit Python/Bash testen vor Produktiveinsatz
|
||||
7. **Cache löschen:** Nach routes.json Änderungen IMMER Cache clearen!
|
||||
|
||||
### Wann Custom API verwenden?
|
||||
|
||||
**✅ Verwende Custom API wenn:**
|
||||
- Junction-Spalten häufig gelesen/geschrieben werden
|
||||
- JOINs über mehrere Tabellen nötig sind
|
||||
- Performance kritisch ist (viele Dokumente)
|
||||
- ACL-Probleme mit Standard Junction-Entity API
|
||||
- Spezielle Business Logic beim Read/Write nötig
|
||||
|
||||
**❌ Verwende Standard API wenn:**
|
||||
- Einfache CRUD ohne Junction-Spalten
|
||||
- ACL-System explizit gewünscht
|
||||
- Hooks sollen ausgelöst werden
|
||||
- Wenig Datenvolumen
|
||||
|
||||
### Hooks & Automatische Updates
|
||||
|
||||
Folgende Operationen lösen automatisch Hooks aus:
|
||||
@@ -998,23 +1144,9 @@ PUT /api/v1/CAdvowareAkten/{id}
|
||||
```
|
||||
- → `CheckGlobalSyncStatus`: Berechnet globalen Status aus Junction-Einträgen
|
||||
|
||||
### ACL-Berechtigungen
|
||||
|
||||
Für Junction-Entities müssen Rollen explizit Zugriff haben:
|
||||
|
||||
```sql
|
||||
-- Via Admin UI: Roles → [Your Role] → Add "CAdvowareAktenCDokumente"
|
||||
-- Oder via SQL:
|
||||
UPDATE role
|
||||
SET data = JSON_SET(data, '$.table.CAdvowareAktenCDokumente',
|
||||
JSON_OBJECT('create','yes','read','all','edit','all','delete','all')
|
||||
)
|
||||
WHERE name = 'Your Role Name';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Letzte Aktualisierung:** 11. März 2026
|
||||
**Version:** 1.3
|
||||
**Letzte Aktualisierung:** 12. März 2026
|
||||
**Version:** 1.4
|
||||
|
||||
Für weitere Fragen: Siehe `custom/docs/ESPOCRM_BEST_PRACTICES.md`
|
||||
|
||||
@@ -1,11 +1,31 @@
|
||||
# EspoCRM Best Practices & Entwicklungsrichtlinien
|
||||
|
||||
**Version:** 2.3
|
||||
**Datum:** 11. März 2026
|
||||
**Version:** 2.4
|
||||
**Datum:** 12. März 2026
|
||||
**Zielgruppe:** AI Code Agents & Entwickler
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Letzte Änderungen (v2.4 - 12. März 2026)
|
||||
|
||||
**Neue Features:**
|
||||
- ✅ **Custom API Endpoints mit routes.json**: Vollständiges Pattern für moderne Custom API (EspoCRM 7+)
|
||||
- ✅ **Junction Table Custom API**: Best Practice für direkte SQL-basierte Junction-Zugriffe
|
||||
- ✅ **Real-World Beispiel**: CAIKnowledge Junction API (GET/PUT/POST) mit vollständigem Code
|
||||
- ✅ **Performance-Optimierung**: JOIN-Queries in einem Call statt mehrere API-Requests
|
||||
- ✅ **ACL-Workaround**: Umgehung von ACL-Problemen bei Junction Entities
|
||||
|
||||
**Dokumentierte Patterns:**
|
||||
- routes.json Setup und Configuration
|
||||
- Action Classes mit Constructor Property Promotion
|
||||
- Direkte PDO-Queries für Junction Tables
|
||||
- Dynamische UPDATE-Queries mit variablen Feldern
|
||||
- Error Handling (BadRequest, NotFound, Forbidden)
|
||||
- Snake_case vs CamelCase in DB-Queries
|
||||
- Typische Fehler und Debugging-Strategien
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Letzte Änderungen (v2.3 - 11. März 2026)
|
||||
|
||||
**Neue Features:**
|
||||
@@ -951,6 +971,368 @@ curl -X GET "https://crm.example.com/api/v1/CMyEntity" \
|
||||
|
||||
---
|
||||
|
||||
### Custom API Endpoints mit routes.json (Modern, EspoCRM 7+)
|
||||
|
||||
**Status:** ✅ Empfohlene Methode seit EspoCRM 7.4+ (Controller-Methode deprecated)
|
||||
|
||||
#### Wann Custom API Endpoints verwenden?
|
||||
|
||||
**✅ Verwende Custom API wenn:**
|
||||
- Junction Table additionalColumns lesen/schreiben
|
||||
- JOINs über mehrere Tabellen erforderlich
|
||||
- ACL-Probleme mit Standard Junction-Entity API
|
||||
- Performance-kritische Operationen (viele Datensätze)
|
||||
- Spezielle Business Logic ohne Entity-Hooks
|
||||
- Hooks sollen NICHT ausgelöst werden
|
||||
|
||||
**❌ Verwende Standard API wenn:**
|
||||
- Einfache CRUD-Operationen ohne Junction-Spalten
|
||||
- ACL-System explizit gewünscht
|
||||
- Entity-Hooks sollen ausgelöst werden
|
||||
|
||||
#### Implementierungs-Pattern
|
||||
|
||||
**1. Routes definieren**
|
||||
|
||||
**Datei:** `custom/Espo/Custom/Resources/routes.json`
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"route": "/JunctionData/CAIKnowledge/:knowledgeId/dokumentes",
|
||||
"method": "get",
|
||||
"actionClassName": "Espo\\Custom\\Api\\JunctionData\\GetDokumentes"
|
||||
},
|
||||
{
|
||||
"route": "/JunctionData/CAIKnowledge/:knowledgeId/dokumentes/:documentId",
|
||||
"method": "put",
|
||||
"actionClassName": "Espo\\Custom\\Api\\JunctionData\\UpdateJunction"
|
||||
},
|
||||
{
|
||||
"route": "/JunctionData/CAIKnowledge/:knowledgeId/dokumentes/:documentId",
|
||||
"method": "post",
|
||||
"actionClassName": "Espo\\Custom\\Api\\JunctionData\\LinkDokument"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Wichtig:**
|
||||
- **Dateiname:** `routes.json` (NICHT `api.json`!)
|
||||
- **Location:** `custom/Espo/Custom/Resources/routes.json`
|
||||
- **Namespace:** Doppelte Backslashes in `actionClassName`!
|
||||
- **Cache:** Nach Änderungen **IMMER** Clear Cache + Rebuild!
|
||||
|
||||
**2. Action Class implementieren**
|
||||
|
||||
**Datei:** `custom/Espo/Custom/Api/JunctionData/GetDokumentes.php`
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
namespace Espo\Custom\Api\JunctionData;
|
||||
|
||||
use Espo\Core\Api\Action;
|
||||
use Espo\Core\Api\Request;
|
||||
use Espo\Core\Api\Response;
|
||||
use Espo\Core\Api\ResponseComposer;
|
||||
use Espo\Core\Exceptions\BadRequest;
|
||||
use Espo\Core\Exceptions\NotFound;
|
||||
use Espo\ORM\EntityManager;
|
||||
|
||||
/**
|
||||
* GET /api/v1/JunctionData/CAIKnowledge/:knowledgeId/dokumentes
|
||||
*
|
||||
* Retrieves all documents linked to a knowledge entry with junction data.
|
||||
* Uses direct SQL JOIN for optimal performance.
|
||||
*/
|
||||
class GetDokumentes implements Action
|
||||
{
|
||||
public function __construct(
|
||||
private EntityManager $entityManager
|
||||
) {}
|
||||
|
||||
public function process(Request $request): Response
|
||||
{
|
||||
$knowledgeId = $request->getRouteParam('knowledgeId');
|
||||
|
||||
if (!$knowledgeId) {
|
||||
throw new BadRequest('Knowledge ID is required');
|
||||
}
|
||||
|
||||
// Validate entity exists
|
||||
$knowledge = $this->entityManager->getEntityById('CAIKnowledge', $knowledgeId);
|
||||
if (!$knowledge) {
|
||||
throw new NotFound('Knowledge entry not found');
|
||||
}
|
||||
|
||||
$pdo = $this->entityManager->getPDO();
|
||||
|
||||
// Direct SQL with JOIN - much faster than multiple API calls!
|
||||
$sql = "
|
||||
SELECT
|
||||
j.id as junctionId,
|
||||
j.c_a_i_knowledge_id as cAIKnowledgeId,
|
||||
j.c_dokumente_id as cDokumenteId,
|
||||
j.ai_document_id as aiDocumentId,
|
||||
j.syncstatus,
|
||||
j.last_sync as lastSync,
|
||||
d.id as documentId,
|
||||
d.name as documentName,
|
||||
d.blake3hash as blake3hash,
|
||||
d.created_at as documentCreatedAt,
|
||||
d.modified_at as documentModifiedAt
|
||||
FROM c_a_i_knowledge_dokumente j
|
||||
INNER JOIN c_dokumente d ON j.c_dokumente_id = d.id
|
||||
WHERE j.c_a_i_knowledge_id = :knowledgeId
|
||||
AND j.deleted = 0
|
||||
AND d.deleted = 0
|
||||
ORDER BY j.id DESC
|
||||
";
|
||||
|
||||
$sth = $pdo->prepare($sql);
|
||||
$sth->execute(['knowledgeId' => $knowledgeId]);
|
||||
|
||||
$results = $sth->fetchAll(\PDO::FETCH_ASSOC);
|
||||
|
||||
return ResponseComposer::json([
|
||||
'total' => count($results),
|
||||
'list' => $results
|
||||
]);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**3. Action Class für UPDATE**
|
||||
|
||||
**Datei:** `custom/Espo/Custom/Api/JunctionData/UpdateJunction.php`
|
||||
|
||||
```php
|
||||
<?php
|
||||
|
||||
namespace Espo\Custom\Api\JunctionData;
|
||||
|
||||
use Espo\Core\Api\Action;
|
||||
use Espo\Core\Api\Request;
|
||||
use Espo\Core\Api\Response;
|
||||
use Espo\Core\Api\ResponseComposer;
|
||||
use Espo\Core\Exceptions\BadRequest;
|
||||
use Espo\Core\Exceptions\NotFound;
|
||||
use Espo\ORM\EntityManager;
|
||||
|
||||
/**
|
||||
* PUT /api/v1/JunctionData/CAIKnowledge/:knowledgeId/dokumentes/:documentId
|
||||
*
|
||||
* Updates junction table columns without triggering entity hooks.
|
||||
*/
|
||||
class UpdateJunction implements Action
|
||||
{
|
||||
public function __construct(
|
||||
private EntityManager $entityManager
|
||||
) {}
|
||||
|
||||
public function process(Request $request): Response
|
||||
{
|
||||
$knowledgeId = $request->getRouteParam('knowledgeId');
|
||||
$documentId = $request->getRouteParam('documentId');
|
||||
$data = $request->getParsedBody();
|
||||
|
||||
if (!$knowledgeId || !$documentId) {
|
||||
throw new BadRequest('Knowledge ID and Document ID required');
|
||||
}
|
||||
|
||||
$pdo = $this->entityManager->getPDO();
|
||||
|
||||
// Dynamic UPDATE - only fields provided in request body
|
||||
$setClauses = [];
|
||||
$params = [
|
||||
'knowledgeId' => $knowledgeId,
|
||||
'documentId' => $documentId
|
||||
];
|
||||
|
||||
if (isset($data->aiDocumentId)) {
|
||||
$setClauses[] = "ai_document_id = :aiDocumentId";
|
||||
$params['aiDocumentId'] = $data->aiDocumentId;
|
||||
}
|
||||
|
||||
if (isset($data->syncstatus)) {
|
||||
$allowedStatuses = ['new', 'unclean', 'synced', 'failed', 'unsupported'];
|
||||
if (!in_array($data->syncstatus, $allowedStatuses)) {
|
||||
throw new BadRequest('Invalid syncstatus. Allowed: ' . implode(', ', $allowedStatuses));
|
||||
}
|
||||
$setClauses[] = "syncstatus = :syncstatus";
|
||||
$params['syncstatus'] = $data->syncstatus;
|
||||
}
|
||||
|
||||
if (isset($data->lastSync)) {
|
||||
$setClauses[] = "last_sync = :lastSync";
|
||||
$params['lastSync'] = $data->lastSync;
|
||||
} elseif (isset($data->updateLastSync) && $data->updateLastSync === true) {
|
||||
$setClauses[] = "last_sync = NOW()";
|
||||
}
|
||||
|
||||
if (empty($setClauses)) {
|
||||
throw new BadRequest('No fields to update');
|
||||
}
|
||||
|
||||
$sql = "
|
||||
UPDATE c_a_i_knowledge_dokumente
|
||||
SET " . implode(', ', $setClauses) . "
|
||||
WHERE c_a_i_knowledge_id = :knowledgeId
|
||||
AND c_dokumente_id = :documentId
|
||||
AND deleted = 0
|
||||
";
|
||||
|
||||
$sth = $pdo->prepare($sql);
|
||||
$sth->execute($params);
|
||||
|
||||
if ($sth->rowCount() === 0) {
|
||||
throw new NotFound('Junction entry not found or no changes made');
|
||||
}
|
||||
|
||||
// Return updated entry
|
||||
return ResponseComposer::json($this->getJunctionEntry($knowledgeId, $documentId));
|
||||
}
|
||||
|
||||
private function getJunctionEntry(string $knowledgeId, string $documentId): array
|
||||
{
|
||||
$pdo = $this->entityManager->getPDO();
|
||||
|
||||
$sql = "
|
||||
SELECT
|
||||
id as junctionId,
|
||||
c_a_i_knowledge_id as cAIKnowledgeId,
|
||||
c_dokumente_id as cDokumenteId,
|
||||
ai_document_id as aiDocumentId,
|
||||
syncstatus,
|
||||
last_sync as lastSync
|
||||
FROM c_a_i_knowledge_dokumente
|
||||
WHERE c_a_i_knowledge_id = :knowledgeId
|
||||
AND c_dokumente_id = :documentId
|
||||
AND deleted = 0
|
||||
";
|
||||
|
||||
$sth = $pdo->prepare($sql);
|
||||
$sth->execute([
|
||||
'knowledgeId' => $knowledgeId,
|
||||
'documentId' => $documentId
|
||||
]);
|
||||
|
||||
$result = $sth->fetch(\PDO::FETCH_ASSOC);
|
||||
|
||||
if (!$result) {
|
||||
throw new NotFound('Junction entry not found');
|
||||
}
|
||||
|
||||
return $result;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Verwendung
|
||||
|
||||
**GET: Alle Dokumente mit Junction-Daten**
|
||||
```bash
|
||||
curl -X GET "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/69b1b03582bb6e2da/dokumentes" \
|
||||
-H "X-Api-Key: e53def10eea27b92a6cd00f40a3e09a4"
|
||||
```
|
||||
|
||||
**PUT: Junction-Spalten aktualisieren**
|
||||
```bash
|
||||
curl -X PUT "http://localhost:8080/api/v1/JunctionData/CAIKnowledge/69b1b03582bb6e2da/dokumentes/69a68b556a39771bf" \
|
||||
-H "X-Api-Key: e53def10eea27b92a6cd00f40a3e09a4" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"aiDocumentId": "EXTERNAL-AI-123",
|
||||
"syncstatus": "synced",
|
||||
"updateLastSync": true
|
||||
}'
|
||||
```
|
||||
|
||||
#### Best Practices
|
||||
|
||||
✅ **DO:**
|
||||
- Constructor Property Promotion (`private EntityManager $entityManager`)
|
||||
- Prepared Statements IMMER (`$pdo->prepare()` + `execute()`)
|
||||
- Validierung BEVOR DB-Operations
|
||||
- Spezifische Exceptions (`BadRequest`, `NotFound`, `Forbidden`)
|
||||
- PHPDoc mit Endpoint-Beschreibung
|
||||
- `snake_case` für DB-Spaltennamen beachten!
|
||||
- Cache IMMER löschen nach routes.json Änderungen
|
||||
|
||||
❌ **DON'T:**
|
||||
- Raw SQL ohne Prepared Statements (SQL Injection!)
|
||||
- Vergessen `deleted = 0` zu prüfen
|
||||
- Camel Case für DB-Spalten annonehmen (DB verwendet snake_case!)
|
||||
- Entity-Methods auf routes.json Änderungen verzichten
|
||||
- ResponseComposer::json() vergessen
|
||||
- Controller-Methode für neue Projekte (deprecated!)
|
||||
|
||||
#### Vorteile gegenüber Standard API
|
||||
|
||||
| Feature | Standard Junction API | Custom routes.json API |
|
||||
|---------|----------------------|------------------------|
|
||||
| JOINs | ❌ Mehrere Calls nötig | ✅ Ein Call mit JOIN |
|
||||
| Performance | ⚠️ Langsam bei vielen Records | ✅ Optimiert mit direktem SQL |
|
||||
| ACL-Probleme | ❌ Oft 403 Forbidden | ✅ Keine ACL-Issues |
|
||||
| Hooks | ✅ Werden ausgelöst | ❌ Werden umgangen |
|
||||
| Flexibilität | ⚠️ Eingeschränkt | ✅ Volle SQL-Kontrolle |
|
||||
| Wartbarkeit | ✅ Standard-Konformität | ⚠️ Custom Code |
|
||||
|
||||
#### Typische Fehler
|
||||
|
||||
**1. routes.json nicht gefunden**
|
||||
```
|
||||
❌ custom/Espo/Custom/Resources/metadata/app/api.json
|
||||
✅ custom/Espo/Custom/Resources/routes.json
|
||||
```
|
||||
|
||||
**2. Cache nicht gelöscht**
|
||||
```bash
|
||||
# PFLICHT nach routes.json Änderungen!
|
||||
docker exec espocrm php clear_cache.php
|
||||
docker exec espocrm php rebuild.php
|
||||
```
|
||||
|
||||
**3. Falsche Spalten-Namen**
|
||||
```php
|
||||
❌ j.lastSync // CamelCase (falsch!)
|
||||
✅ j.last_sync // snake_case (richtig!)
|
||||
```
|
||||
|
||||
**4. File Permissions falsch**
|
||||
```bash
|
||||
# Alle Custom-Dateien müssen www-data:www-data gehören
|
||||
chown -R www-data:www-data custom/Espo/Custom/Api/
|
||||
```
|
||||
|
||||
**5. Namespace-Fehler**
|
||||
```json
|
||||
❌ "actionClassName": "Espo\Custom\Api\MyAction"
|
||||
✅ "actionClassName": "Espo\\Custom\\Api\\MyAction"
|
||||
```
|
||||
|
||||
#### Debugging
|
||||
|
||||
**Check routes cache:**
|
||||
```bash
|
||||
docker exec espocrm cat data/cache/application/routes.php | grep -i "YourRoute"
|
||||
```
|
||||
|
||||
**Check logs:**
|
||||
```bash
|
||||
docker exec espocrm tail -100 data/logs/espo.log | grep -i "error\|exception"
|
||||
```
|
||||
|
||||
**Test mit curl verbose:**
|
||||
```bash
|
||||
curl -v "http://localhost:8080/api/v1/YourEndpoint" \
|
||||
-H "X-Api-Key: your-key" 2>&1 | head -30
|
||||
```
|
||||
|
||||
**Siehe:** `custom/docs/API_ENDPOINTS.md` für vollständige Beispiele
|
||||
|
||||
---
|
||||
|
||||
## Hook-Entwicklung
|
||||
|
||||
### Überblick
|
||||
|
||||
@@ -1,790 +0,0 @@
|
||||
# Many-to-Many Junction-Tabelle mit additionalColumns - Testergebnisse
|
||||
|
||||
**Version:** 2.0
|
||||
**Datum:** 11. März 2026
|
||||
**Status:** ✅ VOLLSTÄNDIG ERFOLGREICH mit UI-Integration
|
||||
|
||||
## ✅ VOLLSTÄNDIG ERFOLGREICH!
|
||||
|
||||
**UPDATE (März 2026):** Die Junction-Tabelle kann als eigene Entity via REST-API abgerufen werden! Seit EspoCRM 6.0.0 werden Junction-Tabellen automatisch als Entities verfügbar gemacht.
|
||||
|
||||
**NEU:** UI-Anzeige von Junction-Spalten via columnAttributeMap + notStorable Pattern!
|
||||
|
||||
## Zusammenfassung
|
||||
|
||||
Die Implementierung einer Many-to-Many-Beziehung mit zusätzlichen Feldern in der Junction-Tabelle wurde erfolgreich getestet und ist:
|
||||
- **vollständig funktionsfähig via REST-API**
|
||||
- **im UI anzeigbar via columnAttributeMap Pattern**
|
||||
- **automatisch aktualisierbar via Hooks**
|
||||
|
||||
## ✅ Was funktioniert
|
||||
|
||||
### 1. Datenbank-Schema
|
||||
**Status: VOLLSTÄNDIG FUNKTIONSFÄHIG**
|
||||
|
||||
Die Junction-Tabelle `c_a_i_collection_c_dokumente` wurde automatisch mit der zusätzlichen `sync_id`-Spalte erstellt:
|
||||
|
||||
```sql
|
||||
CREATE TABLE `c_a_i_collection_c_dokumente` (
|
||||
`id` bigint(20) NOT NULL AUTO_INCREMENT,
|
||||
`c_a_i_collections_id` varchar(17),
|
||||
`c_dokumente_id` varchar(17),
|
||||
`sync_id` varchar(255), ← Unser custom Feld!
|
||||
`deleted` tinyint(1) DEFAULT 0,
|
||||
PRIMARY KEY (`id`),
|
||||
UNIQUE KEY `UNIQ_C_A_I_COLLECTIONS_ID_C_DOKUMENTE_ID` (...)
|
||||
)
|
||||
```
|
||||
|
||||
### 2. Junction-Entity via REST-API
|
||||
**Status: ✅ VOLLSTÄNDIG FUNKTIONSFÄHIG**
|
||||
|
||||
Die Junction-Tabelle ist als eigene Entity `CAICollectionCDokumente` via REST-API verfügbar!
|
||||
|
||||
**Beispiel-Abruf:**
|
||||
```bash
|
||||
GET /api/v1/CAICollectionCDokumente?maxSize=10
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"total": 5,
|
||||
"list": [
|
||||
{
|
||||
"id": "6",
|
||||
"deleted": false,
|
||||
"cAICollectionsId": "testcol999",
|
||||
"cDokumenteId": "testdoc999",
|
||||
"syncId": "SYNC-TEST-999",
|
||||
"cAICollectionsName": null,
|
||||
"cDokumenteName": null
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**✅ Die `syncId` ist direkt in der API-Response enthalten!**
|
||||
|
||||
### 3. Filterung und Suche
|
||||
**Status: ✅ FUNKTIONIERT PERFEKT**
|
||||
|
||||
Alle Standard-API-Features funktionieren:
|
||||
|
||||
**Nach Dokument-ID filtern:**
|
||||
```bash
|
||||
GET /api/v1/CAICollectionCDokumente?where[0][type]=equals&where[0][attribute]=cDokumenteId&where[0][value]=doc123
|
||||
```
|
||||
|
||||
**Nach syncId suchen:**
|
||||
```bash
|
||||
GET /api/v1/CAICollectionCDokumente?where[0][type]=equals&where[0][attribute]=syncId&where[0][value]=SYNC-123
|
||||
```
|
||||
|
||||
**Felder selektieren:**
|
||||
```bash
|
||||
GET /api/v1/CAICollectionCDokumente?select=id,cDokumenteId,cAICollectionsId,syncId
|
||||
```
|
||||
|
||||
### 4. Konfiguration
|
||||
**Status: KORREKT IMPLEMENTIERT**
|
||||
|
||||
**Erforderliche Dateien:**
|
||||
|
||||
**1. Entity-Definition** (`entityDefs/CAICollectionCDokumente.json`):
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"id": {"type": "id", "dbType": "bigint", "autoincrement": true},
|
||||
"cAICollections": {"type": "link"},
|
||||
"cAICollectionsId": {"type": "varchar", "len": 17, "index": true},
|
||||
"cDokumente": {"type": "link"},
|
||||
"cDokumenteId": {"type": "varchar", "len": 17, "index": true},
|
||||
"syncId": {"type": "varchar", "len": 255, "isCustom": true},
|
||||
"deleted": {"type": "bool", "default": false}
|
||||
},
|
||||
"links": {
|
||||
"cAICollections": {
|
||||
"type": "belongsTo",
|
||||
"entity": "CAICollections"
|
||||
},
|
||||
"cDokumente": {
|
||||
"type": "belongsTo",
|
||||
"entity": "CDokumente"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**2. Scope-Definition** (`scopes/CAICollectionCDokumente.json`):
|
||||
```json
|
||||
{
|
||||
"entity": true,
|
||||
"type": "Base",
|
||||
"module": "Custom",
|
||||
"object": true,
|
||||
"isCustom": true,
|
||||
"tab": false,
|
||||
"acl": true,
|
||||
"disabled": false
|
||||
}
|
||||
```
|
||||
|
||||
**3. Controller** (`Controllers/CAICollectionCDokumente.php`):
|
||||
```php
|
||||
<?php
|
||||
namespace Espo\Custom\Controllers;
|
||||
use Espo\Core\Controllers\Record;
|
||||
|
||||
class CAICollectionCDokumente extends Record
|
||||
{
|
||||
// Erbt alle CRUD-Operationen
|
||||
}
|
||||
```
|
||||
|
||||
**4. Service** (`Services/CAICollectionCDokumente.php`):
|
||||
```php
|
||||
<?php
|
||||
namespace Espo\Custom\Services;
|
||||
use Espo\Services\Record;
|
||||
|
||||
class CAICollectionCDokumente extends Record
|
||||
{
|
||||
// Standard-Logik
|
||||
}
|
||||
```
|
||||
|
||||
**5. Many-to-Many-Beziehung in CDokumente.json:**
|
||||
```json
|
||||
"cAICollections": {
|
||||
"type": "hasMany",
|
||||
"entity": "CAICollections",
|
||||
"foreign": "cDokumente",
|
||||
"relationName": "cAICollectionCDokumente",
|
||||
"additionalColumns": {
|
||||
"syncId": {
|
||||
"type": "varchar",
|
||||
"len": 255
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**6. ACL-Berechtigungen:**
|
||||
Die Rolle muss Zugriff auf die Junction-Entity haben:
|
||||
```json
|
||||
{
|
||||
"CAICollectionCDokumente": {
|
||||
"create": "yes",
|
||||
"read": "all",
|
||||
"edit": "all",
|
||||
"delete": "all"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 💡 Verwendung
|
||||
|
||||
### Beispiel 1: Alle Verknüpfungen eines Dokuments abrufen
|
||||
|
||||
**Python:**
|
||||
```python
|
||||
import requests
|
||||
|
||||
response = requests.get(
|
||||
"https://your-crm.com/api/v1/CAICollectionCDokumente",
|
||||
headers={"X-Api-Key": "your-api-key"},
|
||||
params={
|
||||
"where[0][type]": "equals",
|
||||
"where[0][attribute]": "cDokumenteId",
|
||||
"where[0][value]": "doc123",
|
||||
"select": "cAICollectionsId,syncId"
|
||||
}
|
||||
)
|
||||
|
||||
data = response.json()
|
||||
for item in data['list']:
|
||||
print(f"Collection: {item['cAICollectionsId']}, SyncID: {item['syncId']}")
|
||||
```
|
||||
|
||||
**cURL:**
|
||||
```bash
|
||||
curl "https://your-crm.com/api/v1/CAICollectionCDokumente?where[0][type]=equals&where[0][attribute]=cDokumenteId&where[0][value]=doc123" \
|
||||
-H "X-Api-Key: your-api-key"
|
||||
```
|
||||
|
||||
### Beispiel 2: Dokument in Collection via syncId finden
|
||||
|
||||
```python
|
||||
response = requests.get(
|
||||
"https://your-crm.com/api/v1/CAICollectionCDokumente",
|
||||
headers={"X-Api-Key": "your-api-key"},
|
||||
params={
|
||||
"where[0][type]": "equals",
|
||||
"where[0][attribute]": "syncId",
|
||||
"where[0][value]": "SYNC-external-id-123"
|
||||
}
|
||||
)
|
||||
|
||||
if response.json()['list']:
|
||||
match = response.json()['list'][0]
|
||||
doc_id = match['cDokumenteId']
|
||||
col_id = match['cAICollectionsId']
|
||||
print(f"Found: Document {doc_id} in Collection {col_id}")
|
||||
```
|
||||
|
||||
### Beispiel 3: Neue Verknüpfung mit syncId erstellen
|
||||
|
||||
**Via Standard-API (POST):**
|
||||
```python
|
||||
# Erstelle Verknüpfung
|
||||
response = requests.post(
|
||||
"https://your-crm.com/api/v1/CAICollectionCDokumente",
|
||||
headers={"X-Api-Key": "your-api-key"},
|
||||
json={
|
||||
"cDokumenteId": "doc123",
|
||||
"cAICollectionsId": "col456",
|
||||
"syncId": "SYNC-2026-001"
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Beispiel 4: syncId aktualisieren
|
||||
|
||||
```python
|
||||
# Aktualisiere einen bestehenden Eintrag
|
||||
response = requests.put(
|
||||
f"https://your-crm.com/api/v1/CAICollectionCDokumente/{junction_id}",
|
||||
headers={"X-Api-Key": "your-api-key"},
|
||||
json={
|
||||
"syncId": "SYNC-UPDATED-002"
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## 📊 Test-Ergebnisse
|
||||
|
||||
| Feature | Status | Notizen |
|
||||
|---------|--------|---------|
|
||||
| Junction-Tabelle Erstellung | ✅ | Automatisch mit syncId-Spalte |
|
||||
| Junction-Entity via API | ✅ | Vollständig funktionsfähig |
|
||||
| syncId in API-Response | ✅ | Direkt verfügbar |
|
||||
| Filterung (where) | ✅ | Standard-API-Syntax |
|
||||
| Sortierung (orderBy) | ✅ | Funktioniert |
|
||||
| Paginierung (maxSize, offset) | ✅ | Funktioniert |
|
||||
| CREATE via API | ✅ | POST mit allen Feldern |
|
||||
| UPDATE via API | ✅ | PUT zum Ändern von syncId |
|
||||
| DELETE via API | ✅ | Standard-DELETE |
|
||||
| View-Darstellung | ❌ | Nicht empfohlen - verursacht 405 Fehler |
|
||||
|
||||
## ⚠️ UI-Panel Warnung
|
||||
|
||||
**WICHTIG:** additionalColumns sollten NICHT in Standard-Relationship-Panels angezeigt werden!
|
||||
|
||||
**Problem:**
|
||||
- Standard relationship panels versuchen inline-editing
|
||||
- Dies führt zu 405 Method Not Allowed Fehlern
|
||||
- additionalColumns sind nicht kompatibel mit Standard-Panel-Architektur
|
||||
|
||||
**Empfehlung:**
|
||||
- ✅ Nutze API-only Access Pattern
|
||||
- ✅ Vollständige CRUD via `/api/v1/CAICollectionCDokumente`
|
||||
- ❌ NICHT in CDokumente detail view als relationship panel anzeigen
|
||||
|
||||
## ✅ LÖSUNG: UI-Anzeige via columnAttributeMap + notStorable
|
||||
|
||||
**UPDATE (März 2026):** Es gibt eine Working-Solution für UI-Anzeige von Junction-Spalten!
|
||||
|
||||
**Pattern:** columnAttributeMap + notStorable Felder
|
||||
|
||||
### Konzept
|
||||
|
||||
1. **notStorable Felder** im Parent: Placeholder für Junction-Spalten
|
||||
2. **columnAttributeMap** in Links: Bidirektionales Mapping
|
||||
3. **Custom List Layouts**: Zeigt notStorable Felder an
|
||||
4. EspoCRM synchronisiert automatisch zwischen Junction-Table und notStorable Feldern
|
||||
|
||||
### Implementierung: CAdvowareAkten ↔ CDokumente
|
||||
|
||||
**CAdvowareAkten.json:**
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"dokumenteHnr": {
|
||||
"type": "int",
|
||||
"notStorable": true,
|
||||
"utility": true
|
||||
},
|
||||
"dokumenteSyncstatus": {
|
||||
"type": "enum",
|
||||
"options": ["new", "unclean", "synced", "failed"],
|
||||
"notStorable": true,
|
||||
"utility": true
|
||||
},
|
||||
"dokumenteLastSync": {
|
||||
"type": "datetime",
|
||||
"notStorable": true,
|
||||
"utility": true
|
||||
},
|
||||
"dokumentes": {
|
||||
"type": "linkMultiple",
|
||||
"columns": {
|
||||
"hnr": "advowareAktenHnr",
|
||||
"syncstatus": "advowareAktenSyncstatus",
|
||||
"lastSync": "advowareAktenLastSync"
|
||||
},
|
||||
"view": "views/fields/link-multiple-with-columns"
|
||||
}
|
||||
},
|
||||
"links": {
|
||||
"dokumentes": {
|
||||
"type": "hasMany",
|
||||
"entity": "CDokumente",
|
||||
"foreign": "advowareAktens",
|
||||
"relationName": "cAdvowareAktenDokumente",
|
||||
"additionalColumns": {
|
||||
"hnr": {"type": "int"},
|
||||
"syncstatus": {"type": "varchar", "len": 20},
|
||||
"lastSync": {"type": "datetime"}
|
||||
},
|
||||
"columnAttributeMap": {
|
||||
"hnr": "dokumenteHnr",
|
||||
"syncstatus": "dokumenteSyncstatus",
|
||||
"lastSync": "dokumenteLastSync"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**CDokumente.json (Foreign Side):**
|
||||
```json
|
||||
{
|
||||
"fields": {
|
||||
"advowareAktenHnr": {
|
||||
"type": "int",
|
||||
"notStorable": true,
|
||||
"utility": true,
|
||||
"layoutAvailabilityList": ["listForAdvowareAkten"]
|
||||
},
|
||||
"advowareAktenSyncstatus": {
|
||||
"type": "varchar",
|
||||
"notStorable": true,
|
||||
"utility": true,
|
||||
"layoutAvailabilityList": ["listForAdvowareAkten"]
|
||||
},
|
||||
"advowareAktenLastSync": {
|
||||
"type": "datetime",
|
||||
"notStorable": true,
|
||||
"utility": true,
|
||||
"layoutAvailabilityList": ["listForAdvowareAkten"]
|
||||
}
|
||||
},
|
||||
"links": {
|
||||
"advowareAktens": {
|
||||
"type": "hasMany",
|
||||
"entity": "CAdvowareAkten",
|
||||
"foreign": "dokumentes",
|
||||
"relationName": "cAdvowareAktenDokumente",
|
||||
"columnAttributeMap": {
|
||||
"hnr": "advowareAktenHnr",
|
||||
"syncstatus": "advowareAktenSyncstatus",
|
||||
"lastSync": "advowareAktenLastSync"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Custom List Layout (layouts/CDokumente/listForAdvowareAkten.json):**
|
||||
```json
|
||||
[
|
||||
{"name": "name", "width": 25},
|
||||
{"name": "advowareAktenHnr", "width": 10},
|
||||
{"name": "advowareAktenSyncstatus", "width": 12},
|
||||
{"name": "advowareAktenLastSync", "width": 15},
|
||||
{"name": "description", "width": 20}
|
||||
]
|
||||
```
|
||||
|
||||
**Bottom Panel (layouts/CAdvowareAkten/bottomPanelsDetail.json):**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"name": "dokumentes",
|
||||
"label": "Dokumente",
|
||||
"view": "views/record/panels/relationship",
|
||||
"layout": "listForAdvowareAkten",
|
||||
"index": 1
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Wie es funktioniert
|
||||
|
||||
1. **Lesen:** EspoCRM lädt Junction-Spalten via RDB und mapped sie zu notStorable Feldern
|
||||
2. **Anzeigen:** Custom List Layout zeigt notStorable Felder an
|
||||
3. **Schreiben:** Updates via Hooks mit `updateColumns()`
|
||||
4. **Bidirektional:** columnAttributeMap muss auf beiden Seiten existieren
|
||||
|
||||
### Beispiel: Hook für Auto-Update
|
||||
|
||||
```php
|
||||
<?php
|
||||
namespace Espo\Custom\Hooks\CAdvowareAkten;
|
||||
|
||||
use Espo\ORM\Entity;
|
||||
use Espo\Core\Hook\Hook\AfterRelate;
|
||||
|
||||
class DokumenteSyncStatus implements AfterRelate
|
||||
{
|
||||
public function __construct(
|
||||
private \Espo\ORM\EntityManager $entityManager
|
||||
) {}
|
||||
|
||||
public function afterRelate(
|
||||
Entity $entity,
|
||||
string $relationName,
|
||||
Entity $foreignEntity,
|
||||
array $columnData,
|
||||
\Espo\ORM\Repository\Option\RelateOptions $options
|
||||
): void {
|
||||
if ($relationName !== 'dokumentes') {
|
||||
return;
|
||||
}
|
||||
|
||||
// Setze Junction-Spalten via updateColumns()
|
||||
$repository = $this->entityManager->getRDBRepository('CAdvowareAkten');
|
||||
$repository->getRelation($entity, 'dokumentes')->updateColumns(
|
||||
$foreignEntity,
|
||||
[
|
||||
'syncstatus' => 'new',
|
||||
'lastSync' => null
|
||||
]
|
||||
);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Vorteile dieser Lösung
|
||||
|
||||
✅ **UI-Anzeige**: Junction-Spalten sichtbar in Relationship-Panels
|
||||
✅ **Kein 405 Fehler**: Read-only Darstellung vermeidet Inline-Edit-Probleme
|
||||
✅ **API-Kompatibel**: Funktioniert parallel zur Junction-Entity-API
|
||||
✅ **Bidirektional**: Funktioniert von beiden Seiten der Beziehung
|
||||
✅ **Hook-Integration**: Updates via Hooks möglich
|
||||
|
||||
### Einschränkungen
|
||||
|
||||
⚠️ **notStorable = Read-only in UI**: Keine direkte Bearbeitung im Panel
|
||||
⚠️ **Updates via Hooks**: Änderungen müssen über Hooks oder API erfolgen
|
||||
⚠️ **layoutAvailabilityList**: Foreign-Side-Felder nur in Custom Layouts sichtbar
|
||||
|
||||
## 🎯 Fazit
|
||||
|
||||
Die **Junction-Tabelle mit `additionalColumns` ist vollständig via REST-API nutzbar**!
|
||||
|
||||
**Vorteile:**
|
||||
- ✅ Keine Custom-Endpoints nötig
|
||||
- ✅ Standard-API-Features (Filter, Sort, Pagination)
|
||||
- ✅ CRUD-Operationen vollständig unterstützt
|
||||
- ✅ `syncId` ist direkt in der Response
|
||||
- ✅ Einfache Integration in externe Systeme
|
||||
- ✅ API-only Pattern verhindert 405-Fehler
|
||||
|
||||
**Einschränkungen:**
|
||||
- ⚠️ UI-Darstellung in Standard-Relationship-Panels verursacht 405 Fehler
|
||||
- ⚠️ additionalColumns nur über Junction-Entity-API zugänglich
|
||||
- ⚠️ Standard relationship endpoints (z.B. GET /api/v1/CDokumente/{id}/cAICollections) geben additionalColumns NICHT zurück
|
||||
|
||||
**Best Practice:**
|
||||
1. ✅ Junction Entity als API-Endpoint nutzen (`/api/v1/CAICollectionCDokumente`)
|
||||
2. ✅ Keine UI-Panels für Junction-Relationships mit additionalColumns
|
||||
3. ✅ API-Integration für externe Systeme (Middleware, KI, etc.)
|
||||
4. ✅ Bei Bedarf: Separate Management-UI für Junction Entity (ohne Relationship-Panel)
|
||||
|
||||
**Wichtig:**
|
||||
1. Controller und Service erstellen
|
||||
2. Scope-Definition anlegen
|
||||
3. Entity-Definition mit korrekten Feldtypen
|
||||
4. ACL-Rechte für die Junction-Entity setzen
|
||||
5. Cache löschen und rebuild
|
||||
6. **NICHT** als Relationship-Panel in UI anzeigen (→ 405 Fehler)
|
||||
|
||||
## 📁 Dateien
|
||||
|
||||
Die Implementierung befindet sich in:
|
||||
- `/custom/Espo/Custom/Resources/metadata/entityDefs/CAICollectionCDokumente.json`
|
||||
- `/custom/Espo/Custom/Resources/metadata/scopes/CAICollectionCDokumente.json`
|
||||
- `/custom/Espo/Custom/Controllers/CAICollectionCDokumente.php`
|
||||
- `/custom/Espo/Custom/Services/CAICollectionCDokumente.php`
|
||||
- `/custom/Espo/Custom/Resources/metadata/entityDefs/CDokumente.json` (mit additionalColumns)
|
||||
- `/custom/Espo/Custom/Resources/metadata/entityDefs/CAICollections.json`
|
||||
|
||||
Datenbank-Tabelle:
|
||||
- `c_a_i_collection_c_dokumente`
|
||||
|
||||
---
|
||||
|
||||
**Erstellt:** 9. März 2026
|
||||
**Getestet mit:** EspoCRM 9.3.2 (MariaDB 12.2.2, PHP 8.2.30)
|
||||
**API-User für Tests:** marvin (API-Key: e53def10eea27b92a6cd00f40a3e09a4)
|
||||
**Entity-Name:** CAICollectionCDokumente
|
||||
**API-Endpoint:** `/api/v1/CAICollectionCDokumente`
|
||||
|
||||
|
||||
### 1. Datenbank-Schema
|
||||
**Status: VOLLSTÄNDIG FUNKTIONSFÄHIG**
|
||||
|
||||
Die Junction-Tabelle `c_a_i_collection_c_dokumente` wurde automatisch mit der zusätzlichen `sync_id`-Spalte erstellt:
|
||||
|
||||
```sql
|
||||
CREATE TABLE `c_a_i_collection_c_dokumente` (
|
||||
`id` bigint(20) NOT NULL AUTO_INCREMENT,
|
||||
`c_a_i_collections_id` varchar(17),
|
||||
`c_dokumente_id` varchar(17),
|
||||
`sync_id` varchar(255), ← Unser custom Feld!
|
||||
`deleted` tinyint(1) DEFAULT 0,
|
||||
PRIMARY KEY (`id`),
|
||||
UNIQUE KEY `UNIQ_C_A_I_COLLECTIONS_ID_C_DOKUMENTE_ID` (...)
|
||||
)
|
||||
```
|
||||
|
||||
### 2. Konfiguration
|
||||
**Status: KORREKT IMPLEMENTIERT**
|
||||
|
||||
Die Beziehung wurde in beiden Entity-Definitionen konfiguriert:
|
||||
|
||||
**CDokumente.json:**
|
||||
```json
|
||||
"cAICollections": {
|
||||
"type": "hasMany",
|
||||
"entity": "CAICollections",
|
||||
"foreign": "cDokumente",
|
||||
"relationName": "cAICollectionCDokumente",
|
||||
"additionalColumns": {
|
||||
"syncId": {
|
||||
"type": "varchar",
|
||||
"len": 255
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**CAICollections.json:**
|
||||
```json
|
||||
"cDokumente": {
|
||||
"type": "hasMany",
|
||||
"entity": "CDokumente",
|
||||
"foreign": "cAICollections",
|
||||
"relationName": "cAICollectionCDokumente"
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Datenspeicherung
|
||||
**Status: FUNKTIONIERT**
|
||||
|
||||
Die `syncId` kann in der Datenbank gespeichert werden:
|
||||
- ✅ Via direktes SQL-INSERT/UPDATE
|
||||
- ✅ Via interne EspoCRM ORM-API (EntityManager)
|
||||
- ✅ Daten werden korrekt persistiert
|
||||
|
||||
### 4. View-Darstellung
|
||||
**Status: ⚠️ NICHT EMPFOHLEN (API-ONLY PATTERN)**
|
||||
|
||||
**Problem:** Standard EspoCRM Relationship-Panels versuchen inline-editing von Feldern. Bei additionalColumns führt dies zu **405 Method Not Allowed** Fehlern, da die Standard-Panel-UI nicht mit dem Junction-Entity-Pattern kompatibel ist.
|
||||
|
||||
**Versucht & Fehlgeschlagen:**
|
||||
1. ❌ Direct display of syncId in relationship panel layout → 405 Fehler
|
||||
2. ❌ Custom View mit actionEditLinkData → Blank views, dann weiter 405 Fehler
|
||||
3. ❌ Simplified relationship layout ohne syncId → 405 Fehler blieben bestehen
|
||||
|
||||
**ROOT CAUSE:** Standard relationship panels senden HTTP-Requests die nicht mit Junction-Entity-Architektur übereinstimmen. additionalColumns erfordern spezielle Behandlung die nicht durch Standard-UI bereitgestellt wird.
|
||||
|
||||
**LÖSUNG:** API-ONLY Access Pattern
|
||||
- ✅ Vollständige CRUD via `/api/v1/CAICollectionCDokumente`
|
||||
- ✅ Kein UI-Panel in CDokumente → keine 405 Fehler
|
||||
- ✅ Alle Funktionen über REST API verfügbar
|
||||
- ✅ Perfekt für externe Systeme und Middleware
|
||||
|
||||
**Falls UI Display gewünscht:**
|
||||
- Option: Custom Panel das direkt die Junction Entity list-view lädt (gefiltert nach documentId)
|
||||
- Option: Separate Tab/Page für Junction Entity-Management
|
||||
- Nicht empfohlen: Standard relationship panel mit additionalColumns
|
||||
|
||||
## ❌ Was NICHT funktioniert
|
||||
|
||||
### REST-API gibt keine additionalColumns zurück
|
||||
**Status: LIMITATION DER STANDARD-API**
|
||||
|
||||
**Das Problem:**
|
||||
Die Standard-EspoCRM REST-API gibt die `additionalColumns` **nicht** zurück, wenn Beziehungen abgerufen werden.
|
||||
|
||||
**Getestete Szenarien:**
|
||||
1. ❌ Standard GET-Request: `GET /api/v1/CDokumente/{id}/cAICollections` → keine `syncId` in Response
|
||||
2. ❌ Mit Query-Parametern (select, additionalColumns, columns, etc.) → keine `syncId`
|
||||
3. ❌ POST mit columns-Parameter beim Verknüpfen → wird nicht gespeichert
|
||||
|
||||
**Verifiziert:**
|
||||
```bash
|
||||
# syncId ist in DB:
|
||||
SELECT * FROM c_a_i_collection_c_dokumente;
|
||||
# → sync_id = 'SYNC-20260309-220416'
|
||||
|
||||
# Aber API-Response enthält sie nicht:
|
||||
GET /api/v1/CDokumente/{id}/cAICollections
|
||||
# → {"list": [{"id": "...", "name": "...", ...}]} # Keine syncId!
|
||||
```
|
||||
|
||||
## 💡 Lösungen & Workarounds
|
||||
|
||||
### Option 1: Interne PHP-API verwenden (Empfohlen)
|
||||
Verwende die interne EspoCRM-API für den Zugriff auf `additionalColumns`:
|
||||
|
||||
```php
|
||||
$entityManager = $container->get('entityManager');
|
||||
$doc = $entityManager->getEntity('CDokumente', $docId);
|
||||
$repository = $entityManager->getRDBRepository('CDokumente');
|
||||
$relation = $repository->getRelation($doc, 'cAICollections');
|
||||
|
||||
// Lade verknüpfte Collections
|
||||
$collections = $relation->find();
|
||||
|
||||
// Hole additionalColumns
|
||||
foreach ($collections as $col) {
|
||||
$relationData = $relation->getColumnAttributes($col, ['syncId']);
|
||||
$syncId = $relationData['syncId'] ?? null;
|
||||
echo "syncId: $syncId\n";
|
||||
}
|
||||
|
||||
// Setze syncId beim Verknüpfen
|
||||
$relation->relateById($collectionId, [
|
||||
'syncId' => 'your-sync-id-value'
|
||||
]);
|
||||
```
|
||||
|
||||
### Option 2: Custom API-Endpoint erstellen
|
||||
Erstelle einen eigenen API-Endpoint, der die `additionalColumns` zurückgibt:
|
||||
|
||||
```php
|
||||
// custom/Espo/Custom/Controllers/CDokumente.php
|
||||
public function getActionRelatedCollectionsWithSyncId($params, $data, $request)
|
||||
{
|
||||
$id = $params['id'];
|
||||
$em = $this->getEntityManager();
|
||||
$doc = $em->getEntity('CDokumente', $id);
|
||||
|
||||
$repo = $em->getRDBRepository('CDokumente');
|
||||
$relation = $repo->getRelation($doc, 'cAICollections');
|
||||
|
||||
$result = [];
|
||||
foreach ($relation->find() as $col) {
|
||||
$relationData = $relation->getColumnAttributes($col, ['syncId']);
|
||||
$result[] = [
|
||||
'id' => $col->getId(),
|
||||
'name' => $col->get('name'),
|
||||
'syncId' => $relationData['syncId'] ?? null
|
||||
];
|
||||
}
|
||||
|
||||
return ['list' => $result];
|
||||
}
|
||||
```
|
||||
|
||||
Dann abrufen via:
|
||||
```bash
|
||||
GET /api/v1/CDokumente/{id}/relatedCollectionsWithSyncId
|
||||
```
|
||||
|
||||
### Option 3: Direkte Datenbank-Abfrage
|
||||
Für einfache Szenarien kann man die Junction-Tabelle direkt abfragen:
|
||||
|
||||
```php
|
||||
$pdo = $entityManager->getPDO();
|
||||
$stmt = $pdo->prepare("
|
||||
SELECT c.*, j.sync_id
|
||||
FROM c_a_i_collections c
|
||||
JOIN c_a_i_collection_c_dokumente j
|
||||
ON c.id = j.c_a_i_collections_id
|
||||
WHERE j.c_dokumente_id = ?
|
||||
AND j.deleted = 0
|
||||
AND c.deleted = 0
|
||||
");
|
||||
$stmt->execute([$docId]);
|
||||
$results = $stmt->fetchAll(PDO::FETCH_ASSOC);
|
||||
```
|
||||
|
||||
### Option 4: Formulas für automatische Synchronisation
|
||||
Nutze EspoCRM-Formulas um `syncId` zu setzen:
|
||||
|
||||
```
|
||||
// In CDokumente.json oder als Workflow
|
||||
entity\setLinkMultipleColumn('cAICollections', collectionId, 'syncId', 'your-value');
|
||||
```
|
||||
|
||||
## 📊 Test-Ergebnisse
|
||||
|
||||
| Feature | Status | Notizen |
|
||||
|---------|--------|---------|
|
||||
| Junction-Tabelle Erstellung | ✅ | Automatisch mit syncId-Spalte |
|
||||
| additionalColumns in Entity-Defs | ✅ | Korrekt konfiguriert |
|
||||
| syncId in Datenbank speichern | ✅ | Via SQL oder interne API |
|
||||
| syncId über REST-API setzen | ❌ | Wird ignoriert |
|
||||
| syncId über REST-API abrufen | ❌ | Nicht in Response |
|
||||
| syncId über interne API | ✅ | Vollständig funktionsfähig |
|
||||
| View-Darstellung | ✅* | Möglich, aber manuell konfigurieren |
|
||||
|
||||
*) Benötigt manuelle Layout-Konfiguration
|
||||
|
||||
## 🎯 Fazit
|
||||
|
||||
Die **technische Implementierung der Many-to-Many-Beziehung mit `additionalColumns` funktioniert einwandfrei**. Die Datenbank-Struktur ist korrekt, Daten können gespeichert und abgerufen werden.
|
||||
|
||||
**Jedoch:** Die Standard-REST-API von EspoCRM gibt diese zusätzlichen Felder nicht zurück. Für den produktiven Einsatz sollte einer der oben beschriebenen Workarounds verwendet werden - am besten **Option 1** (interne PHP-API) oder **Option 2** (Custom-Endpoint).
|
||||
|
||||
## 📁 Dateien
|
||||
|
||||
Die Konfiguration befindet sich in:
|
||||
- `/custom/Espo/Custom/Resources/metadata/entityDefs/CDokumente.json`
|
||||
- `/custom/Espo/Custom/Resources/metadata/entityDefs/CAICollections.json`
|
||||
|
||||
Datenbank-Tabelle:
|
||||
- `c_a_i_collection_c_dokumente`
|
||||
|
||||
## 🔧 Verwendung
|
||||
|
||||
### Beispiel: Dokument in Collection mit Sync-ID einfügen (PHP)
|
||||
|
||||
```php
|
||||
$entityManager = $container->get('entityManager');
|
||||
|
||||
// Entities laden
|
||||
$doc = $entityManager->getEntity('CDokumente', $docId);
|
||||
$collection = $entityManager->getEntity('CAICollections', $collectionId);
|
||||
|
||||
// Verknüpfen mit syncId
|
||||
$repo = $entityManager->getRDBRepository('CDokumente');
|
||||
$relation = $repo->getRelation($doc, 'cAICollections');
|
||||
$relation->relateById($collectionId, [
|
||||
'syncId' => 'my-unique-sync-id-123'
|
||||
]);
|
||||
|
||||
// SyncId auslesen
|
||||
$relationData = $relation->getColumnAttributes($collection, ['syncId']);
|
||||
echo $relationData['syncId']; // 'my-unique-sync-id-123'
|
||||
```
|
||||
|
||||
### Beispiel: Dokument in Collection finden via Sync-ID
|
||||
|
||||
```sql
|
||||
SELECT c_dokumente_id, c_a_i_collections_id, sync_id
|
||||
FROM c_a_i_collection_c_dokumente
|
||||
WHERE sync_id = 'my-unique-sync-id-123'
|
||||
AND deleted = 0;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Erstellt:** 9. März 2026
|
||||
**Getestet mit:** EspoCRM (MariaDB 12.2.2, PHP 8.2.30)
|
||||
**API-User für Tests:** marvin (API-Key: e53def10eea27b92a6cd00f40a3e09a4)
|
||||
Reference in New Issue
Block a user