Transform and validate data
Add your first transformation
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.
Here’s an example that modifies the first name value of a Record, converting it to lowercase:
import { recordHook } from "@flatfile/plugin-record-hook";
listener.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.
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.
import { recordHook } from "@flatfile/plugin-record-hook";
listener.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;
})
);
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:
import { recordHook } from "@flatfile/plugin-record-hook";
listener.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.