Legacy Documentation: This content is maintained for backward compatibility and may not reflect the latest features or best practices. For current documentation, please refer to our updated guides.
The DevXP engineering team hosts office hours every Thursday at 11 a.m. Pacific Time where we answer your questions live and help you get up and running with Flatfile. Join us!

​
Before you begin

To make working with event data inside a listener easy, Flatfile provides a suite of Plugins.
Plugins extend the functionality of a listener. They are registered with the listener.use() function and fire when the listener receives a corresponding event.
The Record Hook Plugin fires whenever a row of data (a Record) is added or modified, allowing us to take action and perform a custom transformation.

​
Import the recordHook plugin

import { recordHook } from "@flatfile/plugin-record-hook";

​
Add your first transformation

Here’s an example that modifies the first name value of a Record, converting it to lowercase: 
red.use(
  recordHook("contacts", (record) => {
    const value = record.get("firstName");

    if (typeof value === "string") {
      record.set("firstName", value.toLowerCase());
    }

    return record;
  }),
);
As you can see, the recordHook has been configured to run on any Sheet matching the slug “contacts”. The second parameter to the recordHook is a callback function where a Record, complete with it’s own get and set methods, is the incoming value.
Note: Unmodified rows do not trigger a Record Hook.

​
Watch your data transform

Is your listener still running? If not, run npx flatfile@latest develop again. Now, in your Workbook, add a new Record. Enter a capitalized value in the First Name field, then click away so Flatfile knows you’ve finished your current edit. Once your focus leaves the First Name field, an Event will trigger and the recordHook will run the lowercase transformation you just configured.

​
Add your first validation

You can also use a recordHook to help validate data. For example, what if the first name in a Record is not a string? The current code would not transform it, so let’s add an error message to flag the Record. 
red.use(
  recordHook("contacts", (record) => {
    const value = record.get("firstName");
    if (typeof value === "string") {
      record.set("firstName", value.toLowerCase());
    } else {
      record.addError("firstName", "Invalid first name");
    }
    return record;
  }),
);

​
Addl examples

You can use any npm package in a plugin.
The possible customizations are endless. Flatfile has a constantly expanding library of transformation and validation plugins that help you reshape data. You can add as many as you need to ensure your data is clean and ready to be used. For example, you could add code to validate a Record’s email field: 
red.use(
  recordHook("contacts", (record) => {
    // FirstName field transformation and validation
    const value = record.get("firstName");
    if (typeof value === "string") {
      record.set("firstName", value.toLowerCase());
    } else {
      record.addError("firstName", "Invalid first name");
    }

    // Email field validation
    const email = record.get("email");
    const validEmailAddress = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    if (email !== null && !validEmailAddress.test(email)) {
      console.log("Invalid email address");
      record.addError("email", "Invalid email address");
    }
    return record;
  }),
);
Remember that the recordHook plugin fires once per modified record, so you should include the code for all transformations and validations you want on that Record in the same recordHook.

​
Watch your data validate

Check your listener is still running. If not, run npx flatfile@latest develop again. Now, in your Workbook, add or update a Record. Enter a number inside the firstName field, or an invalid email address in the email field, then click away so Flatfile knows you’ve finished your current edit. See that error message? That’s the result of your validation.

​
Next steps

Now that you’ve added some transformations and validations, let’s egress the cleaned data: Configure a submit Action.