Data Hooks® best practices

Before you begin:

Check out how to use Data Hooks® in the latest version of Flatfile.

Data Hooks® Best Practices

Working with multiple fields in record hooks

When working with record hooks, it is useful to be able to validate information using multiple fields. For example, say you require an email or user Id. You can use record hooks to compare the two fields, and if both are blank, you can mark the data with an error message on one or both fields to indicate to the user that one field or the other is required. In working with these two fields, you can reference record.email and record.userId and return an error when neither have a value.

Here's an example of the above usage:

import FlatfileImporter from "@flatfile/adapter";
import $ from "jquery";

const importer = new FlatfileImporter("4171f0b4-5f5c-4b32-a008-356ebb813e4e", {
  fields: [
    {
      label: "User ID",
      key: "userId",
    },
    {
      label: "Email Address",
      key: "email",
    },
  ],
  type: "Contact",
});

importer.registerRecordHook(async (record, index) => {
  let out = {};
  if (!record.email && !record.userId) {
    out.email = {
      info: [
        {
          message: "Must have a User ID or Email",
          level: "error",
        },
      ],
    };
    out.userId = {
      info: [
        {
          message: "Must have a User ID or Email",
          level: "error",
        },
      ],
    };
  }
  return out;
});

importer.setCustomer({
  userId: "19234",
  name: "Jon",
});

$("#launch").click(function () {
  importer
    .requestDataFromUser()
    .then(function (results) {
      console.log(results);
      importer.displaySuccess("Thanks for your data.");
    })
    .catch(function (error) {
      console.info(error || "window close");
    });
});

Splitting record hooks by init or change

It's key to note that while record hooks run both on init and on change, you have access to differentiate between the two mode types with a third, optional mode parameter in the registerRecordHooks method. This will identify each call to the record hook as either init or change. This split can be used to perform different tasks depending on what mode is being executed. There are many reasons why you might want to use these different states in the validation process, but one of the most common is for working with external data (which we discuss in our guide for working with external data).

For the example here, we will add a different message onto the same field, one on init and the other will update the message and error level on change of the record.

import FlatfileImporter from "@flatfile/adapter";
import $ from "jquery";

const importer = new FlatfileImporter("4171f0b4-5f5c-4b32-a008-356ebb813e4e", {
  fields: [
    {
      label: "Name",
      key: "name",
    },
    {
      label: "User ID",
      key: "userId",
    },
    {
      label: "Email Address",
      key: "email",
    },
  ],
  type: "Contact",
});

importer.registerRecordHook((record, index, mode) => {
  let out = {};
  if (record.email && mode === "init") {
    out.email = {
      info: [
        {
          message: "On Init: Email in error state to show init",
          level: "error",
        },
      ],
    };
  }
  if (record.email && mode === "change") {
    out.email = {
      info: [
        {
          message: "On Change: Email in warning state to show changed record",
          level: "warning",
        },
      ],
    };
  }
  return out;
});

importer.setCustomer({
  userId: "19234",
  name: "Jon",
});

$("#launch").click(function () {
  importer
    .requestDataFromUser()
    .then(function (results) {
      console.log(results);
      importer.displaySuccess("Thanks for your data.");
    })
    .catch(function (error) {
      console.info(error || "window close");
    });
});

In the above example, when the file is dropped and the review stage begins, any record with an email would have red highlighting and display the message "On Init: Email in error state to show init" when the cell is hovered over. When any record on the field is updated, the email field for that record will then change to yellow highlighting and display the message "On Change: Email in warning state to show changed record" when hovered over.

Validating with external data

In our guide for working with external data, we have an example and more details about this, but we think it is fair to also point out here the common uses and mistakes for using Data Hooks® with external data.

In the above section, you can see how to split the record hooks based on init or change. The key for validating with external data is to not use the record hooks on init, but only on change when making API calls inside hook. If you need to make them on init, you should use a field hook to grab all the values of the field in bulk and then perform the necessary actions on all of the items in the field before returning the data. You may then perform the same or similar call on each field as they are changed using the change event on record hooks.

Data Hooks®: run order and flow

When considering Data Hooks® best practices, it is important to re-iterate the order of which these hooks will process. In any import, field hooks will be run in the order that they are presented in the code (and will only run once), then record hooks on init would be run. After these have finished running, the Review stage of the import begins. As each record is updated, the change record hooks will run on the record that has been updated.