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`

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`

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`

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`

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`

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`

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`

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`

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`

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`

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`

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

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`

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`

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`

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`

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`

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`

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`

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`

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`

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`

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`

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`

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`

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`

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`

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

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`

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`

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`

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`

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`

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`

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`

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`

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`

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

​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

​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

​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`

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

Space

`space:created`

`space:updated`

`space:deleted`

`space:expired`

`space:archived`

`space:guestAdded`

`space:guestRemoved`

Secret

`secret:created`

`secret:updated`

`secret:deleted`