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

Resources in Flatfile come with severaldefault built-in actions like:
  • Export/download data
  • Delete data or files
  • Find and replace (Sheets)

Developer-Created Actions

You can create custom Actions to handle operations specific to your workflow, such as:
  • Sending data to your API when data is ready
  • Downloading your data in a specific format
  • Validating data against external systems
  • Moving data between different resources
  • Custom data validations andtransformations

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. See the Using Actions guide for more details.