Actions
Trigger custom operations based on user input
An Action is a code-based operation that runs where that Action is mounted. Actions run when a user clicks the corresponding user prompt in Flatfile.
Overview
When an Action is triggered, it creates a Job that your application can listen for and respond to.
Given that Actions are powered by Jobs, the Jobs Lifecycle pertains to Actions as well. This means that you can update progress values/messages while an Action is processing, and when it’s done you can provide an Outcome, which allows you to show a success message, automatically download a generated file, or forward the user to a generated Document.
Actions are mounted on resources like Workbooks, Sheets, Fields, Documents, and Files.
Generally, Workbook, Sheet, Field, and Document Actions are configured within a Blueprint object, while File Actions are appended to the file during the upload process. Alternatively, Actions can be mounted to any of these resources via API in a Listener.
Sheet Actions can be executed on the entire Sheet, for a filtered view of the Sheet, or selectively for the chosen records. See Sheet Action Execution Modes for details on how actions handle different data selections.
In these examples, we’ll show the full listener lifecycle implementation, complete with ack
to acknowledge the job, update
to update the job’s progress, and complete
or fail
to complete or fail the job.
To make this simpler in practice, we provide a plugin called Job Handler that handles the job lifecycle for you. This plugin works by listening to the job:ready
event and executing the handler callback, even catching errors to fail the job. There is also an optional tick
function which allows you to update the Job’s progress.
For example: With the Job Handler plugin, the 35-line File Action Listener defined below would be implemented simply as:
Workbook Actions

Two Workbook Actions: A primary action (Submit to API) and a secondary action (Download XML)
Once a user has extracted and mapped data into a Workbook, it may be more efficient to run an operation on the entire dataset rather than making atomic transformations at the record- or field-level.
For example:
- Sending a webhook that notifies your API of the data’s readiness
- Populating a Sheet with data from another source
- Adding two different fields together after a user review’s initial validation checks
- Moving valid data from an editable Sheet to a read-only Sheet
Workbook-mounted actions are represented as buttons in the top right of the Workbook.
Usage
If you configure primary: true
on an Action, its button will be highlighted in the Workbook.
If you configure trackChanges: true
, it will disable your actions until all commits are complete (usually data hooks).
Blueprint Configuration
First, configure your action in your Blueprint:
Listener Implementation
Next, create a listener to handle the job:ready
event for your action.
Sheet Actions

Two Sheet Actions: A primary action (Populate...) and a secondary action (Validate...)
Each Sheet has built-in Actions like download.
Sheet-mounted actions are represented as a dropdown in the toolbar of the Sheet.
Usage
If you configure primary: true
on an Action, it creates a top-level button as well as placing it in the dropdown menu.
Blueprint Configuration
First, configure your action on your Blueprint. Add the action configuration to your sheet definition:
Listener Implementation
Next, listen for a job:ready
and filter on the domain
(sheet) and the operation
of where the action was placed. Be sure to complete the job when it’s done.
Sheet Action Execution Modes
Sheet Actions are powerful because they can operate on different subsets of data within a sheet. When a Sheet Action is triggered, it automatically receives context about what data should be processed based on the user’s current view and selections.
How Sheet Actions Handle Data Context
When a Sheet Action job is created, it receives a query
object in the job’s subject that specifies which records to process:
Three Execution Contexts
1. Entire Sheet (No Filter, No Selection)
- Processes all records in the sheet
query.filter
is"all"
or undefined- No
ids
orexceptions
arrays
2. Filtered View
- Processes only records matching the current filter
query.filter
indicates the filter type:"valid"
- Only valid records (no errors)"error"
- Only records with validation errors- Custom filters if applied
- May include search parameters if user has searched
- May include FFQL queries via the
q
parameter for advanced filtering
3. Selected Records
- Processes only user-selected records
- When no other filters applied:
query.ids
contains specific record IDs to INCLUDE - When filters are applied:
query.ids
contains record IDs to EXCLUDE from the filtered results
Implementation Example
Built-in Action Examples
Built-in actions like Delete and Download demonstrate these execution modes:
- Delete All - Removes all records when no selection/filter
- Delete Selected - Removes only selected records
- Delete Valid/Invalid - Removes records matching the current filter
- Download Filtered - Exports only records matching current view
Your custom Sheet Actions automatically inherit this same context-aware behavior.
Field Actions

Example Field Action dropdown in column header (Capitalize All Values)
Field-mounted actions are operations that can be performed on individual columns/fields within a Sheet. They appear as options in the dropdown menu when you click on a column header.
Field actions are particularly useful for:
- Column-specific data transformations (e.g., capitalizing all values in a name field)
- Field-level validation operations
- Data formatting specific to a column type
- Column-specific cleanup operations
Usage
The primary
property does not affect the UI for Field actions.
Note: Field Actions are essentially an extension of Sheet actions - therefore their operation names are prefixed with sheet:
, and the column key is available in the job data.
Blueprint Configuration
First, configure your field action in your Blueprint by adding it to the field definition:
Listener Implementation
Next, create a listener to handle the job:ready
event for your field action. Field actions use the sheet:operationName
job pattern and provide field context through the job’s subject parameters.
Key Differences from Other Action Types
Field actions have several unique characteristics:
- Job Pattern: Use
sheet:operationName
- Context Access: Field key is available via
job.subject.params.columnKey
- UI Location: Appear in column header dropdown menus
- Configuration: Defined within individual field objects in the Blueprint
Document Actions

Example Document Action
Document-mounted actions are similar to Workbook-mounted actions. They appear in the top right corner of your Document.
Usage
If you configure primary: true
on an Action, it will be highlighted in the Document.
Document Configuration
Define Document-mounted Actions using the actions
parameter when you create a Document.
Listener Implementation
In your listener, listen for the job’s event and perform your desired operations.
File Actions

Example File Action (Log File Metadata)
Each file has built-in actions like Delete and Download.
File-mounted actions are represented as a dropdown menu for each file in the Files list. You can attach additional actions to a File.
Usage
You can attach additional actions to a File by listening for file events and updating the file’s actions array.
File Configuration
First, listen for a file:ready
event and add one or more actions to the file.
Listener Implementation
Next, listen for job:ready
and filter on the domain
(file) and the operation
of where the Action was placed. Be sure to complete the job when it’s done.
Action Parameters
Required Parameters
Parameter | Type | Description |
---|---|---|
operation | string | A unique identifier for the Action that is used by the listener to determine what work to do as part of the resulting Job. |
label | string | The text that will be displayed to the user in the UI as a button or menu item. |
Optional Parameters
Parameter | Type | Default | Description |
---|---|---|---|
primary | boolean | false | Whether the Action is a primary Action for the resource. Primary Actions are displayed more prominently in the UI. |
confirm | boolean | true | When set to true, a modal is shown to confirm the Action. |
description | string | - | The text displayed to the user when a confirmation modal is used. Phrase this as a question. |
icon | string | lightning bolt | The icon to be displayed. Use 'none' to omit the icon. See Flatfile icons for available options. |
tooltip | string | - | Text displayed as a tooltip when hovering over the action button or menu item. |
messages | array[{}] | - | Custom messages displayed as tooltips based on action state. Supports [{ type: 'error' }] and [{ type: 'info' }] . |
constraints | array[{}] | - | Conditions that disable the action. Options: hasAllValid , hasSelection , hasData . |
mode | string | background | Execution mode: foreground , background , or toolbarBlocking . |
Constraint Types
hasAllValid
: Disables action when there are invalid recordshasSelection
: Disables action when no records are selected (Sheet actions only)hasData
: Disables action when there are no records
Mode Types
foreground
: Prevents interacting with the entire resource until completebackground
: Runs in the background without blocking the UItoolbarBlocking
: Disables sheet-level toolbar and column header menus while allowing manual record entry
Usage
An Action with all of the above properties would look like this:
Input Forms

Example Input Form
When initiating an action, there may be instances where additional information is required from the end user to successfully complete the intended task. For example, you might want to enable users to specify the name of the file they intend to export.
In such cases, if you configure input fields for your action, a secondary dialog will be presented to the end user, prompting them to provide the necessary information. Once the user has entered the required details, they can proceed with the action seamlessly.
Configuration
Parameter | Type | Required | Description |
---|---|---|---|
type | string | ✓ | The type of the input form. Currently accepts: simple |
fields | array[object] | ✓ | An array of field objects representing the input form fields |
Fields
Parameter | Type | Required | Description |
---|---|---|---|
key | string | ✓ | The key for the field |
label | string | ✓ | The label for the field |
type | string | ✓ | Field type: string , textarea , number , boolean , or enum |
defaultValue | string | - | The default value for the field |
description | string | - | A description of the field |
config | object | - | Configuration options for the field (required for enum type) |
constraints | array[object] | - | An array of constraints for the field |
Config (for enum fields)
Parameter | Type | Required | Description |
---|---|---|---|
options | array[object] | ✓ | An array of options for the field |
Options
Parameter | Type | Required | Description |
---|---|---|---|
value | string | ✓ | The value or ID of the option |
label | string | - | A visual label for the option |
description | string | - | A short description of the option |
meta | object | - | An arbitrary JSON object associated with the option |
Field Constraints
Parameter | Type | Required | Description |
---|---|---|---|
type | string | ✓ | The type of constraint. Currently accepts: required |
Usage
First, configure your action to have an inputForm on your Blueprint. These will appear once the action button is clicked.
Next, listen for a job:ready
and filter on the job
you’d like to process. Grab the data entered in the form from the job itself and leverage it as required for your use case.
Constraints
Usage
Workbook & Sheet Actions
- Adding a
hasAllValid
constraint on an Action will disable a Workbook Action when there are invalid records. - Adding a
hasData
on an Action will disable a Workbook Action when there are no records.
Sheet Actions Only
Adding a constraint of hasSelection
on an Action will disable a Sheet Action when no records in the Sheet are selected.
Messages
Add custom messages to actions, tailored according to their state:
- Error
- Info
These messages will be displayed as tooltips when users hover over an action, providing context-specific text that corresponds to the action’s current state. When an error message is present on an action, the action will be disabled.
Usage
Simply add a messages property to your action configuration. This property should be an array of objects, each specifying a message type and its content.