Events
The anatomy of Events.
The Flatfile platform encompasses a comprehensive suite of tools. Firstly, it offers a REST API, which can be accessed through the , empowering users to effortlessly manipulate resources. Additionally, an Event bus is available for seamless subscription to resource-related notifications.
To simplify the process of utilizing the Flatfile API, the Flatfile PubSub Client serves as a lightweight wrapper. It enables developers to seamlessly trigger API calls upon receiving Events from any PubSub driver, thus ensuring a smooth and streamlined integration process.
The anatomy of an Event
Flatfile Events adhere to a standardized structure, and Event listeners have the flexibility to handle Events within Flatfile using any of the following syntaxes.
Using Events
Once an Event is received, it is routed to any awaiting listeners which are added with addEventListener() or its alias on().
An Event context is passed to an EventFilter
export type EventFilter = Record<string, Arrayable<string>>;
// example event context
{
context: {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"actorId": "us_ag_1234"
}
}
Building with events
By leveraging the robust capabilities of our @flatfile/listener library, we can seamlessly intercept any Event and execute a callback function based on the values encapsulated within the Event itself.
listener.on(
"job:ready",
{ job: "space:configure" },
async (event: FlatfileEvent) => {
//do something here
}
);
Event Topics
Utilize the reference provided by the response of each Event topic to determine the desired outcome or plan subsequent actions accordingly.
Workbook
workbook:created
Called when a new workbook is created.
{
"domain": "workbook",
"topic": "workbook:created",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"jobId": "us_jb_1234",
"actorId": "us_usr_1234"
}
}
workbook:updated
Called when workbook metadata is updated. For example, updating the name of a workbook. Adding data to a workbook does not emit this Event.
{
"domain": "workbook",
"topic": "workbook:updated",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"workbookId": "us_wb_1234",
"actorId": "us_ag_1234"
}
}
workbook:deleted
Called when a workbook is deleted.
{
"domain": "workbook",
"topic": "workbook:deleted",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"workbookId": "us_wb_1234",
"actorId": "us_ag_1234"
}
}
workbook:expired
Called when a workbook is expired.
{
"domain": "workbook",
"topic": "workbook:expired",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"workbookId": "us_wb_1234"
}
}
Document
document:created
Called when a document is created on a workbook.
{
"domain": "document",
"topic": "document:created",
"context": {
"actorId": "us_key_1234",
"spaceId": "us_sp_1234",
"accountId": "us_acc_1234",
"documentId": "us_dc_1234",
"environmentId": "us_env_1234"
}
}
document:updated
Called when a document is updated on a workbook.
{
"domain": "document",
"topic": "document:updated",
"context": {
"actorId": "us_key_1234",
"spaceId": "us_sp_1234",
"accountId": "us_acc_1234",
"documentId": "us_dc_1234",
"environmentId": "us_env_1234"
}
}
document:deleted
Called when a document is deleted on a workbook.
{
"domain": "document",
"topic": "document:deleted",
"context": {
"actorId": "us_key_1234",
"spaceId": "us_sp_1234",
"accountId": "us_acc_1234",
"documentId": "us_dc_1234",
"environmentId": "us_env_1234"
}
}
Sheet
sheet:updated
Called when a sheet is updated. For example, running sheet level validations. Adding data to a sheet does not emit this event.
{
"domain": "sheet",
"topic": "sheet:updated",
"context": {
"slugs": { "sheet": "contacts" },
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"workbookId": "us_wb_1234",
"sheetId": "us_sh_1234",
"sheetSlug": "contacts",
"actorId": "us_ag_XRGmuGfL"
}
}
sheet:deleted
Called when a sheet is deleted.
{
"domain": "sheet",
"topic": "sheet:deleted",
"context": {
"slugs": { "sheet": "contacts" },
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"workbookId": "us_wb_1234",
"sheetId": "us_sh_1234",
"sheetSlug": "contacts",
"actorId": "us_ag_XRGmuGfL"
}
}
Snapshot
snapshot:created
Called when a snapshot is created of the sheet. This can be triggered by the API endpoint or when AI Assist is used to modify a sheet.
{
"domain": "sheet",
"topic": "snapshot:created",
"context": {
"appId": "us_app_1234",
"accountId": "us_acc_1234",
"snapshotId": "us_ss_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"workbookId": "us_wb_1234",
"sheetId": "us_sh_1234",
"actorId": "us_ag_XRGmuGfL"
}
}
### Record
#### `commit:created`
<ParamField path="commit:created" type="readonly">
Commits are created when a cell in a Record (which is in a Sheet) is created
or updated.
</ParamField>
```json
{
"domain": "workbook",
"topic": "commit:created",
"context": {
"slugs": { "sheet": "MasterWorkbook/Data" },
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"workbookId": "us_wb_1234",
"sheetId": "us_sh_1234",
"sheetSlug": "MasterWorkbook/Data",
"versionId": "us_vr_1234",
"actorId": "us_usr_1234"
}
}
commit:completed
This only runs when trackChanges is enabled on the workbook. This event fires when a commit has completed and any record changes have finished.
{
"domain": "workbook",
"topic": "commit:completed",
"context": {
"appId": "us_app_1234",
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"workbookId": "us_wb_1234",
"sheetId": "us_sh_1234",
"versionId": "us_vr_1234",
"actorId": "us_usr_1234",
"commitId": "us_vr_1234"
}
}
layer:created
Called when a new layer is created within a commit. A layer is a programmatically generated artifact of a commit. For example, when a data hook or formatting rule applies formatting or validation automatically. Layers cannot be updated or deleted, but you can ignore them to see the original source data.
File Upload
file:created
Called when a file upload begins or a new file is created.
{
"domain": "file",
"topic": "file:created",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"fileId": "us_fl_1234",
"actorId": "us_usr_1234"
}
}
file:updated
Called when a file is updated. For example, when a file has been extracted into a workbook.
{
"domain": "file",
"topic": "file:updated",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"fileId": "us_fl_1234",
"actorId": "us_acc_1234"
},
"payload": {
"status": "complete",
"workbookId": "us_wb_1234"
}
}
file:deleted
Called when a file is deleted.
{
"domain": "file",
"topic": "file:deleted",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"fileId": "us_fl_1234",
"actorId": "us_usr_1234"
}
}
file:expired
Called when a file is expired.
{
"domain": "file",
"topic": "file:expired",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"fileId": "us_fl_1234"
}
}
Jobs
job:created
Called when a new job is first created. Some jobs will enter an optional planning state at this time. A job with ‘immediate’ set to true will skip the planning step and transition directly to ‘ready.’
{
"domain": "job", //job domain
"topic": "job:created",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"jobId": "us_jb_1234",
"actorId": "us_usr_1234"
},
"payload": {
"job": "space:configure", //this is domain:operation
"info": null,
"domain": "space", //event domain
"status": "created",
"operation": "configure"
}
}
job:ready
Called when a new job is ready to execute. Either the job has a complete plan of work or the job is configured to not need a plan. This is the only event most job implementations will care about. Once a ready job is acknowledged by a listener, it transitions into an executing state.
{
"domain": "job", //job domain
"topic": "job:ready",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"jobId": "us_jb_1234",
"actorId": "us_usr_1234"
},
"payload": {
"job": "space:configure", //this is domain:operation
"info": null,
"domain": "space", //event domain
"status": "ready",
"operation": "configure"
}
}
job:updated
Called when a job is updated. For example, when a listener updates the state or progress of the job. The event will emit many times as the listener incrementally completes work and updates the job.
{
"domain": "job", //job domain
"topic": "job:updated",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"jobId": "us_jb_1234",
"actorId": "us_usr_1234"
},
"payload": {
"job": "space:configure", //this is domain:operation
"info": null,
"domain": "space", //event domain
"status": "ready",
"operation": "configure"
}
}
job:completed
Called when a job has completed.
{
"domain": "job", //job domain
"topic": "job:completed",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"jobId": "us_jb_1234",
"actorId": "us_usr_1234"
},
"payload": {
"job": "space:configure", //this is domain:operation
"info": "Configuring space...",
"domain": "space", //event domain
"status": "complete",
"operation": "configure"
}
}
job:outcome-acknowledged
Called to trigger workflow actions after the user has acknowledged that the job has completed or failed. Background jobs will skip this step.
{
"domain": "job", //job domain
"topic": "job:outcome-acknowledged",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"workbookId": "us_wb_1234",
"sheetId": "us_sh_1234",
"jobId": "us_jb_1234",
"actorId": "us_usr_1234"
},
"payload": {
"job": "sheet:buildSheet", //this is domain:operation
"info": null,
"domain": "sheet", //event domain
"status": "failed",
"operation": "buildSheet"
}
}
job:failed
Called when a job fails.
{
"domain": "job", //job domain
"topic": "job:failed",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"workbookId": "us_wb_1234",
"sheetId": "us_sh_1234",
"jobId": "us_jb_1234",
"actorId": "us_usr_1234"
},
"payload": {
"job": "sheet:buildSheet", //this is domain:operation
"info": null,
"domain": "sheet", //event domain
"status": "failed",
"operation": "buildSheet"
}
}
job:deleted
Called when a job is deleted.
{
"domain": "job",
"topic": "job:deleted",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"jobId": "us_jb_1234",
"actorId": "us_ag_1234"
}
}
Agents
agent:created
Called when a new agent is deployed.
{
"domain": "space",
"topic": "agent:created",
"context": {
"actorId": "us_ag_1234",
"accountId": "us_acc_1234",
"environmentId": "us_env_1234"
}
}
agent:updated
Called when an agent is updated.
{
"domain": "space",
"topic": "agent:updated",
"context": {
"actorId": "us_ag_1234",
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"agentId": "us_ag_1234"
}
}
#### `agent:deleted`
<ParamField path="agent:deleted" type="readonly">
Called when an agent is deleted.
</ParamField>
```json
{
"domain": "space",
"topic": "agent:deleted",
"context": {
"actorId": "us_ag_1234",
"accountId": "us_acc_1234",
"environmentId": "us_env_1234"
"agentId": "us_ag_1234"
}
}
Space
space:created
Called when a new space is created.
{
"domain": "space",
"topic": "space:created",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"actorId": "us_usr_1234"
}
}
space:updated
Called when a space is updated.
{
"domain": "space",
"topic": "space:updated",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"actorId": "us_usr_1234"
}
}
space:deleted
Called when a space is deleted.
{
"domain": "space",
"topic": "space:deleted",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"workbookId": "us_wb_1234",
"actorId": "us_usr_1234"
}
}
space:expired
Called when a space is expired.
{
"domain": "space",
"topic": "space:expired",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"workbookId": "us_wb_1234"
}
}
space:archived
Called when a space is archived.
{
"domain": "space",
"topic": "space:archived",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234"
}
}
space:guestAdded
Called when a guest is added.
{
"domain": "space",
"topic": "space:guestAdded",
"context": {
"actorId": "us_usr_1234",
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234"
}
}
space:guestRemoved
Called when a guest’s access is revoked from a space.
{
"domain": "space",
"topic": "space:guestRemoved",
"context": {
"actorId": "us_usr_1234",
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234"
}
}
Secret
secret:created
Called when a new secret is created.
{
"domain": "secret",
"topic": "secret:created",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"actorId": "us_usr_1234"
}
}
secret:updated
Called when a secret is updated.
{
"domain": "secret",
"topic": "secret:updated",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"actorId": "us_usr_1234"
}
}
secret:deleted
Called when a secret is deleted.
{
"domain": "secret",
"topic": "secret:deleted",
"context": {
"accountId": "us_acc_1234",
"environmentId": "us_env_1234",
"spaceId": "us_sp_1234",
"actorId": "us_usr_1234"
}
}