1. File Input in Actions

File inputs allow users to upload files that your action can then process or send to external APIs.

1.1 When to Use File Inputs

  • Upload files to external tools: Send user-uploaded documents to APIs, cloud storage, or external services like email or tickets systems.
  • Process user files: Analyze, convert, or transform files uploaded by users

1.2 Adding File Input Fields

Single File Input

Add an input field of type “FILE” to accept one file: image.png

Multiple File Input

For multiple files, enable Allow multiple files: Screenshot 2025-07-22 at 19.30.43.png

1.3 Accessing File Data in Code

Every uploaded file is delivered as a FileData object with this exact format:
{
  fileName: "Invoice.pdf",
  mimeType: "application/pdf",
  size: 102400,                    // bytes
  base64: "JVBERi0xLjQK...",        // binary content, Base64-encoded
  lastModified: "2024-01-15T10:30:00Z"  // ISO date string
}
Important: File inputs do NOT include a text property. The text shortcut only exists for file outputs.

Single File Access

// 'document' in this example is the id of the created input field
const document = data.input.document; // FileData object
const buffer = Buffer.from(document.base64, "base64");
ld.log(`Processing ${document.fileName} (${document.size} bytes)`);

Multiple Files Access

// 'attachments' in this example is the id of the created input field
const files = data.input.attachments; // FileData[] array
for (const file of files) {
  const buffer = Buffer.from(file.base64, "base64");
  await processFile(buffer, file.mimeType);
}
Data Structure: When “Allow multiple files” is enabled, data.input.fieldName is an array. Otherwise, it’s a single object.

1.4 Common Input Patterns

1.5 Input Validation & Error Handling

// Validate file presence
const files = data.input.attachments;
if (!files || files.length === 0) {
  return { error: 'No files provided. Please attach at least one file.' };
}

// Validate file types
const allowedTypes = ['application/pdf', 'image/jpeg', 'image/png'];
for (const file of files) {
  if (!allowedTypes.includes(file.mimeType)) {
    return {
      error: `Unsupported file type: ${file.mimeType}. Allowed: ${allowedTypes.join(', ')}`
    };
  }
}

// Log file metadata for debugging
ld.log('Processing files:', files.map(f => ({
  fileName: f.fileName,
  mimeType: f.mimeType,
  size: f.size
})));

2. File Output in Actions

File outputs allow your action to generate and return files that users can download or use in subsequent actions.

2.1 When to Use File Outputs

  • Generate reports: Create PDFs, spreadsheets, or documents from data
  • Retrieve files from APIs: Download files from external services
  • Transform files: Convert between formats or process uploaded files
  • Export data: Create CSV exports, backup files, or data dumps

2.2 File Output Format

Return files under a files key in your response:
// Single file output
return {
  files: {
    fileName: "report.pdf",
    mimeType: "application/pdf",
    base64: "JVBERi0xLjQK..."  // Base64 encoded content
  }
};

// Multiple files output
return {
  files: [
    {
      fileName: "data.csv",
      mimeType: "text/csv",
      text: "Name,Email\nJohn,john@example.com"  // Text shortcut for UTF-8
    },
    {
      fileName: "chart.png",
      mimeType: "image/png",
      base64: "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
};

File Output Properties

FieldRequiredNotes
fileNameInclude proper file extension
mimeTypeAccurate MIME type for proper handling
base64✓*Base64 encoded binary content
text✓*UTF-8 text content (alternative to base64)
lastModifiedISO date string (defaults to current time)
*Provide either base64 OR text, never both.

2.3 Common Output Patterns

3. File Output in Triggers

Triggers can also return files when detecting events that include file attachments or when generating files based on trigger data.
Key Difference: Unlike actions that return objects directly, triggers must return an array of events. Each event needs id, timestamp, and data properties, with files inside the data object.

3.1 When to Use File Outputs in Triggers

  • Email attachments: Forward attachments from incoming emails
  • File change events: Return modified or new files from monitored systems
  • Generated notifications: Create summary files or reports when events occur
  • API webhook files: Process and forward files from webhook payloads

3.2 Trigger File Output Format

Triggers must return an array of objects with id, timestamp, and data properties. Files go inside the data object:
// Required trigger format with files
return [
  {
    id: "msg_123",                    // Unique identifier for this event
    timestamp: "2024-01-15T10:30:00Z", // Event timestamp
    data: {
      from: "sender@example.com",
      subject: "Invoice #12345",
      body: "Please find the invoice attached.",
      messageId: "msg_123",
      files: [                        // Files go INSIDE data object
        {
          fileName: "invoice-12345.pdf",
          mimeType: "application/pdf",
          base64: "JVBERi0xLjQK..."
        }
      ]
    }
  }
];
Important: Unlike actions, triggers must return an array of events, and files must be inside the data object, not at the top level.

3.3 Common Trigger Patterns

4. Platform Constraints & Limits

ConstraintLimit
Total file size per action100 MB
Maximum files per action20 files
Individual documents≤ 256 MB*
Individual images≤ 20 MB
Individual spreadsheets≤ 30 MB
Individual audio files≤ 200 MB*
Individual video files≤ 20 MB
Other file types≤ 10 MB
Action execution timeout2 minutes
*Still bounded by the 100 MB total limit.
Validation: Exceeding limits throws an error before your code executes.
{
  "error": "Total file size (120.0 MB) exceeds the action execution limit of 100.0 MB. Please use smaller files or reduce the number of files."
}

4.1 Sandbox Library Restrictions

Custom action and trigger code runs in a secure sandboxed environment.
You cannot install or import external libraries (npm, pip, etc.)—only a limited set of built-in JavaScript/Node.js APIs are available.
For advanced file processing (e.g., PDF parsing, image manipulation), use external APIs or services and call them from your code.

5. Best Practices

File Input Best Practices

  • Validate file types early: Check MIME types before processing
  • Handle missing files gracefully: Use || [] for optional file arrays
  • Log file metadata: Help debug issues without exposing content
  • Provide clear error messages: Tell users exactly what went wrong
// Good validation pattern
const files = data.input.attachments || [];
if (files.length === 0) {
  return { error: 'Please attach at least one file to process.' };
}

const allowedTypes = ['image/jpeg', 'image/png', 'application/pdf'];
for (const file of files) {
  if (!allowedTypes.includes(file.mimeType)) {
    return {
      error: `File "${file.fileName}" has unsupported type ${file.mimeType}. Allowed: ${allowedTypes.join(', ')}`
    };
  }
}

File Output Best Practices

  • Use meaningful filenames: Include dates, IDs, or descriptive names
  • Set accurate MIME types: Enables proper file handling and previews
  • Use text shortcut for UTF-8: More efficient than base64 for text files
  • Include processing status: Help users understand what happened
// Good output pattern
return {
  files: {
    fileName: `customer-report-${new Date().toISOString().slice(0,10)}.pdf`,
    mimeType: 'application/pdf',
    base64: reportBuffer.toString('base64')
  },
  success: true,
  recordsProcessed: customerData.length,
  message: `Generated report with ${customerData.length} customer records`
};

Performance Best Practices

  • Process files in parallel when possible: Use Promise.all() for independent operations
  • Avoid loading all files into memory: Process one at a time for large batches
  • Log progress: Use ld.log() to track processing status
  • Handle errors gracefully: Continue processing other files if one fails
// Good error handling pattern
const results = [];
for (const file of files) {
  try {
    const result = await processFile(file);
    results.push({ fileName: file.fileName, status: "success", result });
    ld.log(`✓ Processed ${file.fileName}`);
  } catch (error) {
    results.push({
      fileName: file.fileName,
      status: "error",
      error: error.message,
    });
    ld.log(`✗ Failed ${file.fileName}: ${error.message}`);
  }
}

6. Troubleshooting

IssueLikely CauseSolution
”File not found”User didn’t attach fileMake file input required or add validation
Size limit errorFiles exceed 100 MB totalAsk for smaller files or fewer files
”Invalid file type”Wrong MIME typeValidate file.mimeType in your code
Empty file contentBase64 encoding issueVerify file.base64 is valid
Timeout errorsLarge files or slow processingOptimize processing or reduce file sizes
Memory errorsToo many large filesProcess files sequentially, not in parallel

Debug Helper

// Safe logging for file metadata (never logs content)
function logFileInfo(files) {
  const fileInfo = Array.isArray(files) ? files : [files];
  ld.log(
    "File info:",
    fileInfo.map((f) => ({
      fileName: f.fileName,
      mimeType: f.mimeType,
      size: f.size,
      hasBase64: !!f.base64,
      hasText: !!f.text, // Only exists for outputs
    })),
  );
}