Product Features & Updates

Step Hooks Help Flatfile Users Customize the Data Import Process

Brent Kulwicki

Posted 6/22/2021

With Flatfile’s Data Hooks® feature, you can run custom functions on both Fields (columns) and Records (rows) within files that are imported. They are useful for defining complex validation, transformation, and lookup logic like:

  • "If the country is United States, the postal code must be 5 digits"
  • "Does this email exist in my database?"
  • “Remove all special characters”

Our next iteration of Data Hooks® now includes Step Hooks, which let you customize the import process itself. With Step Hooks you can pause the import flow at various steps, allowing your customer to review or augment the data being shared. A Step Hook, for example, allows you to perform validation based on matched headers ahead of the review step. You can also automatically append fields that might not have been included in the original data set. 

Here's some example data for the code below. If you want to follow along, check out the playground with this setup.

First Name Last Name
Marshall Erickson
Winston Schmidt 
Jim Brockmire
Stanley Hudson

For this example, we will assume that the schema is expecting a first_name and a last_name key. When we use step hooks, we get to see what the matching status is for the user after upload , before matching and/or before the review step. We also can get a hook that runs when a user matches or de-selects a match during the matching step using match_field .

Let's take a look at how to use it and what the expected output might look like for the review step. This hook runs during the import when we click the "review" button pictured here. Whatever code you write into the below hook will run in the time between when the button is clicked and the review state loads - with the data inside of the review table.

undefined

importer.registerStepHook("review", (status) => 
{
console.log(status) })
// output structure when first_name and last_name are
// mapped properly by the user
{
batchId: "batch-ID-of-the-import",
fileName: "file_name.csv",
fileSize: 105,
count_column: 2, // number of columns in the file
count_rows: 4, // number of records in the file
fileType: "text/csv",
headers_matched: [
{
index: 0,
letter: "A", // column index order
matched_key: "first_name"
},
{
index: 1,
letter: "B",
matched_key: "last_name"
}
],
headers_raw: [
{
index: 0,
value: "First Name",
letter: "A"
},
{
index: 1,
value: "Last Name",
letter: "B"
}
],
sample: [
[
["First Name", "Last Name"], 0
]
[
["Marshall", "Erickson"], 1
],
[
["Winston", "Schmidt"], 2
],
[
["Jim", "Brockmire"], 3
],
[
["Stanley", "Hudson"], 4
]
]
}

So in this example, we see what the state of the matching is compared to what the original/raw headers were, a sample set of data, and also some metadata about the file.

Here are a few examples of how Flatfile users can take advantage of Step Hooks:

  • Compare the data in the upload to your system to make sure the exact same file hasn't already been uploaded.
  • Confirm the number of rows in the file before receiving the results.
  • Determine if you need to create an additional field during this process. For example, maybe you want to accept first_name and last_name but your desired state is full_name . You could create the full_name field inside of one of these step hooks using the addVirtualField method. If that final scenario interests you, we've created a guide for creating virtual fields dynamically here.

With step hooks, you can follow along the import as the user is going through the process and can use that information to influence different pieces of the import with Flatfile Portal.

Step Hooks are currently in Beta. If you would like access to this, please reach out to us at support@flatfile.io.

Want to learn more about our products?
Request a demo