The anatomy of Events and Listeners - core components of the Flatfile Platform
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", ... } |
**
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.listener.on()
listener.on()
method is the fundamental pattern for responding to specific events. This method allows you to provide a callback function that will be executed when the specified event occurs.
For a complete list of Events published by Flatfile, see Events Reference.
Type Signature:
listener.use()
listener.use()
method is for building and distributing listener functions in a modular manner. It allows you to send your own Listener functions as a callback to the method, each of which receives a FlatfileListener
instance as their argument.
Inside that callback function, you can use listener.on()
to register Event handlers or introduce various Plugins to your listener. The result can be an index
file with with little more than listener.use()
calls, each of which distributes your listener function to other places in your codebase:
Method | Use For |
---|---|
listener.use() | Creating reusable functions, organizing complex logic into modules |
listener.on() | Responding to specific Events, implementing direct Event handlers |
listener.namespace()
and listener.filter()
.
Namespaces provide architectural boundaries for organizing different parts of your application at the App, Space, and Workbook level:
space:customer-portal
- Events from Spaces in the “customer-portal” Appworkbook:staging
- Events from Workbooks with “staging” namespace{ sheet: 'contacts' }
- Events from the “contacts” Sheet{ domain: 'job', 'payload.job': 'space:configure' }
- Space configuration Jobs-s
flag to give your Agent a unique slug. This is useful when managing multiple Agents in the same Environment.
default
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.
develop
command to test, these logs will not be recorded in your dashboard. You can still view them in your terminal.