1. Dateieingabe in Aktionen

Dateieingaben ermöglichen es Nutzern, Dateien hochzuladen, die deine Aktion dann verarbeiten oder an externe APIs senden kann.

1.1 Wann du Dateieingaben verwenden solltest

  • Dateien zu externen Tools hochladen: Sende von Nutzern hochgeladene Dokumente an APIs, Cloud-Speicher oder externe Dienste wie E-Mail oder Ticket-Systeme.
  • Nutzerdateien verarbeiten: Analysiere, konvertiere oder transformiere von Nutzern hochgeladene Dateien

1.2 Dateieingabefelder hinzufügen

Einzelne Dateieingabe

Füge ein Eingabefeld vom Typ “FILE” hinzu, um eine Datei zu akzeptieren: image.png

Mehrere Dateieingaben

Für mehrere Dateien aktiviere Mehrere Dateien erlauben: Screenshot 2025-07-22 at 19.30.43.png

1.3 Auf Dateidaten im Code zugreifen

Jede hochgeladene Datei wird als FileData-Objekt mit diesem exakten Format geliefert:
{
  fileName: "Rechnung.pdf",
  mimeType: "application/pdf",
  size: 102400,                    // Bytes
  base64: "JVBERi0xLjQK...",        // Binärinhalt, Base64-kodiert
  lastModified: "2024-01-15T10:30:00Z"  // ISO-Datumsstring
}
Wichtig: Dateieingaben enthalten KEINE text-Eigenschaft. Die text-Abkürzung existiert nur für Dateiausgaben.

Zugriff auf einzelne Datei

// 'document' ist in diesem Beispiel die ID des erstellten Eingabefelds
const document = data.input.document; // FileData-Objekt
const buffer = Buffer.from(document.base64, "base64");
ld.log(`Verarbeite ${document.fileName} (${document.size} Bytes)`);

Zugriff auf mehrere Dateien

// 'attachments' ist in diesem Beispiel die ID des erstellten Eingabefelds
const files = data.input.attachments; // FileData[] Array
for (const file of files) {
  const buffer = Buffer.from(file.base64, "base64");
  await processFile(buffer, file.mimeType);
}
Datenstruktur: Wenn “Mehrere Dateien erlauben” aktiviert ist, ist data.input.fieldName ein Array. Andernfalls ist es ein einzelnes Objekt.

1.4 Häufige Eingabemuster

1.5 Eingabevalidierung & Fehlerbehandlung

// Dateipräsenz validieren
const files = data.input.attachments;
if (!files || files.length === 0) {
  return { error: 'Keine Dateien bereitgestellt. Bitte hänge mindestens eine Datei an.' };
}

// Dateitypen validieren
const allowedTypes = ['application/pdf', 'image/jpeg', 'image/png'];
for (const file of files) {
  if (!allowedTypes.includes(file.mimeType)) {
    return {
      error: `Nicht unterstützter Dateityp: ${file.mimeType}. Erlaubt: ${allowedTypes.join(', ')}`
    };
  }
}

// Dateimetadaten für Debugging protokollieren
ld.log('Verarbeite Dateien:', files.map(f => ({
  fileName: f.fileName,
  mimeType: f.mimeType,
  size: f.size
})));

2. Dateiausgabe in Aktionen

Dateiausgaben ermöglichen es deiner Aktion, Dateien zu generieren und zurückzugeben, die Nutzer herunterladen oder in nachfolgenden Aktionen verwenden können.

2.1 Wann du Dateiausgaben verwenden solltest

  • Berichte generieren: PDFs, Tabellenkalkulationen oder Dokumente aus Daten erstellen
  • Dateien von APIs abrufen: Dateien von externen Diensten herunterladen
  • Dateien transformieren: Zwischen Formaten konvertieren oder hochgeladene Dateien verarbeiten
  • Daten exportieren: CSV-Exporte, Backup-Dateien oder Daten-Dumps erstellen

2.2 Dateiausgabeformat

Gib Dateien unter einem files-Schlüssel in deiner Antwort zurück:
// Einzelne Dateiausgabe
return {
  files: {
    fileName: "bericht.pdf",
    mimeType: "application/pdf",
    base64: "JVBERi0xLjQK..."  // Base64-kodierter Inhalt
  }
};

// Mehrere Dateiausgaben
return {
  files: [
    {
      fileName: "daten.csv",
      mimeType: "text/csv",
      text: "Name,Email\nJohn,john@example.com"  // Text-Abkürzung für UTF-8
    },
    {
      fileName: "diagramm.png",
      mimeType: "image/png",
      base64: "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
};

Dateiausgabe-Eigenschaften

FeldErforderlichHinweise
fileNameRichtige Dateierweiterung einschließen
mimeTypeGenauer MIME-Typ für ordnungsgemäße Verarbeitung
base64✓*Base64-kodierter Binärinhalt
text✓*UTF-8 Textinhalt (Alternative zu base64)
lastModifiedISO-Datumsstring (Standard ist aktuelle Zeit)
*Gib entweder base64 ODER text an, niemals beides.

2.3 Häufige Ausgabemuster

3. Dateiausgabe in Triggern

Trigger können auch Dateien zurückgeben, wenn sie Ereignisse erkennen, die Dateianhänge enthalten, oder wenn sie Dateien basierend auf Trigger-Daten generieren.
Wichtiger Unterschied: Im Gegensatz zu Aktionen, die Objekte direkt zurückgeben, müssen Trigger ein Array von Ereignissen zurückgeben. Jedes Ereignis benötigt id, timestamp und data Eigenschaften, mit Dateien innerhalb des data-Objekts.

3.1 Wann du Dateiausgaben in Triggern verwenden solltest

  • E-Mail-Anhänge: Anhänge von eingehenden E-Mails weiterleiten
  • Dateiänderungsereignisse: Modifizierte oder neue Dateien von überwachten Systemen zurückgeben
  • Generierte Benachrichtigungen: Zusammenfassungsdateien oder Berichte erstellen, wenn Ereignisse auftreten
  • API-Webhook-Dateien: Dateien aus Webhook-Payloads verarbeiten und weiterleiten

3.2 Trigger-Dateiausgabeformat

Trigger müssen ein Array von Objekten mit id, timestamp und data Eigenschaften zurückgeben. Dateien kommen innerhalb des data-Objekts:
// Erforderliches Trigger-Format mit Dateien
return [
  {
    id: "msg_123",                    // Eindeutiger Bezeichner für dieses Ereignis
    timestamp: "2024-01-15T10:30:00Z", // Ereignis-Zeitstempel
    data: {
      from: "sender@example.com",
      subject: "Rechnung #12345",
      body: "Bitte finde die Rechnung im Anhang.",
      messageId: "msg_123",
      files: [                        // Dateien kommen INNERHALB des data-Objekts
        {
          fileName: "rechnung-12345.pdf",
          mimeType: "application/pdf",
          base64: "JVBERi0xLjQK..."
        }
      ]
    }
  }
];
Wichtig: Im Gegensatz zu Aktionen müssen Trigger ein Array von Ereignissen zurückgeben, und files muss innerhalb des data-Objekts sein, nicht auf oberster Ebene.

3.3 Häufige Trigger-Muster

4. Plattform-Einschränkungen & Limits

EinschränkungLimit
Gesamte Dateigröße pro Aktion100 MB
Maximale Dateien pro Aktion20 Dateien
Einzelne Dokumente≤ 256 MB*
Einzelne Bilder≤ 20 MB
Einzelne Tabellenkalkulationen≤ 30 MB
Einzelne Audiodateien≤ 200 MB*
Einzelne Videodateien≤ 20 MB
Andere Dateitypen≤ 10 MB
Aktions-Ausführungs-Timeout2 Minuten
*Immer noch durch das 100 MB Gesamtlimit begrenzt.
Validierung: Das Überschreiten von Limits löst einen Fehler aus bevor dein Code ausgeführt wird.
{
  "error": "Gesamte Dateigröße (120.0 MB) überschreitet das Aktions-Ausführungslimit von 100.0 MB. Bitte verwende kleinere Dateien oder reduziere die Anzahl der Dateien."
}

4.1 Sandbox-Bibliotheksbeschränkungen

Nutzerdefinierter Aktions- und Trigger-Code läuft in einer sicheren Sandbox-Umgebung.
Du kannst keine externen Bibliotheken installieren oder importieren (npm, pip, etc.) – nur eine begrenzte Anzahl von eingebauten JavaScript/Node.js APIs ist verfügbar.
Für erweiterte Dateiverarbeitung (z.B. PDF-Parsing, Bildmanipulation), verwende externe APIs oder Dienste und rufe sie aus deinem Code auf.

5. Best Practices

Best Practices für Dateieingaben

  • Dateitypen früh validieren: Prüfe MIME-Typen vor der Verarbeitung
  • Fehlende Dateien elegant behandeln: Verwende || [] für optionale Datei-Arrays
  • Dateimetadaten protokollieren: Hilft beim Debuggen von Problemen ohne Inhalt preiszugeben
  • Klare Fehlermeldungen bereitstellen: Sage Nutzern genau, was schiefgelaufen ist
// Gutes Validierungsmuster
const files = data.input.attachments || [];
if (files.length === 0) {
  return { error: 'Bitte hänge mindestens eine Datei zur Verarbeitung an.' };
}

const allowedTypes = ['image/jpeg', 'image/png', 'application/pdf'];
for (const file of files) {
  if (!allowedTypes.includes(file.mimeType)) {
    return {
      error: `Datei "${file.fileName}" hat nicht unterstützten Typ ${file.mimeType}. Erlaubt: ${allowedTypes.join(', ')}`
    };
  }
}

Best Practices für Dateiausgaben

  • Aussagekräftige Dateinamen verwenden: Füge Daten, IDs oder beschreibende Namen hinzu
  • Genaue MIME-Typen setzen: Ermöglicht ordnungsgemäße Dateiverarbeitung und Vorschauen
  • Text-Abkürzung für UTF-8 verwenden: Effizienter als base64 für Textdateien
  • Verarbeitungsstatus einschließen: Hilf Nutzern zu verstehen, was passiert ist
// Gutes Ausgabemuster
return {
  files: {
    fileName: `kundenbericht-${new Date().toISOString().slice(0,10)}.pdf`,
    mimeType: 'application/pdf',
    base64: reportBuffer.toString('base64')
  },
  success: true,
  recordsProcessed: customerData.length,
  message: `Bericht mit ${customerData.length} Kundendatensätzen generiert`
};

Performance Best Practices

  • Dateien nach Möglichkeit parallel verarbeiten: Verwende Promise.all() für unabhängige Vorgänge
  • Vermeide alle Dateien in den Speicher zu laden: Verarbeite eine nach der anderen bei großen Batches
  • Fortschritt protokollieren: Verwende ld.log() um den Verarbeitungsstatus zu verfolgen
  • Fehler elegant behandeln: Fahre mit der Verarbeitung anderer Dateien fort, wenn eine fehlschlägt
// Gutes Fehlerbehandlungsmuster
const results = [];
for (const file of files) {
  try {
    const result = await processFile(file);
    results.push({ fileName: file.fileName, status: "success", result });
    ld.log(`✓ ${file.fileName} verarbeitet`);
  } catch (error) {
    results.push({
      fileName: file.fileName,
      status: "error",
      error: error.message,
    });
    ld.log(`✗ ${file.fileName} fehlgeschlagen: ${error.message}`);
  }
}

6. Fehlerbehebung

ProblemWahrscheinliche UrsacheLösung
”Datei nicht gefunden”Nutzer hat keine Datei angehängtMache Dateieingabe erforderlich oder füge Validierung hinzu
Größenlimit-FehlerDateien überschreiten 100 MB gesamtBitte um kleinere oder weniger Dateien
”Ungültiger Dateityp”Falscher MIME-TypValidiere file.mimeType in deinem Code
Leerer DateiinhaltBase64-KodierungsproblemÜberprüfe, dass file.base64 gültig ist
Timeout-FehlerGroße Dateien oder langsame VerarbeitungOptimiere Verarbeitung oder reduziere Dateigrößen
SpeicherfehlerZu viele große DateienVerarbeite Dateien sequenziell, nicht parallel

Debug-Helfer

// Sicheres Protokollieren für Dateimetadaten (protokolliert niemals Inhalt)
function logFileInfo(files) {
  const fileInfo = Array.isArray(files) ? files : [files];
  ld.log(
    "Datei-Info:",
    fileInfo.map((f) => ({
      fileName: f.fileName,
      mimeType: f.mimeType,
      size: f.size,
      hasBase64: !!f.base64,
      hasText: !!f.text, // Existiert nur für Ausgaben
    })),
  );
}