An Action is a code-based operation that runs when a user clicks a button or menu item in Flatfile. Actions can be mounted on Sheets, Workbooks, Documents, or Files to trigger custom operations.

Defining a custom Action is a two-step process:

  1. Define an Action in your Flatfile blueprint or in your code
  2. Create a Listener to handle the Action

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.

For complete implementation details, see our Using Actions guide.

Several Action examples

​
Types of Actions

​
Built-in Actions

Every resource comes with default built-in actions like:

  • Export/download data
  • Delete data or files
  • Find and replace (Sheets)
  • Data mapping operations

​
Developer-Created Actions

You can create custom Actions to handle operations specific to your workflow, such as:

  • Sending webhooks when data is ready
  • Validating data against external systems
  • Moving data between different resources
  • Custom data transformations

​
Where Actions Appear

Actions appear in different parts of the UI depending on where they’re mounted:

  • Workbook Actions: Buttons in the top-right corner of Workbooks
  • Sheet Actions: Dropdown menu in the Sheet toolbar (or top-level button if marked as primary)
  • Document Actions: Buttons in the top-right corner of Documents
  • File Actions: Dropdown menu for each file in the Files list

​
Example Action Configuration

Every Action requires an operation (unique identifier) and label (display text):

{
  operation: "submitActionBg",
  mode: "background",
  label: "Submit",
  type: "string",
  description: "Submit this data to a webhook.",
  primary: true,
},

Actions support additional options like primary status, confirmation dialogs, constraints, and input forms.