Vollständige Advoware-EspoCRM Integration implementiert
- Advoware API Proxy für alle HTTP-Methoden (GET/POST/PUT/DELETE) - EspoCRM Webhook-Receiver für Beteiligte CRUD-Operationen - Redis-basierte Deduplikation für Webhook-Events - Event-driven Synchronisations-Handler (Placeholder) - Detaillierte README.md mit Setup und Verwendungsanleitung - Fehlerbehebungen für Context-Attribute und Redis-Verbindungen
This commit is contained in:
root
225
bitbylaw/README.md
Normal file
225
bitbylaw/README.md
Normal file
@@ -0,0 +1,225 @@
|
||||
# Motia Advoware-EspoCRM Integration
|
||||
|
||||
Dieses Projekt implementiert eine robuste Integration zwischen Advoware und EspoCRM über das Motia-Framework. Es bietet eine vollständige API-Proxy für Advoware und Webhook-Handler für EspoCRM, um Änderungen an Beteiligte-Entitäten zu synchronisieren.
|
||||
|
||||
## Übersicht
|
||||
|
||||
Das System besteht aus drei Hauptkomponenten:
|
||||
|
||||
1. **Advoware API Proxy**: Vollständige REST-API-Proxy für alle HTTP-Methoden (GET, POST, PUT, DELETE)
|
||||
2. **EspoCRM Webhook Receiver**: Empfängt Webhooks für CRUD-Operationen auf Beteiligte-Entitäten
|
||||
3. **Event-Driven Sync**: Verarbeitet Synchronisationsereignisse mit Redis-basierter Deduplikation
|
||||
|
||||
## Architektur
|
||||
|
||||
### Komponenten
|
||||
|
||||
- **Motia Framework**: Event-driven Backend-Orchestrierung
|
||||
- **Python Steps**: Asynchrone Verarbeitung mit aiohttp und redis-py
|
||||
- **Advoware API Client**: Authentifizierte API-Kommunikation mit Token-Management
|
||||
- **Redis**: Deduplikation von Webhook-Events und Caching
|
||||
- **EspoCRM Integration**: Webhook-Handler für create/update/delete Operationen
|
||||
|
||||
### Datenfluss
|
||||
|
||||
```
|
||||
EspoCRM Webhook → VMH Webhook Receiver → Redis Deduplication → Event Emission → Sync Handler
|
||||
Advoware API → Proxy Steps → Response
|
||||
```
|
||||
|
||||
## Setup
|
||||
|
||||
### Voraussetzungen
|
||||
|
||||
- Python 3.13+
|
||||
- Node.js 18+
|
||||
- Redis Server
|
||||
- Motia CLI
|
||||
|
||||
### Installation
|
||||
|
||||
1. **Repository klonen und Dependencies installieren:**
|
||||
```bash
|
||||
cd /opt/motia-app/bitbylaw
|
||||
npm install
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
2. **Umgebungsvariablen konfigurieren:**
|
||||
Erstellen Sie eine `.env`-Datei mit folgenden Variablen:
|
||||
```env
|
||||
ADVOWARE_BASE_URL=https://api.advoware.com
|
||||
ADVOWARE_USERNAME=your_username
|
||||
ADVOWARE_PASSWORD=your_password
|
||||
REDIS_URL=redis://localhost:6379
|
||||
ESPOCRM_WEBHOOK_SECRET=your_webhook_secret
|
||||
```
|
||||
|
||||
3. **Redis starten:**
|
||||
```bash
|
||||
redis-server
|
||||
```
|
||||
|
||||
4. **Motia starten:**
|
||||
```bash
|
||||
motia start
|
||||
```
|
||||
|
||||
## Verwendung
|
||||
|
||||
### Advoware API Proxy
|
||||
|
||||
Die Proxy-Endpunkte spiegeln die Advoware-API wider:
|
||||
|
||||
- `GET /api/advoware/*` - Daten abrufen
|
||||
- `POST /api/advoware/*` - Neue Ressourcen erstellen
|
||||
- `PUT /api/advoware/*` - Ressourcen aktualisieren
|
||||
- `DELETE /api/advoware/*` - Ressourcen löschen
|
||||
|
||||
**Beispiel:**
|
||||
```bash
|
||||
curl -X GET "http://localhost:3000/api/advoware/employees"
|
||||
```
|
||||
|
||||
### EspoCRM Webhooks
|
||||
|
||||
Webhooks werden automatisch von EspoCRM gesendet für Änderungen an Beteiligte-Entitäten:
|
||||
|
||||
- **Create**: `/webhooks/vmh/beteiligte/create`
|
||||
- **Update**: `/webhooks/vmh/beteiligte/update`
|
||||
- **Delete**: `/webhooks/vmh/beteiligte/delete`
|
||||
|
||||
### Synchronisation
|
||||
|
||||
Die Synchronisation läuft event-driven ab:
|
||||
|
||||
1. Webhook-Events werden in Redis-Queues dedupliziert
|
||||
2. Events werden an den Sync-Handler emittiert
|
||||
3. Sync-Handler verarbeitet die Änderungen (aktuell Placeholder)
|
||||
|
||||
## Konfiguration
|
||||
|
||||
### Motia Workbench
|
||||
|
||||
Die Flows sind in `motia-workbench.json` definiert:
|
||||
|
||||
- `advoware-proxy`: API-Proxy-Flows
|
||||
- `vmh-webhook`: Webhook-Receiver-Flows
|
||||
- `beteiligte-sync`: Synchronisations-Flow
|
||||
|
||||
### Redis Keys
|
||||
|
||||
- `vmh:webhook:create`: Create-Event Queue
|
||||
- `vmh:webhook:update`: Update-Event Queue
|
||||
- `vmh:webhook:delete`: Delete-Event Queue
|
||||
|
||||
## Entwicklung
|
||||
|
||||
### Projektstruktur
|
||||
|
||||
```
|
||||
bitbylaw/
|
||||
├── steps/
|
||||
│ ├── advoware_proxy/ # API Proxy Steps
|
||||
│ │ ├── advoware_api_proxy_get_step.py
|
||||
│ │ ├── advoware_api_proxy_post_step.py
|
||||
│ │ ├── advoware_api_proxy_put_step.py
|
||||
│ │ └── advoware_api_proxy_delete_step.py
|
||||
│ └── vmh/
|
||||
│ ├── webhook/ # Webhook Receiver Steps
|
||||
│ │ ├── beteiligte_create_api_step.py
|
||||
│ │ ├── beteiligte_update_api_step.py
|
||||
│ │ └── beteiligte_delete_api_step.py
|
||||
│ └── beteiligte_sync_event_step.py # Sync Handler
|
||||
├── services/
|
||||
│ └── advoware.py # API Client
|
||||
├── config.py # Configuration
|
||||
├── motia-workbench.json # Flow Definitions
|
||||
├── package.json
|
||||
├── requirements.txt
|
||||
└── tsconfig.json
|
||||
```
|
||||
|
||||
### Testing
|
||||
|
||||
**API Proxy testen:**
|
||||
```bash
|
||||
curl -X GET "http://localhost:3000/api/advoware/employees"
|
||||
```
|
||||
|
||||
**Webhook simulieren:**
|
||||
```bash
|
||||
curl -X POST "http://localhost:3000/webhooks/vmh/beteiligte/create" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"id": "123", "name": "Test Beteiligte"}'
|
||||
```
|
||||
|
||||
### Logging
|
||||
|
||||
Alle Steps enthalten detaillierte Logging-Ausgaben für Debugging:
|
||||
|
||||
- API-Requests/Responses
|
||||
- Redis-Operationen
|
||||
- Event-Emission
|
||||
- Fehlerbehandlung
|
||||
|
||||
## Deployment
|
||||
|
||||
### Docker
|
||||
|
||||
```dockerfile
|
||||
FROM python:3.13-slim
|
||||
|
||||
WORKDIR /app
|
||||
COPY requirements.txt .
|
||||
RUN pip install -r requirements.txt
|
||||
|
||||
COPY . .
|
||||
EXPOSE 3000
|
||||
|
||||
CMD ["motia", "start"]
|
||||
```
|
||||
|
||||
### Production Setup
|
||||
|
||||
1. Redis Cluster für Hochverfügbarkeit
|
||||
2. Load Balancer für API-Endpunkte
|
||||
3. Monitoring für Sync-Operationen
|
||||
4. Backup-Strategie für Redis-Daten
|
||||
|
||||
## Fehlerbehebung
|
||||
|
||||
### Häufige Probleme
|
||||
|
||||
1. **Context Attribute Error**: Verwenden Sie `Config` statt `context.config`
|
||||
2. **Redis Connection Failed**: Überprüfen Sie Redis-URL und Netzwerkverbindung
|
||||
3. **Webhook Duplikate**: Redis-Deduplikation verhindert Mehrfachverarbeitung
|
||||
|
||||
### Logs überprüfen
|
||||
|
||||
```bash
|
||||
motia logs
|
||||
```
|
||||
|
||||
## Erweiterungen
|
||||
|
||||
### Geplante Features
|
||||
|
||||
- Vollständige EspoCRM-API-Integration im Sync-Handler
|
||||
- Retry-Logic für fehlgeschlagene Syncs
|
||||
- Metriken und Alerting
|
||||
- Batch-Verarbeitung für große Datenmengen
|
||||
|
||||
### API Erweiterungen
|
||||
|
||||
- Zusätzliche Advoware-Endpunkte
|
||||
- Mehr EspoCRM-Entitäten
|
||||
- Custom Mapping-Regeln
|
||||
|
||||
## Lizenz
|
||||
|
||||
[License Information]
|
||||
|
||||
## Beitrag
|
||||
|
||||
Bitte erstellen Sie Issues für Bugs oder Feature-Requests. Pull-Requests sind willkommen!
|
||||
Reference in New Issue
Block a user