Automatically apply schema changes to existing, live workbooks when a new version of a Flatfile Agent is deployed
agent:created
or agent:updated
events), this plugin identifies relevant workbooks and initiates an update process.
Its primary use case is to ensure that all workbooks associated with a particular configuration stay up-to-date with the latest schema definitions without manual intervention. It works by creating a job to apply the new schema via a user-defined updater
function. After the schema is updated, it cleverly re-triggers all data hooks on all records in the updated sheets, ensuring data validity and transformations are re-evaluated against the new schema.
This plugin should be deployed in a server-side listener.
namespace
(required)string
workbook:your-namespace
.dev
(required)boolean
true
, the plugin will also trigger an update check when the agent starts up in a local development environment (i.e., not running on AWS Lambda). This is useful for testing changes locally without needing to deploy a new agent version.false
- updates in local development are suppressed unless this is explicitly set to true
.updater
(required)(space: Flatfile.Space, workbooks: Flatfile.Workbook[]) => Promise<undefined | Flatfile.Workbook[]>
space
being processed and a list of its workbooks
. You are responsible for using the Flatfile API within this function to apply your new schema to the workbooks. The function should return an array of the workbooks that were successfully updated.rollout(config)
updater
function to apply the specific schema changes.
Parameters:
config
(object): Configuration object with the following properties:
namespace
(string, required): The namespace to filter spaces for updatesdev
(boolean, required): Set to true
to enable updates on local agent reloadsupdater
(function, required): Async function that performs the schema update.root
property (also a listener callback). The main callback handles the space:auto-update
job, while the .root
callback handles agent:created
and agent:updated
events.
agent:created
or agent:updated
events are firing upon deploymentFF_AUTO_UPDATE
or FF_AUTO_UPDATE_DEV
) is set to 'true'
dev: true
in the plugin configurationupdater
function is returning an array containing the workbooks that you successfully updatedundefined
value is returned, the hook re-triggering step will be skippedFF_AUTO_UPDATE
with a value of 'true'
. If the dev: true
option is used, it will trigger updates for development spaces that have a secret named FF_AUTO_UPDATE_DEV
with a value of 'true'
. This secret-based mechanism acts as an explicit opt-in for each space, preventing accidental updates.
.root
property. You MUST register both. The main function handles the job execution and should be on a namespaced listener. The .root
function handles the global events that trigger the job and must be on the root listener.FF_AUTO_UPDATE
must exist with the value 'true'
. For local development (with dev: true
), the secret must be FF_AUTO_UPDATE_DEV
with the value 'true'
._autoUpdateKey
with a random UUID. This modification forces Flatfile to re-evaluate each record.space:read
(for spaces.list
, spaces.get
)secret:read
(for secrets.list
)workbook:read
(for workbooks.list
)job:write
(for jobs.create
)updater
function will likely require additional permissions, such as sheet:write
to update sheet configurations.