nextcloud-tables

Production-Ready n8n Node für Nextcloud Tables - Vollständige API-Abdeckung mit erweiterten Filtern, Multi-Column-Sorting, CSV-Import und professioneller Datenvalidierung

Package Information

Released: 5/31/2025

Downloads: 40 weekly / 86 monthly

Latest Version: 2.4.8

Author: Niko Terschawetz

Available Nodes

Nextcloud Tables

No description available

Documentation

n8n-nodes-nextcloud-tables

Ein Community n8n Node für die Integration mit Nextcloud Tables. Diese Node ermöglicht vollständige Tabellen-Verwaltung, erweiterte Datenoperationen und ist speziell für KI-Agents optimiert.

🚀 Produktions-Status: v2.4.7 ✅

Diese Node ist produktionsreif für die getesteten Kern-Features und gegen kritische NaN-Bugs abgehärtet!

✅ Version 2.4.8 - Production-Ready:

✅ Robuste Resource Locator Validierung - Keine NaN-Fehler mehr
✅ KI-Agent Kompatibilität - Spezielle AI-Friendly Operationen
✅ Umfassende Fehlerbehandlung - Detaillierte HTTP-Status-Codes
✅ Optimierte API-Performance - Query-Parameter für Column-Operationen
✅ Verbesserte Log-Kennzeichnung - Eindeutige Node-Identifikation für besseres Grepping
✅ Strukturiertes Logging - Debug, Info, Warn, Error Level mit Kontext

✅ Version 2.4.7 - Production-Ready:

🛡️ NaN-Bug-Fixes: Robuste Validierung gegen alle NaN-Quellen (null, undefined, 'NaN' strings)
🧹 Production-Cleanup: Alle Debug-Tools entfernt, saubere Codebase
⚡ Enhanced Error Handling: Hilfreiche Fehlermeldungen für Resource Locator Probleme
🔧 Optimierte Builds: TypeScript-Compilation ohne Warnings
📦 Clean Dependencies: Entfernte veraltete Scripts und Altlasten

✅ Getestet & Produktionsreif:

Tabellen-Management: Grundlegende CRUD-Operationen (getAll, get) ✅
Spalten-Management: Alle Operationen inkl. AI-friendly Extensions ✅
Zeilen-Management: Basis CRUD (create, getAll, get) ✅
Views-Management: Basis-Operationen (getAll, create) ✅
Shares-Management: Benutzer/Gruppen-Freigaben ✅
NaN-Bug-Protection: Robuste Resource Locator Validierung ✅

⚠️ Implementiert aber ungetestet:

Erweiterte Tabellen-Ops: update, delete
Erweiterte Zeilen-Ops: update (delete nicht von API unterstützt)
Erweiterte Views-Ops: get, update, delete, getRows
Erweiterte Shares-Ops: update, delete
CSV-Import: Vollständige Import-Pipeline
Context-Integration: App-Context-Features
Erweiterte Filter/Sort: Komplexe Multi-Column-Operationen

🛡️ Kritische Bug-Fixes in v2.4.7

Problem gelöst: NaN Table IDs

Nextcloud-Logs zeigten kritische Fehler wie:

[error] Did expect one result but found none for table id = NaN
[error] no read access to table id = 0

Root Cause: Resource Locator Handling

// VORHER: Unzureichende Validierung führte zu NaN IDs
if (!tableId || isNaN(tableId)) { ... }

// NACHHER: Robuste Validierung gegen ALLE NaN-Quellen
if (resourceLocator === null || resourceLocator === undefined || 
    resourceLocator === 'null' || resourceLocator === 'undefined' ||
    resourceLocator === 'NaN' || 
    (typeof resourceLocator === 'number' && isNaN(resourceLocator))) {
    throw new Error('Resource Locator ist erforderlich aber nicht gesetzt oder ungültig');
}

Gehärtete Validation in Load Options

✅ Tabellen-ID Extraktion: Robuste Behandlung von __rl Resource Locators
✅ Column/View Loading: Validierung verhindert /tables/NaN/columns Requests
✅ Error Messages: Hilfreiche Debugging-Informationen
✅ String-to-Number Conversion: Sichere parseInt() mit Validation

🤖 KI-Agent Optimiert ⭐

Einzigartig: Diese Node ist die erste n8n Community Node, die speziell für KI-Agents optimiert wurde!

Problem gelöst:

Standard n8n-Nodes verwenden displayOptions, die Parameter dynamisch verstecken. KI-Agents können diese nicht sehen.

Lösung: AI-Friendly Operationen

✅ Alle Parameter gleichzeitig sichtbar
✅ Keine UI-Dependencies für KI-Agents
✅ String-basierte IDs statt Dropdown-Navigation
✅ Flache Parameter-Struktur ohne Verschachtelung
✅ Robuste NaN-Protection in v2.4.7

AI-Friendly Operationen verfügbar:

Spalten-Management (AI-Optimiert)

// Für KI-Agents optimiert - ALLE Parameter sichtbar
Operation: "Spalte Erstellen (KI-Friendly)"
{
  "tableIdAI": "123",
  "columnType": "selection", 
  "columnTitle": "Status",
  "columnMandatory": true,
  
  // Alle typ-spezifischen Parameter gleichzeitig verfügbar:
  "selectionOptionsAI": "[\"Offen\", \"In Bearbeitung\", \"Fertig\"]",
  "selectionDefaultAI": "Offen",
  "selectionMultipleAI": false,
  
  // Text-Parameter (werden ignoriert bei anderen Typen):
  "textSubtypeAI": "line",
  "textMaxLengthAI": 255,
  // ... alle anderen Parameter verfügbar
}

// Vollständige Updates möglich
Operation: "Spalte Aktualisieren (KI-Friendly)"
{
  "columnIdAI": "456",
  "columnType": "text",           // Typ ändern
  "columnTitle": "Neuer Name",    // Titel ändern
  "textSubtypeAI": "long",        // Text-spezifisch
  "textMaxLengthAI": 500,         // Max-Länge ändern
  // Nur relevante Parameter werden verwendet
}

Vorteile für KI-Agents:

🔍 Parameter-Transparenz: 24 Parameter gleichzeitig sichtbar
🎯 Autonome Operationen: Keine UI-Interaktion erforderlich
🚀 String-basierte Eingaben: Keine Dropdown-Listen, maximale Flexibilität
🛡️ NaN-Protection: Robuste Validierung verhindert API-Fehler (v2.4.7)
↩️ Backward Compatible: Human-UI bleibt unverändert

📊 Feature-Übersicht & Test-Status

🏗️ Tabellen-Operationen

✅ Alle Tabellen abrufen: Getestet, produktionsreif
✅ Tabelle abrufen: Getestet, produktionsreif
⚠️ Tabelle erstellen: Implementiert, ungetestet
⚠️ Tabelle aktualisieren: Implementiert, ungetestet
⚠️ Tabelle löschen: Implementiert, ungetestet

📋 Spalten-Management ✅ VOLLSTÄNDIG GETESTET & AI-OPTIMIERT

Standard-Operationen:

✅ Alle Spalten abrufen: Getestet, produktionsreif
✅ Spalte abrufen: Getestet, produktionsreif
✅ Spalte erstellen: Getestet, produktionsreif
⚠️ Spalte aktualisieren: Implementiert, ungetestet
⚠️ Spalte löschen: Implementiert, ungetestet

🤖 KI-Friendly Operationen:

✅ Spalte Erstellen (KI-Friendly): Getestet, produktionsreif - 23 Parameter gleichzeitig sichtbar
⚠️ Spalte Aktualisieren (KI-Friendly): Implementiert, ungetestet - 24 Parameter für vollständige Updates

5 Spaltentypen vollständig unterstützt:

✅ Text: Getestet - Pattern-Validierung, Max-Länge, Subtypen (einzeilig/mehrzeilig)
✅ Number: Getestet - Min/Max, Dezimalstellen, Präfix/Suffix, Validierung
✅ DateTime: Getestet - Standard-Datum, flexible Eingabeformate
✅ Selection: Getestet - Dropdown-Optionen, Standard-Werte, Mehrfachauswahl
✅ UserGroup: Getestet - Benutzer/Gruppen-Auswahl, Multi-Select, Teams

🎯 Zeilen-Operationen

✅ Alle Zeilen abrufen: Getestet, produktionsreif
✅ Zeile abrufen: Getestet, produktionsreif (clientseitige Filterung)
✅ Zeile erstellen: Getestet, produktionsreif
⚠️ Zeile aktualisieren: Implementiert, ungetestet
❌ Zeile löschen: Nicht von Nextcloud Tables API unterstützt

Erweiterte Zeilen-Features (ungetestet):

⚠️ Smart-Pagination: 1-1000 Zeilen optimiert
⚠️ 11 Filter-Operatoren: =, !=, >, >=, <, <=, LIKE, starts_with, ends_with, is_empty, is_not_empty
⚠️ Multi-Column-Sorting: Prioritäts-basierte Sortierung
⚠️ Volltext-Suche: Case-sensitive/insensitive, spalten-spezifisch
✅ Automatische Validierung: Spalten-basierte Datenformatierung

📋 Views-Management

✅ Views abrufen: Getestet, produktionsreif
✅ View erstellen: Getestet, produktionsreif
⚠️ View abrufen (einzeln): Implementiert, ungetestet
⚠️ View aktualisieren: Implementiert, ungetestet
⚠️ View löschen: Implementiert, ungetestet
⚠️ Zeilen aus View abrufen: Implementiert, ungetestet

🤝 Kollaborations-Features

✅ Shares abrufen: Getestet, produktionsreif
✅ Share erstellen: Getestet, produktionsreif (Benutzer & Gruppen)
⚠️ Share aktualisieren: Implementiert, ungetestet
⚠️ Share löschen: Implementiert, ungetestet
✅ Benutzer/Gruppen-Listen: Getestet, produktionsreif

📥 CSV-Import ⚠️ UNGETESTET

⚠️ Flexible Optionen: Header-Erkennung, Trennzeichen-Auswahl
⚠️ Column-Mapping: Automatische oder manuelle Zuordnung
⚠️ Datentyp-Konvertierung: Auto, Text, Number, DateTime, Boolean
⚠️ Import-Status: Überwachung und Fehlerbehandlung

🌐 App-Context-Integration ⚠️ UNGETESTET

⚠️ Context-Navigation: Nahtlose Nextcloud-App-Integration
⚠️ Context-Tabellen: Gefilterte Ansichten nach App-Context
⚠️ Context-Pages: App-Page-Management

Installation

npm install n8n-nodes-nextcloud-tables

Starten Sie n8n neu, um die neue Node zu laden.

Konfiguration

Credentials

Erstellen Sie neue Credentials vom Typ "Nextcloud Tables API":

Nextcloud URL: Vollständige URL (z.B. https://cloud.example.com)
Benutzername: Ihr Nextcloud-Benutzername
Passwort: App-Passwort (empfohlen) oder normales Passwort

🔒 Sicherheit: Verwenden Sie App-Passwörter:

Nextcloud → Einstellungen → Sicherheit → App-Passwörter
Erstellen Sie ein neues App-Passwort für n8n

🤖 KI-Agent Usage Examples

Spalte für KI-Agents erstellen

{
  "resource": "Spalte",
  "operation": "Spalte Erstellen (KI-Friendly)",
  "tableIdAI": "123",
  "columnType": "selection",
  "columnTitle": "Projekt-Status", 
  "columnDescription": "Aktueller Status des Projekts",
  "columnMandatory": true,
  "selectionOptionsAI": "[\"Geplant\", \"In Arbeit\", \"Testing\", \"Fertig\", \"Archiviert\"]",
  "selectionDefaultAI": "Geplant",
  "selectionMultipleAI": false
}

Spalte für KI-Agents aktualisieren

{
  "resource": "Spalte", 
  "operation": "Spalte Aktualisieren (KI-Friendly)",
  "columnIdAI": "456",
  "columnTitle": "Erweiterte Projekt-Status",
  "selectionOptionsAI": "[\"Backlog\", \"Sprint\", \"Review\", \"Done\", \"Cancelled\"]",
  "selectionDefaultAI": "Backlog"
}

Verschiedene Spaltentypen für KI-Agents

// Text-Spalte erstellen
{
  "columnType": "text",
  "columnTitle": "Beschreibung",
  "textSubtypeAI": "long",
  "textMaxLengthAI": 1000,
  "textPatternAI": "^[A-Za-z0-9\\s]+$"
}

// Zahlen-Spalte erstellen  
{
  "columnType": "number",
  "columnTitle": "Budget",
  "numberMinAI": 0,
  "numberMaxAI": 100000,
  "numberDecimalsAI": 2,
  "numberPrefixAI": "€"
}

// Benutzer/Gruppen-Spalte erstellen
{
  "columnType": "usergroup", 
  "columnTitle": "Zuständig",
  "usergroupTypeAI": "user",
  "usergroupMultipleAI": false
}

Human vs. KI-Agent Vergleich

// HUMAN (UI-optimiert) - Parameter erscheinen dynamisch
Operation: "Spalte Erstellen"
Tabelle: [Dropdown-Auswahl]
Typ: "Auswahl" 
// → Dann erscheinen Auswahl-spezifische Parameter

// KI-AGENT (AI-optimiert) - Alle Parameter sichtbar
Operation: "Spalte Erstellen (KI-Friendly)"  
// → ALLE 23 Parameter sofort sichtbar und verwendbar
// → String-basierte Eingaben statt Dropdown-Listen
// → Maximale Flexibilität für autonome Ausführung

🔧 Advanced Usage

Erweiterte Zeilen-Abfrage mit Filtern

{
  "resource": "Zeile",
  "operation": "Alle Zeilen Abrufen",
  "source": "table",
  "tableId": "123",
  "useFiltering": true,
  "filters": [
    {
      "columnId": "5",
      "operator": "EQ", 
      "value": "Aktiv"
    },
    {
      "columnId": "8",
      "operator": "GT",
      "value": "2024-01-01"
    }
  ],
  "useSorting": true,
  "sorting": [
    {
      "columnId": "10",
      "direction": "DESC"
    }
  ]
}

CSV-Import mit Column-Mapping

{
  "resource": "Import",
  "operation": "CSV in Tabelle Importieren",
  "tableId": "123",
  "csvData": "[Binary CSV Data]",
  "hasHeader": true,
  "delimiter": ";",
  "columnMapping": [
    {
      "csvColumn": "Kundenname",
      "tableColumn": "1",
      "dataType": "text"
    },
    {
      "csvColumn": "Erstellungsdatum", 
      "tableColumn": "2",
      "dataType": "datetime"
    }
  ]
}

📊 Vollständige API-Abdeckung

✅ Implementierte Endpunkte

Tables: /tables/* (vollständige CRUD)
Rows: /tables/{id}/rows, /views/{id}/rows (vollständige CRUD außer DELETE*)
Views: /tables/{id}/views, /views/{id} (vollständige CRUD)
Columns: /tables/{id}/columns, /columns/{id} (vollständige CRUD + AI-friendly)
Shares: /tables/{id}/shares, /shares/{id} (vollständige CRUD)
Import: /tables/{id}/import (POST + Status-Monitoring)
Context: /contexts/* (GET-Operationen)

*Note: Row DELETE ist von der Nextcloud Tables API nicht unterstützt

🔧 Kompatibilität

Nextcloud: 28+ (getestet)
Tables App: 0.6+ (getestet)
n8n: 1.0+ (getestet)

🛠️ Technische Details

API Version: Hybrid v1/v2 (optimal je nach Operation)
Authentifizierung: Basic Auth mit App-Passwort-Support
Error Handling: 10 HTTP-Status-Codes mit spezifischen Meldungen
Retry Logic: 3 Versuche mit exponentiellem Backoff
Validation: Spalten-basierte Echtzeit-Validierung

Development & Testing

Setup

npm install          # Dependencies
npm run build        # TypeScript kompilieren  
npm run dev          # Development-Modus
npm run lint         # Code-Prüfung
npm run format       # Code formatieren

Projekt-Architektur

nodes/NextcloudTables/
├── NextcloudTables.node.ts              # Haupt-Node
├── descriptions/                        # UI-Definitionen
│   ├── column.ts     ← KI-OPTIMIERT
│   ├── table.ts      ├── row.ts
│   ├── view.ts       ├── share.ts  
│   ├── import.ts     └── context.ts
├── handlers/                           # Business Logic
│   ├── column.handler.ts ← KI-FRIENDLY LOGIC
│   └── *.handler.ts
├── helpers/                           # Core Utilities
│   ├── api.helper.ts                  # HTTP + Error Handling
│   ├── data.formatter.ts              # Validation
│   └── node.methods.ts                # Dynamic Dropdowns
└── interfaces/                        # TypeScript Types

🛠️ Troubleshooting

Logging & Debugging

🔍 Verbesserte Log-Kennzeichnung (Neu in v2.4.8)
Alle Logs der Node sind jetzt eindeutig gekennzeichnet für besseres Grepping:

# Alle Nextcloud Tables Node Logs
grep "N8N-NEXTCLOUD-TABLES" /path/to/n8n/logs

# Nur API-Fehler
grep "N8N-NEXTCLOUD-TABLES.*API-ERROR" /path/to/n8n/logs

# Nur Validierungsfehler
grep "N8N-NEXTCLOUD-TABLES.*VALIDATION-ERROR" /path/to/n8n/logs

# Operation-spezifische Logs
grep "N8N-NEXTCLOUD-TABLES.*OPERATION-" /path/to/n8n/logs

# Resource Locator Debugging
grep "N8N-NEXTCLOUD-TABLES.*RESOURCE-VALIDATION" /path/to/n8n/logs

Log-Kategorien:

[N8N-NEXTCLOUD-TABLES] [DEBUG] [API-REQUEST] - API-Anfragen
[N8N-NEXTCLOUD-TABLES] [DEBUG] [API-RESPONSE] - API-Antworten
[N8N-NEXTCLOUD-TABLES] [INFO] [OPERATION-START] - Operation gestartet
[N8N-NEXTCLOUD-TABLES] [INFO] [OPERATION-SUCCESS] - Operation erfolgreich
[N8N-NEXTCLOUD-TABLES] [ERROR] [OPERATION-ERROR] - Operation fehlgeschlagen
[N8N-NEXTCLOUD-TABLES] [WARN] [VALIDATION-ERROR] - Validierungsfehler
[N8N-NEXTCLOUD-TABLES] [DEBUG] [RESOURCE-VALIDATION] - Resource Locator Debugging

Beispiel-Logs:

2024-01-15T10:30:45.123Z [N8N-NEXTCLOUD-TABLES] [INFO] [OPERATION-START] table.getAll
2024-01-15T10:30:45.124Z [N8N-NEXTCLOUD-TABLES] [DEBUG] [API-REQUEST] GET /tables
2024-01-15T10:30:45.234Z [N8N-NEXTCLOUD-TABLES] [DEBUG] [API-RESPONSE] GET /tables -> 200 (110ms)
2024-01-15T10:30:45.235Z [N8N-NEXTCLOUD-TABLES] [INFO] [OPERATION-SUCCESS] table.getAll completed (112ms)

Häufige Probleme

401 Unauthorized
✅ Lösung: App-Passwort verwenden, Berechtigungen prüfen

KI-Agent kann Parameter nicht sehen
✅ Lösung: KI-Friendly Operationen verwenden (createAIFriendly, updateAIFriendly)

🚨 NaN Table ID Errors (BEHOBEN in v2.4.7)
❌ Symptom: Nextcloud-Logs zeigen table id = NaN oder table id = 0
✅ Lösung: Update auf v2.4.7 - Robuste Resource Locator Validierung implementiert

Filter funktionieren nicht
✅ Lösung: Spalten-IDs statt Namen, korrekte Operatoren verwenden

Column-Erstellung fehlgeschlagen
✅ Behoben: Verwendet optimierte API v1 mit Query-Parametern

Resource Locator Validation Errors
✅ Neu in v2.4.7: Detaillierte Fehlermeldungen helfen bei Debugging:

"Resource Locator ist erforderlich aber nicht gesetzt oder ungültig"
"Ungültige ID in Resource Locator: 'undefined' ist keine gültige Zahl"

Error Handling

Detaillierte Fehlermeldungen für alle HTTP-Status-Codes:

400-404: Client-Fehler mit Lösungshinweisen
429: Rate-Limiting mit automatischer Wiederholung
5xx: Server-Fehler mit Retry-Logic
Resource Locator: Spezifische Validierung und Debugging-Hilfen (v2.4.7)

🎯 Roadmap

✅ Version 2.4.8 (Aktuell)

✅ Verbesserte Log-Kennzeichnung - Eindeutige [N8N-NEXTCLOUD-TABLES] Präfixe
✅ Strukturiertes Logging - Debug, Info, Warn, Error Level mit Kontext
✅ API-Request/Response Logging - Detaillierte Debugging-Informationen
✅ Operation-Tracking - Start, Success, Error Logging mit Zeitstempel
✅ Validation-Logging - Resource Locator und Parameter-Validierung
✅ Grep-freundliche Logs - Einfache Filterung nach Kategorien

✅ Version 2.4.7

🛡️ Kritische NaN-Bug-Fixes: Robuste Resource Locator Validierung
🧹 Production-Cleanup: Entfernung aller Debug-Tools und Altlasten
⚡ Enhanced Error Handling: Hilfreiche Fehlermeldungen und Validierung
📦 Optimierte Builds: Saubere TypeScript-Compilation ohne Warnings

✅ Version 2.4.6 (Vorgänger)

Vollständige KI-Agent-Optimierung
24 AI-Parameter mit systematischer Trennung
Robuste Validierung und Error Handling
Saubere UX für alle Operationen

🔮 Zukünftige Versionen

Weitere AI-Friendly Operationen für andere Ressourcen
Erweiterte KI-Features (Bulk-Operations, Schema-Inference)
Performance-Optimierungen für große Datenmengen
Extended Context-Integration mit mehr Nextcloud-Apps

Contributing

Beiträge willkommen! Besonders:

🤖 KI-Agent Testing: Testen Sie die AI-friendly Operationen
🐛 Bug Reports: GitHub Issues für Probleme
💻 Code: Verbesserungen und neue Features
📝 Dokumentation: Beispiele und Best Practices

Lizenz

MIT

Support

GitHub: Issues & Discussions
n8n Community: Community Forum
Documentation: Nextcloud Tables API

🤖 Diese Node ist die erste KI-Agent-optimierte n8n Community Node!
Probieren Sie die AI-friendly Operationen aus und erleben Sie autonome Tabellen-Verwaltung.