Guides
Using actions

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.

Custom Actions are configured within a Blueprint. The executable code within an Action is compiled into a Job and can run asyncronously or immediately.

Overview

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

Workbook-mounted custom actions are represented as buttons in the top right of the Workbook. workbook_actions_primary

Usage

Listen for a job:ready and filter on the job you’d like to process. Be sure to complete the job when it’s complete.

If you configure primary: true on a custom action, it will be represented as the rightmost button in the Workbook.

actions: [
  {
    operation: 'submitActionFg',
    mode: 'foreground',
    label: 'Submit data elsewhere',
    type: 'string',
    description: 'Submit this data to a webhook.',
    primary: true,
  },
  {...}
]

Sheet-mounted

Each Sheet has built-in Actions.

Sheet-mounted custom actions are represented as a dropdown in the toolbar of the Sheet. In addition, you can attach a custom action to a Sheet.

sheet actions

Usage

Listen for a job:ready and filter on the domain (sheet) and the operation of where the action was placed. Be sure to complete to job when it’s complete.

sheets : [
  {
    name: "Sheet Name",
    actions: [
      {
        operation: 'capitalizeNamesBg',
        mode: 'background',
        label: 'Capitalize selected names',
        type: 'string',
        description: 'Capitalize names for selected rows',
        primary: true,
      },
      {...}
    ]
  }
]