Export Workbook Plugin

The Export Workbook Plugin is a server-side utility for Flatfile that allows users to export data from an entire Flatfile Workbook into a single, downloadable Microsoft Excel (.xlsx) file.

Its primary purpose is to provide a simple way to get data out of Flatfile in a widely-used format. The plugin is triggered by a user action, typically a “Download” button configured on the workbook. It then iterates through all the sheets in the workbook (unless some are excluded), fetches the records, and compiles them into a corresponding sheet in the generated Excel file.

Use cases include:

• Allowing end-users to download a copy of their cleaned and validated data after an import
• Creating backups or snapshots of data within a Flatfile Space
• Exporting data for use in other systems that accept Excel files
• Providing a final report of all imported data, including any validation messages as comments in the Excel cells

​

Installation

npm install @flatfile/plugin-export-workbook

​

Configuration & Parameters

The plugin is configured by passing an options object to the exportWorkbookPlugin function.

​

Sheet Options

The sheetOptions parameter allows you to configure specific sheets with the following options:

​

Usage Examples

​

Basic Usage

import { FlatfileListener } from "@flatfile/listener";
import { exportWorkbookPlugin } from "@flatfile/plugin-export-workbook";

export default function (listener) {
  // Use the plugin with default settings
  listener.use(exportWorkbookPlugin());
}

/*
// In your workbook.config.json, you need an action to trigger the plugin:
"actions": [
  {
    "operation": "downloadWorkbook",
    "mode": "foreground",
    "label": "Download Excel Workbook",
    "description": "Downloads all data in an Excel file.",
    "primary": true
  }
]
*/

​

Configuration Example

import { FlatfileListener } from "@flatfile/listener";
import { exportWorkbookPlugin } from "@flatfile/plugin-export-workbook";

export default function (listener) {
  listener.use(
    exportWorkbookPlugin({
      // Only export records that have passed validation
      recordFilter: 'valid',
      // Exclude the 'internal_notes' field from all sheets
      excludeFields: ['internal_notes'],
      // Exclude the 'raw_data' sheet entirely
      excludedSheets: ['raw_data'],
      // Automatically start the download for the user
      autoDownload: true,
      // Enable verbose logging for troubleshooting
      debug: true,
      // Add custom options for the 'contacts' sheet
      sheetOptions: {
        contacts: {
          // Omit the header row for the 'contacts' sheet
          skipColumnHeaders: true,
        },
      },
    })
  );
}

​

Advanced Usage with Column Transformer

import { FlatfileListener } from "@flatfile/listener";
import { exportWorkbookPlugin } from "@flatfile/plugin-export-workbook";

export default function (listener) {
  listener.use(
    exportWorkbookPlugin({
      // Use a custom job name
      jobName: 'export:customExcel',
      // Transform column names to be more user-friendly
      columnNameTransformer: (columnName, sheetSlug) => {
        // Example: transform 'firstName' to 'First Name'
        const friendlyName = columnName.replace(/([A-Z])/g, ' $1').replace(/^./, (str) => str.toUpperCase());
        
        // Add a prefix for a specific sheet
        if (sheetSlug === 'users') {
          return `User - ${friendlyName}`;
        }
        
        return friendlyName;
      },
    })
  );
}

/*
// In your workbook.config.json, the action must match the custom jobName:
"actions": [
  {
    "operation": "export:customExcel",
    "mode": "foreground",
    "label": "Download Custom Excel Report",
    "primary": true
  }
]
*/

​

Troubleshooting

​

Enable Debug Mode

The most important troubleshooting tool is the debug: true option. When enabled, the plugin prints detailed logs to the console, including which sheets are being processed, which are skipped, and the status of file writing and uploading.

​

Check Action Operation

If the plugin does not trigger when the action button is clicked, ensure the operation value in your workbook.config.json action exactly matches the jobName used to configure the plugin.

​

No Data Exported

If the exported file is empty or missing sheets, check if a recordFilter is unintentionally filtering out all records or if excludedSheets is misconfigured. The debug logs will show if sheets are being skipped. If all sheets are empty, the plugin will throw an error: No data to write to Excel file.

​

Notes

​

Server-Side Execution

This plugin must be deployed in a server-side listener environment, not in the browser.

​

Action Configuration

For the plugin to be triggered, a corresponding action must be configured on the Workbook in your workbook.config.json. The operation of this action must match the jobName option of the plugin (which defaults to workbook:downloadWorkbook).

​

File System Access

The plugin temporarily writes the .xlsx file to the /tmp directory of the execution environment, which is standard for serverless functions.

​

Sheet Name Sanitization

Excel sheet names have limitations (e.g., max 31 characters, no invalid characters like \ / ? * [ ]). The plugin automatically sanitizes sheet names from your workbook to comply with these rules. If a name becomes empty after sanitization, it will be replaced with a default like Sheet1, Sheet2, etc.

​

Default Behavior

• By default, all records from all sheets are exported
• Validation messages are included as comments in the Excel cells
• The exported file is made available in the “Files” page rather than auto-downloading
• Column headers are included in the export
• A filename is auto-generated using the workbook name and timestamp if not specified

​

Error Handling

The plugin wraps its entire logic in a try...catch block. If any critical step fails (fetching records, writing the file to disk, uploading the file to Flatfile), it logs the error and throws a new Error. This causes the associated job in Flatfile to fail and display the error message to the user, providing feedback on what went wrong.