Initialization and Hooks

There are only a few simple hooks that the embedded data importer requires. We do the rest of the work.

Initializing the Embedded Data Importer

After you have installed the importer by yarn, npm, or CDN, you are ready to initialize it.
To initialize the importer you will need two keys:
  1. 1.
    Your Organization's API key: You can find this at the top of the Importers page.
  2. 2.
    Your Importer's ID: You can find this in the table on the Importers page.
const importer = new FuseImporter(organizationApiKey, importerId);

Hooks & Functions

Hooks allow you to show the importer, run validations and submit records to your backend.
show
The show function does exactly what it sounds like; it launches the importer. Ensure you have initialized the importer properly beforehand. Use this function like so:
importer.show();
onValidateRecord(record)
The onValidationRecord hook is called for each row (record) that a customer uploads. It allows you to specify custom frontend validations and display error messages in the importer for the user to fix. When you create an Importer, each column contains an internal key. These internal keys represent the
Return values:
  • If the record has no errors, we expect you to return an empty object: return { errors: {}, warnings: {} };
  • If the record has validation errors/warnings, you can specify them like below.
importer.onValidateRecord = async (record) => {
const errors = {};
const warnings = {};
// force emails to include gmail
if (!record.email?.includes("gmail")) {
errors['email'] = "Email must from gmail"
}
// email should be from the domain.
if (!record.email?.includes("@example.com")) {
warnings["email"] = "Email is outside the domain";
}
return { errors: errors, warnings: warnings };
};
The differences between errors and warnings are:
  • warnings will still allow you to submit the spreadsheet, unlike errors.
  • errors have a higher priority than warnings, which means if a record has both, you will not be able to see warnings until you fix errors first.
  • Any errors must be fixed before the user submits an importer. The user will not be able to submit without fixing all errors.
formatRecord(record)
The formatRecord hook can be used to format data automatically on behalf of a user. For example, if you have a field called first_name and you know that your system always requires first_name to be capitalized, you can use this callback to uppercase all first_name records like so:
importer.formatRecord = (record) => {
const newRecord = { ...record };
// capitalize the first letter in first_name
if (typeof newRecord.first_name === "string") {
newRecord.first_name = newRecord.first_name.charAt(0).toUpperCase() + newRecord.first_name.slice(1);
}
return newRecord;
};
onSubmit(records)
onSubmit will pass all records to you after the user has made any necessary corrections to frontend validations. This callback expects you to submit the records to your backend in whatever way you typically would, we do not submit the records for you.
This callback also allows you to pass back any backend errors for specific rows. Each record passed to this callback will have a unique identifier under the key record._meta.id. In this case of a backend validation or error occurring, you can tell the importer to show a specific error to the user for a row. Note that after submission, only records with errors will remain visible to the user.
Return values:
  • If there were no backend errors, pass back an empty errors object and a message to show to the user like so:
importer.onSubmit = async (records) => {
// submit to backend here
let message = "Data imported successfully";
return {
message,
errors: {},
};
};
  • If you find an error with a record in your backend, you can tell the importer to show the error to the user like so:
importer.onSubmit = async (records) => {
// submit to your backend here
return {
errors: {
[records[0]._meta.id]: {
"email": "Email is already taken. Emails must be unique.",
"first_name": "First Name must be capitalized."
}
}
};
};