Events - flatfile.com

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.

See API Reference

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`

workbook:created

readonly

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`

workbook:updated

readonly

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`

workbook:deleted

readonly

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`

workbook:expired

readonly

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`

document:created

readonly

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`

document:updated

readonly

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`

document:deleted

readonly

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`

sheet:updated

readonly

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`

sheet:deleted

readonly

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`

snapshot:created

readonly

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`

commit:created

readonly

Commits are created when a cell in a Record (which is in a Sheet) is created or updated.

{
  "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`

commit:completed

readonly

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`

layer:created

readonly

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`

file:created

readonly

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`

file:updated

readonly

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`

file:deleted

readonly

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`

file:expired

readonly

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`

job:created

readonly

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`

job:ready

readonly

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`

job:updated

readonly

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`

job:completed

readonly

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`

job:outcome-acknowledged

readonly

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`

job:failed

readonly

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`

job:deleted

readonly

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`

agent:created

readonly

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`

agent:updated

readonly

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`

agent:deleted

readonly

Called when an agent is deleted.

{
  "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`

space:created

readonly

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`

space:updated

readonly

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`

space:deleted

readonly

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`

space:expired

readonly

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`

space:archived

readonly

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`

space:guestAdded

readonly

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`

space:guestRemoved

readonly

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`

secret:created

readonly

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`

secret:updated

readonly

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`

secret:deleted

readonly

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"
  }
}

Documentation

Platform Apps

Orchestration

Reference

​The anatomy of an Event

​Using Events

​Building with events

​Event Topics

​Workbook

​workbook:created

​workbook:updated

​workbook:deleted

​workbook:expired

​Document

​document:created

​document:updated

​document:deleted

​Sheet

​sheet:updated

​sheet:deleted

​Snapshot

​snapshot:created

​Record

​commit:created

​commit:completed

​layer:created

​File Upload

​file:created

​file:updated

​file:deleted

​file:expired

​Jobs

​job:created

​job:ready

​job:updated

​job:completed

​job:outcome-acknowledged

​job:failed

​job:deleted

​Agents

​agent:created

​agent:updated

​agent:deleted

​Space

​space:created

​space:updated

​space:deleted

​space:expired

​space:archived

​space:guestAdded

​space:guestRemoved

​Secret

​secret:created

​secret:updated

​secret:deleted

The anatomy of an Event

Using Events

Building with events

Event Topics

Workbook

`workbook:created`

`workbook:updated`

`workbook:deleted`

`workbook:expired`

Document

`document:created`

`document:updated`

`document:deleted`

Sheet

`sheet:updated`

`sheet:deleted`

Snapshot

`snapshot:created`

Record

`commit:created`

`commit:completed`

`layer:created`

File Upload

`file:created`

`file:updated`

`file:deleted`

`file:expired`

Jobs

`job:created`

`job:ready`

`job:updated`

`job:completed`

`job:outcome-acknowledged`

`job:failed`

`job:deleted`

Agents

`agent:created`

`agent:updated`

`agent:deleted`

Space

`space:created`

`space:updated`

`space:deleted`

`space:expired`

`space:archived`

`space:guestAdded`

`space:guestRemoved`

Secret

`secret:created`

`secret:updated`

`secret:deleted`