CSV File Connector Guide

The CSV File connector helps you read, write, append, parse, and generate CSV datasets inside Tealfabric workflows. It is useful for importing structured records, producing export files, and converting table-shaped data between file and in-memory formats.

Configuration

Set these parameters on the integration (not in per-call callData):

test is the only operation that validates file_path up front and returns Configuration validation failed when it is missing. Other operations use file_path from config without that pre-check (matching legacy PHP behavior).

Read records with read

Use read to load CSV rows into workflow data. Optional limit, offset (data rows after header), and columns filters are supported.

const baseUrl = "https://api.example.com/api/v1";
const tenantId = "<TENANT_ID>";
const apiKey = "<API_KEY>";

async function readOrdersCsv(integrationId: string) {
  const response = await fetch(`${baseUrl}/integrations/${encodeURIComponent(integrationId)}/execute`, {
    method: "POST",
    headers: {
      "X-API-Key": apiKey,
      "X-Tenant-ID": tenantId,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      operation: "read",
      limit: 100,
      offset: 0,
    }),
  });
  if (!response.ok) throw new Error(`Request failed: ${response.status}`);
  return response.json();
}

curl -X POST "https://api.example.com/api/v1/integrations/<ENTITY_ID>/execute" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{"operation":"read","limit":100}'

{
  "success": true,
  "data": {
    "message": "CSV file read successfully",
    "row_count": 2,
    "headers": ["order_id", "customer", "total"],
    "rows": [
      {"order_id": "1001", "customer": "Acme Corp", "total": "129.50"},
      {"order_id": "1002", "customer": "Northwind", "total": "78.00"}
    ]
  }
}

Write records with write

Use write to create or replace CSV content. Pass rows (or data) and optional headers when has_header is true.

{
  "success": true,
  "data": {
    "message": "CSV file written successfully",
    "row_count": 2,
    "file_path": "/data/exports/orders.csv"
  }
}

Additional operations

Test connection

test checks that an existing file_path is readable, or that the parent directory exists and is writable when the file does not yet exist.

{
  "success": true,
  "data": {
    "message": "CSV file connector test successful",
    "details": {
      "file_path": "/data/exports/orders.csv",
      "file_exists": true,
      "file_size": 128
    }
  }
}

Most failures come from inaccessible file paths, mismatched delimiter or encoding settings, and malformed row structures. Validate path permissions first, keep format options consistent between read and write steps, and run test before production schedules.