<Flatfile />
Embed Flatfile in just a few lines of code.
<Flatfile />
Embed Flatfile in just a few lines of code.
<Flatfile />
Embed Flatfile in just a few lines of code.
{/*Button to trigger the modal */}
{showSpace &&
We are going to import your data now. Click the button below to start your import
```
We are going to import your data now. Click the button below to start your import
```
We are going to import your data now. Click the button below to start your import
```
<Flatfile />
Choose what you want to do!
``` Now you'll need to build the component that will get your space and return it to the browser. The component should end up looking something like this: ```TypeScript src/components/ExistingSpace.vue ``` You'll need to update your `App.vue` to include the existing space component. It should end up looking like the example below: ```TypeScript src/App.vue
<Flatfile />
Embed Flatfile in just a few lines of code.
<Flatfile />
Embed Flatfile in just a few lines of code.
Choose what you want to do!
```Learn more about Flatfile by understanding our core elements.
### Reference
[See API Reference](https://reference.flatfile.com/api-reference/spaces/create)
#### `Workbooks` *object*
A Space contains any number of Workbooks. Each
[Learn more](https://flatfile.com/platform/workbooks/) about the upcoming features and capabilities.
With Workbooks, you can:
1. Accept data from many file types beyond CSVs. (And you can write your own
file extractors if you can't find a plugin.)
2. Automatically apply any validation rules a developer has previously defined.
3. Provide end users the ability to add, remove, review, filter, and correct any
data imported into a Workbook.
4. Define, in code, at least one primary Action that submits the reviewed data
to a destination API, database, or workflow step of your choosing.
***
## Anatomy
A Workbook is comprised of one or more
### Reference
[See API Reference](https://reference.flatfile.com/api-reference/workbooks/create-a-workbook)
#### `Sheets` *array*
A schema contains Sheets. Like tables in a database or sheets in a spreadsheet,
Sheets isolate different data schemas.
[Learn more about Blueprint](/learning-center/blueprint/about)
#### `Fields` *array*
Sheets contain
Finally, when your Job is complete, update the Job's status to `complete`. This status update includes an optional outcome message which will be displayed to the user.
Use this to provide detail on the outcome of the Job.
### Jobs.Complete
Once a job is complete, you can display an alert to the end user using `outcome`.
```jsx javascript
await api.jobs.complete(jobId, {
outcome: {
message: `Operation was completed succesfully. ${myData.length} records were processed.`,
acknowledge: true,
},
});
```
#### Outcome.Next
Optionally, you can add a button to the outcome dialog to control the next step in the workflow once job has finished.
##### Internal Link
Add a button to the dialog that will redirect the user somewhere within a Space using `next > Id`.
In this code below, we will create a button that says "See all downloads" with this path: `space/us_sp_1234/files?mode=export`
```jsx javascript
await api.jobs.complete(jobId, {
outcome: {
message: `Operation was completed succesfully. ${myData.length} records were processed.`,
acknowledge: true,
//Reference: https://platform.flatfile.com/space/{$id}/{path}?{$query}
next: {
type: "id",
id: "dev_sp_1234",
path: "files",
query: "mode=export",
label: "See all downloads",
},
},
});
```
##### External Url
Add a button to the dialog that will redirect the user to an external link using `next > Url`.
In this code below, we will create a button that says "Go to Google". It will open in a new tab.
```jsx javascript
await api.jobs.complete(jobId, {
outcome: {
message: `Operation was completed succesfully. ${myData.length} records were processed.`,
acknowledge: true,
next: {
type: "url",
url: "http://www.google.com",
label: "Go to Google",
},
},
});
```
##### Download
Add a button to the dialog that will redirect the user to an external link using `next > Url`.
In this code below, we will create a button that says "Download this file".
```jsx javascript
await api.jobs.complete(jobId, {
outcome: {
message: `Operation was completed succesfully. ${myData.length} records were processed.`,
acknowledge: true,
next: {
type: "download",
fileName: "DownloadedFromFlatfile.csv",
url: "source_of_file.csv",
label: "Download this file",
},
},
});
```
##### Snapshot
Add a button to the dialog that will redirect the user a particular snapshot using `next > snapshot`.
In this code below, we will create a button that says "Go to Snapshot".
```jsx javascript
await api.jobs.complete(jobId, {
outcome: {
message: `Operation was completed succesfully.`,
acknowledge: true,
next: {
type: "snapshot",
label: "Go to Snapshot",
snapshotId: ${snapshot.id},
sheetId: ${sheet.id}
},
},
});
```
##### Files
Download files hosted on Flatfile by using `next > files`.
In this code below, we will create a button that says "Download files".
```jsx javascript
await api.jobs.complete(jobId, {
outcome: {
message: `The files should download automatically`,
next: {
type: "files",
label: "Download files",
files: [{fileId: "us_fl_123"}],
},
},
});
```
##### View
Dynamically update the columns visible in a sheet by using `next > view`.
In this code below, we will create a button that says "Hide columns".
```jsx javascript
await api.jobs.complete(jobId, {
outcome: {
message: `Operation was completed on sheet ${sheet.name}`,
acknowledge: true,
next: {
type: "view",
label: "Hide columns",
sheetId: ${sheet.id},
hiddenColumns: ['age', 'phone', 'middleName'] //a list of field keys on the sheet
},
},
});
```
##### Retry
Often in the event of a failure, you may want to add a button to the dialog that will retry the Job using `next > Retry`.
In this code below, we will create a button that says "Retry".
```jsx javascript
await api.jobs.complete(jobId, {
outcome: {
message: `Operation was not completed succesfully. No records were processed.`,
acknowledge: true,
next: {
type: "retry",
label: "Try again",
},
},
});
```
# Listeners
Source: https://flatfile.com/docs/learning-center/concepts/listeners
The anatomy of Listeners
## What is a Listener?
Listeners are the core of the Flatfile Platform. All of your configurations,
from [data transformations](https://flatfile.com/plugins/category/transform), to
[custom styling](/learning-center/guides/theming), to [data export](/learning-center/guides/egress) are done in
a Listener. They hold the logic backing your Flatfile Spaces, defining the
functionality of your implementation.
Fundamentally, a Listener is a function that listens for
[Events](/learning-center/concepts/events) and takes action when they occur. This means
your configurations are implemented in response to events. To understand how to
configure a Listener, it's important to understand the anatomy of an Event.
## An Event-Driven System
Flatfile is an event-driven system, meaning interactions with Flatfile (clicking
a button, editing a record, uploading a file, etc) trigger the publication of an
[Event](/learning-center/concepts/events).
Each Event contains information about its source and execution context including
a domain, topic, context, and optionally, a payload.
| Component | Description | Example |
| ------------------ | ------------------------------------------------- | ------------------------------------------------------------------ |
| Domain | the jurisdiction of the event | record, sheet, workbook, space, file, job, agent |
| Topic | a combination of a domain and an action | `workbook:created` `workbook:updated` `workbook:deleted` |
| Context | detailed information about context of the event | `{ spaceId: "us_sp_1234", fileId: "us_fl_1234", ... }` |
| Payload (optional) | detailed information about execution of the event | `{ status: "complete", workbookId: "us_wb_1234", ... }` |
# Anatomy of a Listener
A Listener is a function designed to receive Events as they occur and take
action by executing a callback function. For example, when a file is uploaded, a
Listener can [extract](https://flatfile.com/plugins/category/extractors) its
data to a target sheet, or when a record is created, a Listener can
[validate](/learning-center/guides/handling-data) the data.
The callback function can be as simple as logging the event or as advanced as
integrating with external systems. Here is an example that logs the topic of any
incoming event:
### Merging Changes
Once changes are finalized, they can be merged back into the main sheet, ensuring controlled updates while preserving the original dataset's integrity.
When merging a Data Clip, a visual diff of all changes allows users to confirm updates before they are applied.