Events and Listeners

The anatomy of Events and Listeners - core components of the Flatfile Platform

Events

Flatfile publishes an Event whenever something happens - editing a record, uploading a file, clicking an action button. Events carry structured information about what occurred, including the context and any relevant data.

Each Event includes a domain, topic, context, and optional payload:

Component	Description	Example
Domain	the jurisdiction of the event	record, sheet, workbook, space, file, job, agent
Topic	a combination of a domain and an action	workbook:created workbook:updated workbook:deleted
Context	detailed information about context of the event	{ spaceId: "us_sp_1234", fileId: "us_fl_1234", ... }
Payload (optional)	detailed information about execution of the event	{ status: "complete", workbookId: "us_wb_1234", ... }

Listeners

Listeners are functions you write that respond to Events by executing custom code. They enable all the powerful functionality in your Flatfile implementation: data transformations, validations, integrations, and workflows. Listeners define how your Spaces behave and what happens when users interact with your data.

How Listeners Work

A Listener receives Events as they occur and executes a callback function in response. For example, when a file is uploaded, a Listener can extract its data to a target sheet, or when a record is created, a Listener can validate the data.

The callback function can be as simple as logging the event or as advanced as integrating with external systems. Here is an example that logs the topic of any incoming event:

Note: The ** wildcard is a catch-all that will match all events. This is useful for testing, but should be avoided in production as it can lead to performance issues.

export default function (listener) {
  listener.on("**", (event) => {
    console.log(`Received event: ${event.topic}`);
  });
}

For a complete list of events that can be listened to, see Events Reference.

Filtering

Listeners may be notified of every event on your Environment, but the Events that a Listener responds to are configurable. You can target which events your code responds to in a few ways.

One way is to use a filter. A filter is a string that matches the topic of an event. For example, the filter “commit:created” will match any event of that topic. For more sophisticated filtering techniques with complex conditions, see our Advanced Filters guide.

A simple way to filter events is to use the shorthand syntax listener.on:

listener.on("commit:created", { sheet: "contacts" }, async (event) => {
  // Custom action responding to the commit
});

This is equivalent to:

listener.filter({ sheet: "contacts" }).on("commit:created", async (event) => {
  // Custom action responding to the commit
});

For cases when you want to use multiple listeners under one filter, this syntax may be useful:

export default function flatfileEventListener(listener) {
  listener.filter({ sheet: "contacts" }, (filteredListener) => {
    filteredListener.on("commit:created", async (event) => {
      // Custom action responding to the commit
    })
    filteredListener.on("record:deleted", async (event) => {
      // Custom action responding to the record deletion
    })
  })
});

Namespaces

Namespaces are another way to organize Listener configurations and target specific Events. If you have two different workflows, for example, you can assign them to different namespaces to keep them separate. Learn advanced namespace scoping strategies →

To configure a listener to only act on events for a given namespace, simply use the listener.namespace method.

In this example we’re configuring a listener to only act on events for the “green” Space. This could be useful if you have specific logic that only applies to a single customer.

listener.namespace(['space:green'], (listener) => { ... })

This will scope the listener to only respond to events that match the namespace - in this example, sheets with the slug “green”.

Listener Types

Listeners can be hosted everywhere from your local machine to Flatfile’s secure cloud. The location of your listener determines the type of listener it is.

Listener	Location	Description
development	developer machine	local listener for development
client-side	user machine	browser embedded listener
Agent	Flatfile secure cloud	Flatfile hosted server-side listener
server-side	your secure server	self-hosted server-side listener

Flatfile Listeners can be either client-side or server-side.

Client-side listeners run in the end user’s web browser and respond to user interactions. Client-side listeners are perfect for scenarios that need to tap into values available in the browser, such as the current user’s session or the current page URL.

Server-side listeners run where deployed, either on your own servers or on Flatfile’s secure cloud, and can perform more complex tasks like running intensive calculations or using secured credentials to integrate with external systems.

Server-side listeners can leverage packages that need the capabilities of a server environment.

Agents

In Flatfile, an Agent refers to a server-side listener bundled and deployed to Flatfile to be hosted in our secure cloud. You may deploy multiple Agents to a single Environment, each with its own configurations and codebase. But be careful, as multiple Agents can interfere with each other if not properly managed.

Agent Deployment

To deploy an Agent, run the following command in your terminal from the root directory containing your listener file:

npx flatfile@latest deploy

The CLI will automatically examine your listener code and register itself to listen to only the events your listener is configured to handle.

Deployment Options

Unique Slug: Use the -s flag to give your Agent a unique slug. This is useful when managing multiple Agents in the same Environment.

npx flatfile@latest deploy -s my-custom-agent

Multiple Agents: You may deploy multiple Agents to a single Environment, each with its own configurations and codebase. However, be careful as multiple Agents can interfere with each other if not properly managed.

If no slug is provided:

• Single Agent: Your Agent will be updated and given a slug of default
• Multiple Agents: The CLI will prompt you to select which Agent to update

Managing Multiple Agents

With the capability to deploy multiple Agents within the same Environment, it is crucial to manage them carefully to avoid race conditions and conflicts. When multiple Agents are listening to the same event topics, they can interfere with each other, leading to unpredictable outcomes.

Strategies for Conflict Avoidance

1. Event Filtering: Ensure each Agent listens for specific events to prevent overlap
2. Use Namespaces: Segment Agent operations using namespaces. See comprehensive namespace scoping guide →
3. Unique Topic Handling: Avoid having multiple Agents act on the same event topics

Agent Configuration

When deploying an Agent, the CLI will automatically reduce the topic scope your Agent listens to by examining your listener code and registering itself to listen to only the topics your listener is configured to act on.

For example if your listener code only listens to commit:created events, the CLI will automatically configure the Agent to only listen to commit:created events. If your listener has a wildcard listener **, the CLI will configure the Agent to listen to all events.

Agent Logs

When using Flatfile’s secure cloud to host your listener, you can view the executions of your Agent in the “Event Logs” tab of your dashboard.

Note: If you are running your Agent locally using the develop command to test, these logs will not be recorded in your dashboard.

Event logs are useful in monitoring and troubleshooting your listener. Each execution of your agent is recorded here, including any custom console logs you have configured in your listener code.

Failures

Failures occur when an Agent fails to execute properly. That means either an uncaught error is thrown, or the execution times out.

If you are catching and handling errors within your code, those executions will not be marked as failures. If you would prefer to see them marked this way, re-throw your error after handling to bubble it up to the execution handler.

export default function (listener) {
  //note: listening to all events with a wildcard can be used while testing but is not
  //recommended for production, as it will capture all events and may cause performance issues
  listener.on("**", (event) => {
    try {
      // do something
    } catch (error) {
      // handle error
      throw error; // re-throw error to mark execution as failure
    }
  });
}

Related Concepts

• Events - The building blocks that power Flatfile’s event-driven system
• Jobs - Handle complex or long-running processes asynchronously
• Actions - Custom code-based operations prompted by user interactions