Skip to main content
Version: latest

Process data with Data Hooks®

Data Hooks®, are short functions to re-format, correct, validate, and enrich data automatically during a data import. They can run on specific fields and records (rows), or they can run across an entire batch of records.

Highlights:

Field Hooks

Field Hooks are functions that help to clean up or validate the input data of a field

There are three options: validate, compute and cast

  • Validate takes a typed value and returns annotations. Confirms user-inputted data matches what you're expecting. You can display an error, warning, or comments to the cell informing your user about what needs to be fixed.

  • Compute runs simple logic on the user input value and returns a data value of the same type.

  • Cast takes a string or undefined field and return either the primitive type specified by the field, null, or will throw an error. When the default cast function cannot parse an incoming value, it will throw an error in the UI and retain the original value so users can edit that value. Each of our field types have a default casting, except for the OptionField.

Record Hooks

Two types of Record Hooks: recordCompute and batchRecordsCompute.

These are optionally defined on a Sheet in your Workbook.

// src/index.ts

// ...
// Define Sheets with fields
const Employees = new Sheet(
"Employees",
{
// Define Fields
},
{
// Sheet options with example Data Hooks
recordCompute: (record) => {
const fullName = `{record.get('firstName')} {record.get('lastName')}`;
record.set("fullName", fullName);
return record;
},
batchRecordsCompute: async (payload: FlatfileRecords<any>) => {
const response = await fetch("https://api.us.flatfile.io/health", {
method: "GET",
headers: {
Accept: "application/json",
},
});
const result = await response.json();
payload.records.map(async (record: FlatfileRecord) => {
record.set("fromHttp", result.info.postgres.status);
});
},
},
);
// ...

recordCompute

recordCompute runs across all fields in a single record.

Useful when you want to update values based on multiple fields in the record like this example:

recordCompute: (record) => {
const fullName = `{record.get('firstName')} {record.get('lastName')}`;
record.set("fullName", fullName);
return record;
};

This should be used for simple row work that doesn't make HTTP calls.

batchRecordCompute

batchRecordCompute runs after all recordCompute calls have finished and receives the full list of processed rows.

This is how you can perform bulk operations across all data. In most cases, this should only be used for http calls.

In this example, we pass the input rows into a single API request that returns a list of updated records.

batchRecordsCompute: async (payload: FlatfileRecords<any>) => {
const response = await fetch("https://api.us.flatfile.io/health", {
method: "GET",
headers: {
Accept: "application/json",
},
});
const result = await response.json();
payload.records.map(async (record: FlatfileRecord) => {
record.set("fromHttp", result.info.postgres.status);
});
};