Actions
The anatomy of 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. Additional Actions can be mounted on a Sheet, a Workbook, or a File by a developer.
Learn more about implementing actions in practice in our Using Actions guide.
Types of Actions
Built-in Actions
Workbooks, Sheets and Files come with five default built-in actions:
- Mapping data from one workbook to another (moving data from a workbook to a Workbook)
- Deleting data from a Workbook (or the entire file)
- Exporting (downloading) data from a Workbook (or a file)
- Find and Replacing data in a Sheet
- 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:
operation
string required
A unique identifier for the Action that is used by the listener to determine what work to do as part of the resulting Job.
label
string required
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
boolean default: “false”
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
boolean default: “true”
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.
icon
string
The icon to be displayed. Default is a lightning bolt. If you want to omit the icon, use 'none'. All available icons are listed here: Flatfile icons. If the label is empty, then an icon will always be displayed.
tooltip
string
Setting this will display text in the UI for both buttons and list items as a tooltip on hover.
messages
array[{}]
Setting this will display text on disabled actions [based on the state of the action] in the UI for both buttons and list items as a tooltip on hover.
[{ type: 'error' }]
[{ type: 'info' }]
constraints
array[{}]
[{ type: 'hasAllValid' }]: Adding this constraint will disable a Sheet or Workbook Action when there are invalid records.
[{ type: 'hasSelection' }]: Adding this constraint will disable a Sheet or Workbook Action when no records are selected.
[{ type: 'hasData' }]: Adding this constraint will disable a Sheet or Workbook Action when there are no records.
mode
string default: “background”
Can be foreground, background or toolbarBlocking. Foreground mode will prevent interacting with the entire resource until complete. toolbarBlocking disables the sheet-level toolbar and Column Header menus, while still allowing users to enter records manually.
Usage
An Action with all of the above properties would look like this:
inputForm
When initiating an action, there may be instances where additional information is required from the end user to successfully complete the intended task. For example, you might want to enable users to specify the name of the file they intend to export.
In such cases, 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 seamlessly
inputForm
object
An object representing the input form configuration for the action.
type
string required
The type of the input form. Accepts: simple
fields
fields
array[object]
An array of field objects representing the input form fields.
key
string required
The key for the field.
label
string required
The label for the field.
type
string required
The type of the field. Accepts: string | textarea | number | boolean | enum
defaultValue
string
The default value for the field.
description
string
A description of the field.
config
config
array[object]
An object containing configuration options for the field.
options
array required
An array of options for the field, each represented as an object.
value
string required
The value or ID of the option.
label
string
A visual label for the option.
description
string
A short description of the option.
meta
object
An arbitrary JSON object associated with the option.
constraints
constraints
array[object]
An array of constraints for the field.
type
string required
The type of constraint. Accepts: required
Usage
An Action that requests input from the end user using inputForm would look like this. Your listener would then grab this data from the Job and take action on it.
Actions
The anatomy of 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. Additional Actions can be mounted on a Sheet, a Workbook, or a File by a developer.
Learn more about implementing actions in practice in our Using Actions guide.
Types of Actions
Built-in Actions
Workbooks, Sheets and Files come with five default built-in actions:
- Mapping data from one workbook to another (moving data from a workbook to a Workbook)
- Deleting data from a Workbook (or the entire file)
- Exporting (downloading) data from a Workbook (or a file)
- Find and Replacing data in a Sheet
- 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:
operation
string required
A unique identifier for the Action that is used by the listener to determine what work to do as part of the resulting Job.
label
string required
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
boolean default: “false”
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
boolean default: “true”
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.
icon
string
The icon to be displayed. Default is a lightning bolt. If you want to omit the icon, use 'none'. All available icons are listed here: Flatfile icons. If the label is empty, then an icon will always be displayed.
tooltip
string
Setting this will display text in the UI for both buttons and list items as a tooltip on hover.
messages
array[{}]
Setting this will display text on disabled actions [based on the state of the action] in the UI for both buttons and list items as a tooltip on hover.
[{ type: 'error' }]
[{ type: 'info' }]
constraints
array[{}]
[{ type: 'hasAllValid' }]: Adding this constraint will disable a Sheet or Workbook Action when there are invalid records.
[{ type: 'hasSelection' }]: Adding this constraint will disable a Sheet or Workbook Action when no records are selected.
[{ type: 'hasData' }]: Adding this constraint will disable a Sheet or Workbook Action when there are no records.
mode
string default: “background”
Can be foreground, background or toolbarBlocking. Foreground mode will prevent interacting with the entire resource until complete. toolbarBlocking disables the sheet-level toolbar and Column Header menus, while still allowing users to enter records manually.
Usage
An Action with all of the above properties would look like this:
inputForm
When initiating an action, there may be instances where additional information is required from the end user to successfully complete the intended task. For example, you might want to enable users to specify the name of the file they intend to export.
In such cases, 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 seamlessly
inputForm
object
An object representing the input form configuration for the action.
type
string required
The type of the input form. Accepts: simple
fields
fields
array[object]
An array of field objects representing the input form fields.
key
string required
The key for the field.
label
string required
The label for the field.
type
string required
The type of the field. Accepts: string | textarea | number | boolean | enum
defaultValue
string
The default value for the field.
description
string
A description of the field.
config
config
array[object]
An object containing configuration options for the field.
options
array required
An array of options for the field, each represented as an object.
value
string required
The value or ID of the option.
label
string
A visual label for the option.
description
string
A short description of the option.
meta
object
An arbitrary JSON object associated with the option.
constraints
constraints
array[object]
An array of constraints for the field.
type
string required
The type of constraint. Accepts: required
Usage
An Action that requests input from the end user using inputForm would look like this. Your listener would then grab this data from the Job and take action on it.