Trigger custom operations based on user input
ack
to acknowledge the job, update
to update the job’s progress, and complete
or fail
to complete or fail the job.To make this simpler in practice, we provide a plugin called Job Handler that handles the job lifecycle for you. This plugin works by listening to the job:ready
event and executing the handler callback, even catching errors to fail the job. There is also an optional tick
function which allows you to update the Job’s progress.For example: With the Job Handler plugin, the 35-line File Action Listener defined below would be implemented simply as:Two Workbook Actions: A primary action (Submit to API) and a secondary action (Download XML)
primary: true
on an Action, its button will be highlighted in the Workbook.
If you configure trackChanges: true
, it will disable your actions until all commits are complete (usually data hooks).
job:ready
event for your action.
Two Sheet Actions: A primary action (Populate...) and a secondary action (Validate...)
primary: true
on an Action, it creates a top-level button as well as placing it in the dropdown menu.
job:ready
and filter on the domain
(sheet) and the operation
of where the action was placed. Be sure to complete the job when it’s done.
query
object in the job’s subject that specifies which records to process:
query.filter
is "all"
or undefinedids
or exceptions
arraysquery.filter
indicates the filter type:
"valid"
- Only valid records (no errors)"error"
- Only records with validation errorsq
parameter for advanced filteringquery.ids
contains specific record IDs to INCLUDEquery.ids
contains record IDs to EXCLUDE from the filtered resultsExample Field Action dropdown in column header (Capitalize All Values)
primary
property does not affect the UI for Field actions.
sheet:
, and the column key is available in the job data.job:ready
event for your field action. Field actions use the sheet:operationName
job pattern and provide field context through the job’s subject parameters.
sheet:operationName
job.subject.params.columnKey
Example Document Action
primary: true
on an Action, it will be highlighted in the Document.
actions
parameter when you create a Document.
Example File Action (Log File Metadata)
file:ready
event and add one or more actions to the file.
job:ready
and filter on the domain
(file) and the operation
of where the Action was placed. Be sure to complete the job when it’s done.
Parameter | Type | Description |
---|---|---|
operation | 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. |
label | string | The text that will be displayed to the user in the UI as a button or menu item. |
Parameter | Type | Default | Description |
---|---|---|---|
primary | boolean | false | Whether the Action is a primary Action for the resource. Primary Actions are displayed more prominently in the UI. |
confirm | boolean | true | When set to true, a modal is shown to confirm the Action. |
description | string | - | The text displayed to the user when a confirmation modal is used. Phrase this as a question. |
icon | string | lightning bolt | The icon to be displayed. Use 'none' to omit the icon. See Flatfile icons for available options. |
tooltip | string | - | Text displayed as a tooltip when hovering over the action button or menu item. |
messages | array[{}] | - | Custom messages displayed as tooltips based on action state. Supports [{ type: 'error' }] and [{ type: 'info' }] . |
constraints | array[{}] | - | Conditions that disable the action. Options: hasAllValid , hasSelection , hasData . |
mode | string | background | Execution mode: foreground , background , or toolbarBlocking . |
hasAllValid
: Disables action when there are invalid recordshasSelection
: Disables action when no records are selected (Sheet actions only)hasData
: Disables action when there are no recordsforeground
: Prevents interacting with the entire resource until completebackground
: Runs in the background without blocking the UItoolbarBlocking
: Disables sheet-level toolbar and column header menus while allowing manual record entryExample Input Form
Parameter | Type | Required | Description |
---|---|---|---|
type | string | ✓ | The type of the input form. Currently accepts: simple |
fields | array[object] | ✓ | An array of field objects representing the input form fields |
Parameter | Type | Required | Description |
---|---|---|---|
key | string | ✓ | The key for the field |
label | string | ✓ | The label for the field |
type | string | ✓ | Field type: string , textarea , number , boolean , or enum |
defaultValue | string | - | The default value for the field |
description | string | - | A description of the field |
config | object | - | Configuration options for the field (required for enum type) |
constraints | array[object] | - | An array of constraints for the field |
Parameter | Type | Required | Description |
---|---|---|---|
options | array[object] | ✓ | An array of options for the field |
Parameter | Type | Required | Description |
---|---|---|---|
value | string | ✓ | 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 |
Parameter | Type | Required | Description |
---|---|---|---|
type | string | ✓ | The type of constraint. Currently accepts: required |
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.
hasAllValid
constraint on an Action will disable a Workbook Action when there are invalid records.hasData
on an Action will disable a Workbook Action when there are no records.hasSelection
on an Action will disable a Sheet Action when no records in the Sheet are selected.