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.
.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:
exportWorkbookPlugin
function.
Parameter | Type | Default | Description |
---|---|---|---|
jobName | string | 'workbook:downloadWorkbook' | The name of the job operation that the plugin will listen for. This must match the operation name of an action configured on the workbook. |
excludedSheets | string[] | undefined | An array of sheet slugs to be excluded from the export. |
excludeFields | string[] | undefined | An array of field keys (column names) to be excluded from the export across all sheets. |
excludeMessages | boolean | false | If set to true , validation messages on records will not be included as comments in the cells of the exported Excel file. |
recordFilter | 'valid' | 'error' | 'all' | undefined | Filters the records to be exported. Can be set to ‘valid’ to export only records without errors, or ‘error’ to export only records with errors. |
includeRecordIds | boolean | false | If set to true , a ‘recordId’ column containing the Flatfile internal record ID will be added as the first column in each sheet. |
autoDownload | boolean | false | If set to true , the exported file will be downloaded automatically in the user’s browser upon job completion. If false , the user is directed to the “Files” page in the Flatfile Space to download it. |
filename | string | undefined | A custom filename for the exported file (without the .xlsx extension). If not provided, a filename is generated using the workbook name and a timestamp. |
debug | boolean | false | If set to true , the plugin will output verbose logging to the console, which is useful for development and troubleshooting. |
sheetOptions | Record<string, ExportSheetOptions> | undefined | An object that maps a sheet slug to sheet-specific export options. |
columnNameTransformer | (columnName: string, sheetSlug: string) => string | undefined | A callback function to dynamically transform column names before they are written to the Excel file. |
sheetOptions
parameter allows you to configure specific sheets with the following options:
Option | Type | Description |
---|---|---|
skipColumnHeaders | boolean | If true , the header row with column names is omitted for that sheet. |
origin | number | {row: number, column: number} | Sets the starting cell for the data in the sheet. A number sets the starting row, while an object can set both the starting row and column. |
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.
operation
value in your workbook.config.json
action exactly matches the jobName
used to configure the plugin.
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.
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
).
.xlsx
file to the /tmp
directory of the execution environment, which is standard for serverless functions.
\ / ? * [ ]
). 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.
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.