flatfile.com home pagelight logo
Concepts
Events

The Flatfile platform includes a REST API for manipulating resources and an event bus for subscribing to notifications about those resources.

The Flatfile PubSub Client is a super thin wrapper around the Flatfile API. It allows you to call our API after receiving events from any PubSub driver.

​
The anatomy of an Event

Flatfile events follow a standard structure, and event listeners can use any of the following syntaxes to handle events within Flatfile.

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: {
    sheetSlug: "TestSheet";
  }
}

​
Building with events

Using our powerful @flatfile/listener library we can intervene between any event and run a callback function based on values provided inside that event.

client.on(
  "commit:*", //listens for commit:created & commit:updated
  { target: "sheet(TestSheet)" },
  (event: FlatfileEvent) => {
    //do something here
  }
);

​
Event Topics

​
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"
  }
}
sheet:created
readonly

Called when a new sheet is created within a workbook.

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.

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"
  },
  "target": "sheet(contacts)"
}
commit:created
readonly

Called when a new commit is created. For example, by creating or updating a cell.

commit:created event payload
{
  "domain": "workbook",
  "topic": "commit:created",
  "context": {
    "slugs": { "sheet": "MasterWorkbook/Dat" },
    "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"
  },
  "target": "sheet(DataInReview)",
}
commit:updated
readonly

Called when commit metadata is updated. For example, approving or merging a commit. Commits cannot be deleted.

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.

file:created event payload
{
  "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"
  },
  "target": "space(*)"
}
file:updated
readonly

Called when a file is updated. For example, when a file has been extracted into a workbook.

file:updated event payload
{
  "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"
  },
  "target": "space(*)"
}
file:deleted
readonly

Called when a file is deleted.

file:deleted event payload
{
  "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"
  },
  "target": "space(*)"
}

​
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.’

job:created event payload
{
  "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 transations into an executing state.

job:ready relevant payload
{
  "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 copmletes work and updates the job.

job:updated relevant payload
{
  "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.

job:completed relevant payload
{
  "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.

job:outcome-acknowledged relevant payload
{
  "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.

job:failed event payload
{
  "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:scheduled
readonly

Called when a job has failed and needs to rerun. This event is not currently implemented.

job:deleted
readonly

Called when a job is deleted.

job:deleted event payload
{
  "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.

agent:updated
readonly

Called when an agent is updated.

agent:deleted
readonly

Called when an agent is deleted.

​
Space

space:created
readonly

Called when a new space is created.

space:created relevant payload
{
  "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.

space:updated relevant payload
{
  "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.

space:deleted relevant payload
{
  "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"
  }
}