Isolate and organize your Flatfile Listeners using namespace filtering and advanced Event filtering patterns
space:namespace
- Listen to Events from Spaces with the given namespace or belonging to Apps with that namespaceworkbook:namespace
- Listen to Events from Workbooks with the given namespaceApp settings modal with namespace field ("example-app")
customer-portal
internal-tools
partner-integration
listener.namespace()
to create separate Listeners for Spaces within each App. This will provide a new, filtered Listener object scoped to your callback function.
This pattern allows each App to have completely different:
listener.use()
, as in this example), see Events and Listeners.
space:app-namespace
, they receive Events from spaces within that App.If you override a Space’s namespace to be different from its App, Listeners filtering on the App’s namespace will no longer receive Events from that Space. For example:"my-app"
"my-space"
space:my-space
will receive Events from that Spacespace:my-app
will not receive Events from that Spacespace:configure
Job by updating the Space. This may be useful if you’re creating Spaces from the Flatfile Dashboard, which doesn’t support setting a namespace during creation.
This example shows how to set the namespace based on the Space name, allowing you to have multiple configurations in the same App:
ack
to acknowledge the job, update
to report progress, and complete
or fail
to finish the job.However, for most implementations, we recommend using the Space Configure plugin. This plugin takes care of even more of the heavy lifting for you; not only does it handle the Job lifecycle, but it also takes care of all of the API calls necessary to configure the Space and create its Workbooks and documents.listener.namespace()
to filter Events from Spaces with specific namespaces. This will provide a new, filtered Listener object scoped to your callback function:
workbook:namespace
pattern.
listener.namespace()
function can accept an array of namespace patterns as its first argument, allowing you to listen to Events from multiple namespaces with a single Listener configuration. This is useful when you want to apply the same processing logic across different namespaces.
You can also mix different namespace types in the same array. The Listener in this example will receive Events from both the space:admin-tools
and workbook:critical-data
namespaces:
customer-portal
and vendor-portal
), and each App processes data through different Workbook types (invoices
and orders
). You want to ensure that each App’s Workbooks are completely isolated from the other App, but within each App you want specific handling for each Workbook type.
This example demonstrates how App, Space, and Workbook namespaces work together with nested Listeners:
customer-portal
vendor-portal
listener.filter()
method creates filtered Listener instances that only respond to Events matching specific criteria, returning a new FlatfileListener
instance with the applied filter conditions.
listener.filter()
is to respond to specific Events based on simple criteria. This approach is useful when you want different processing logic for different types of Jobs or Events within the same namespace, without creating separate Event handlers for each case.
*
to match partial values. This may be useful when you want to filter by ID patterns or prefixes.
This example filters for commit:created
events that were initiated by Jobs rather than users. When a Job causes changes to your data (commits), the actorId
in the event context will be the job ID (starting with "us_jb"
):
listener.filter()
method accepts an object defining filter criteria based on Event properties.
console.log()
your events prior to filtering to see what properties are available.Property | Description | Example |
---|---|---|
topic | Event topic pattern | { topic: 'records:created' } |
domain | Event domain (supports wildcards) | { domain: 'space' } |
environmentId | Environment identifier | { environmentId: 'us_env_123' } |
Property | Description | Example | Available In |
---|---|---|---|
spaceId | Specific space | { spaceId: 'us_sp_789' } | Most events (not environment events) |
actorId | Specific actor | { actorId: 'us_usr_123' } | Most user-initiated events |
accountId | Account identifier | { accountId: 'us_acc_123' } | Most events |
Property | Description | Example | Available In |
---|---|---|---|
workbookId | Specific workbook | { workbookId: 'us_wb_456' } | Workbook, sheet, record, some job events |
sheetId | Specific sheet ID | { sheetId: 'us_sh_123' } | Sheet, record, program events |
sheet | Sheet slug | { sheet: 'contacts' } | Sheet, record, program events |
jobId | Specific job ID | { jobId: 'us_jb_123' } | Job events only |
fileId | File identifier | { fileId: 'us_fl_123' } | File events only |
Property | Description | Example |
---|---|---|
job | Job type identifier | { job: 'workbook:submit' } |
payload.status | Job status | { 'payload.status': 'failed' } |
payload.domain | Event domain | { 'payload.domain': 'space' } |
payload.operation | Operation name | { 'payload.operation': 'configure' } |
Property | Description | Example |
---|---|---|
payload.recordIds | Array of affected record IDs | { 'payload.recordIds': ['rec_123'] } |
payload.recordCount | Number of records affected | { 'payload.recordCount': 5 } |
payload.sheetId | Sheet containing the records | { 'payload.sheetId': 'us_sh_123' } |
Property | Description | Example |
---|---|---|
payload.status | File processing status | { 'payload.status': 'completed' } |
payload.workbookId | Associated workbook | { 'payload.workbookId': 'us_wb_123' } |
*
.