Flatfile's Data Hooks are a useful data healing element to re-format, validate and/or correct data automatically during the import without the user having to correct manually. When used properly, they can be used for things like automatically reformatting area codes or country codes, removing special characters, validating emails against external data, and really anything else you can code up. Data Hooks are the most powerful data healing element to date within Flatfile. There are two hooks that are available, field hooks (AKA column hooks) and record hooks (AKA row hooks).
Before beginning, there are a couple considerations to be made when choosing which type of hook to use and how to use it, and those revolve around the order and event flow of the hooks. Below is a helpful diagram that shows the general flow for Flatfile, but it should be noted that
fieldHooks
onRecordInit
onRecordChange
fieldHooks={fieldName: (values) => { return // [record, index][]}
Field hooks run validation on a particular field (column) of data at the beginning of the matching stage. These hooks are run before record hooks and will only run once during the import process. These are best used to bulk edit a field or use an outside data source for validation. For example, say you want to verify the email addresses in a file are not already in your database, you could grab all the values in the column within a field hook, send them to your server and validate against your server and send back an error message with any that already exist in your system to display for the user.
In reference to FlatfileFileImporter.registerFieldHook()
fieldHooks
Name | |
---|---|
John Doe | john@doe.com |
Jane Doe | jane@doe.com |
Steve Smith | steve@something.com |
Wayne Jones | wayne@something.com |
In the above scenario, let's say we are sending the values to our server and returning an error for any emails that are already in the database. Let's assume that John and Steve's emails are already in the system. When we return our response, we would need to provide any array with each item in the array being an array that has the record and index. Notice in the below example that when being passed back, the record becomes an object that has a
value
info
In the below example, we will put it into action. We will simply take in an email field and add " added from the field hook" so that if you run the code, you can see it work.
With external data example:
First Name | User ID | |
---|---|---|
David | 0001 | david@flatfile.io |
John | 0005 | John@doe.com |
Paula | 0009 | paula@fakeemail.com |
Field Hooks additional notes:
value
info
level
fieldHooks
Record hooks in the React component are split into seperate keys, one being
onRecordInit
onRecordChange
record
index
onRecordInit
onRecordChange
fieldHooks
onRecordChange
Record hooks are processed in batches. This means that if you need to do something sequentially, you should rely on the index as the source of truth for the sequence.