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. Additional Actions can be mounted on a Sheet, a Workbook, or a file by a developer.

Types of Actions

Built-in Actions

Workbooks, Sheets and files come with five default built-in actions:

  1. Mapping data from one workbook to another (moving data from a workbook to a Workbook)
  2. Deleting data from a Workbook (or the entire file)
  3. Exporting (downloading) data from a Workbook (or a file)
  4. Find and Replacing data in a Sheet
  5. Applying a Mutate function to data in a Sheet

When these built-in actions are clicked, they create Jobs. You can listen for these events and take appropriate actions if required. Learn more about Jobs.

Developer-Created Actions

Additional Actions can be mounted on a Sheet, a Workbook, or a file. When an action is clicked, it will create a job operation on the domain it is mounted.

For example, an Action with the property operation: 'my-action' placed on a Workbook would spawn a job called: workbook:my-action. This is the job you’d listen for to respond accordingly.

The Anatomy of an Action

Required Parameters

All Actions contain the the information needed to let a user run the Action. This includes:

operationrequired
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.

labelrequired
string

The text that will be displayed to the user in the UI as a button or menu item.

Optional Parameters

Optionally, an Action can also contain extra details about how it appears in the UI. These include:

primary
Default: "false"
boolean

Whether the Action is a primary Action for the resource. Depending on the resource, primary Actions are displayed in the UI in a more prominent way.

confirm
Default: "true"
boolean

When set to true, a modal is shown to confirm the Action.

description
string

The text that will be displayed to the user when a confirmation modal is used. Phrase this as a question.

requireSelection
Default: "false"
boolean

Setting this to true will disable a Sheet Action when no records in the Sheet are selected.

requireAllValid
Default: "false"
boolean

Setting this to true will disable a Sheet Action when there are invalid records.

mode
Default: "background"
string

Can be foreground or background. Foreground mode will prevent interacting with the resource until complete.

tooltip
string

Setting this will display the text in the UI for both buttons and list items as a tooltip on hover.

Usage

An Action with all of the above properties would look like this:

{
  operation: 'my-action',
  label: 'My Action',
  primary: true,
  confirm: true,
  description: 'Are you sure you want to run this action?',
  requireSelection: true,
  requireAllValid: true,
  mode: 'foreground'
  tooltip: 'Click to run action'
}

Learn more

Guides

Learn more about Workbook, Sheet, and File Actions.

Example Projects

Find an Actions example in the Flatfile GitHub repository.