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.

​

Overview

Workbook & Sheet-mounted Actions are configured within a Blueprint object, while File-mounted actions are appended to the file during the upload process.

The executable code within an Action is compiled into a Job entity, providing the capability to run asynchronously or immediately.

Sheet-mounted actions can be executed on the entire Sheet, for a filtered view of the Sheet, or selectively for the chosen records.

​

Workbook-mounted

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

First, configure your action on your Blueprint.

Next, 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.

​

Document-mounted

Document-mounted actions are similar to Workbook-mounted actions. They appear in the top right corner of your Document:

Read more about Documents here.

​

Usage

Define Document-mounted Actions using the actions parameter when you create a Document.

See full code example in our flatfile-docs-kitchen-sink Github repo.

In your listener, listen for the job’s event and perform your desired operations.

​

Sheet-mounted

Sheet-mounted actions are represented as a dropdown in the toolbar of the Sheet.

​

Usage

First, configure your action on your Blueprint.

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

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 to job when it’s complete.

Get the example in the getting-started repo

​

Retrieving data

Data from the Sheet can be retrieved either by calling the API with records.get or through data passed in through event.data. Here are some examples demonstrating how you can extract data from a Sheet-mounted action:

​

From the entire Sheet

This method allows you to access and process data from the complete Sheet, regardless of the current view or selected records.

//inside listener.on()

const { jobId, sheetId } = event.context;

//retrieve all records from sheet
const response = await api.records.get(sheetId);

//print records
console.log(response.data.records);

​

From a filtered view of the Sheet

By applying filters to the Sheet, you can narrow down the data based on specific criteria. This enables you to retrieve and work with a subset of records that meet the defined filter conditions.

event.data returns a promise resolving to an object with a records property so we extract the records property directly from the event.data object.

//inside listener.on()
const { jobId } = event.context;
const { records } = await event.data;

try {
  if (!records || records.length === 0) {
    console.log("No rows were selected or in view.");
    await api.jobs.fail(jobId, {
      outcome: {
        message: "No rows were selected or in view, please try again.",
      },
    });
    return;
  }

  //print records
  console.log(records);

  await api.jobs.complete(jobId, {
    outcome: {
      message: "Records were printed to console, check it out.",
    },
  });
} catch (error) {
  console.log(`Error: ${JSON.stringify(error, null, 2)}`);

  await api.jobs.fail(jobId, {
    outcome: {
      message: "This action failed, check logs.",
    },
  });
}

​

For chosen records

When rows are selected, event.data will only extract information exclusively for the chosen records, providing focused data retrieval for targeted analysis or operations.

event.data returns a promise resolving to an object with a records property so we extract the records property directly from the event.data object.

//inside listener.on()
const { jobId } = event.context;
const { records } = await event.data;

try {
  if (!records || records.length === 0) {
    console.log("No rows were selected or in view.");
    await api.jobs.fail(jobId, {
      outcome: {
        message: "No rows were selected or in view, please try again.",
      },
    });
    return;
  }

  //print records
  console.log(records);

  await api.jobs.complete(jobId, {
    outcome: {
      message: "Records were printed to console, check it out.",
    },
  });
} catch (error) {
  console.log(`Error: ${JSON.stringify(error, null, 2)}`);

  await api.jobs.fail(jobId, {
    outcome: {
      message: "This action failed, check logs.",
    },
  });
}

​

File-mounted

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

First, listen for a file:ready event and add one or more actions to the file.

Next, listen for job:ready and filter on the domain (file) and the operation of where the Action was placed. Be sure to complete to job when it’s complete.

Get the example in the flatfile-docs-kitchen-sink ts or flatfile-docs-kitchen-sink js repo

​

Actions with Input Forms

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.

​

Usage

First, configure your action to have an inputForm on your Blueprint. These will appear once the action button is clicked.

actions: [
  {
    operation: "submitActionFg",
    mode: "foreground",
    label: "Submit data elsewhere",
    type: "string",
    description: "Submit this data to a webhook.",
    primary: true,
    inputForm: {
      type: "simple",
      fields: [
        {
          key: "priority",
          label: "Priority level",
          description: "Set the priority level.",
          type: "enum",
          defaultValue: "80ce8718a21c",
          config: {
            options: [
              {
                value: "80ce8718a21c",
                label: "High Priority",
                description:
                  "Setting a value to High Priority means it will be prioritized over other values",
              },
            ],
          },
          constraints: [
            {
              type: "required",
            },
          ],
        },
      ],
    },
  },
];

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.

​

Actions with Constraints

​

Usage

​

Workbook & Sheet-mounted

1. Adding a hasAllValid constraint on an Action will disable a Workbook Action when there are invalid records.
2. Adding a hasData on an Action will disable a Workbook Action when there are no records.

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

​

Sheet-Mounted only

Adding a constraint of hasSelection on an Action will disable a Sheet Action when no records in the Sheet are selected.

sheets : [
  {
    name: "Sheet Name",
    actions: [
      {
        operation: 'duplicate',
        mode: 'background',
        label: 'Duplicate selected names',
        description: 'Duplicate names for selected rows',
        constraints: [{ type: 'hasSelection' }],
        primary: true,
      },
      {...}
    ]
  }
]

​

Actions with 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.

  actions: [
    {
      operation: 'duplicate',
      mode: 'background',
      label: 'Duplicate selected names',
      description: 'Duplicate names for selected rows',
      messages: [
        { type: 'error', content: 'This is an error message' },
      ],
      primary: true,
    },
    {...}
  ]

​

Example Project

Find the documents example in the Flatfile GitHub repository.