Events
The Flatfile platform includes a REST APIView API reference 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.
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
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"
}
}
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"
}
}
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"
}
}
Called when a new sheet is created within a workbook.
Called when a sheet is updated. For example, running sheet level validations. Adding data to a sheet does not emit this event.
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)"
}
Called when a new commit is created. For example, by creating or updating a cell.
{
"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)",
}
Called when commit metadata is updated. For example, approving or merging a commit. Commits cannot be deleted.
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
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"
},
"target": "space(*)"
}
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"
},
"target": "space(*)"
}
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"
},
"target": "space(*)"
}
Jobs
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"
}
}
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.
{
"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"
}
}
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.
{
"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"
}
}
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"
}
}
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"
}
}
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"
}
}
Called when a job has failed and needs to rerun. This event is not currently implemented.
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
Called when a new agent is deployed.
Called when an agent is updated.
Called when an agent is deleted.
Space
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"
}
}
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"
}
}
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"
}
}