Fuse-importer NPM

Installation
Introduction
Registration
Create Your First Importer
Getting started
More Examples
Usage
- FuseImporter Hooks

Installation

You can use Yarn, NPM, or a CDN to install the importer.

Install with npm:

npm install fuse-importer --save

Install with yarn:

yarn add fuse-importer

Install with CDN:

<script
  type="text/javascript"
  src="https://unpkg.com/fuse-importer@latest.js"
></script>

Introduction

Flatirons Fuse is our solution to the inevitable difficulties of getting customer data into your solution. We provide a white-labeled, customizable CSV and Spreadsheet import experience that is above all effective and flexible. Not only do we save you the time and effort of developing your own import solution, but we also ensure that setup and integration with your systems are a breeze.

To get started with our solution, you're going to need a free account and to create a template on our platform: Flatirons Fuse

To use the importer you will need two keys:

Your Organization's API key: You can find this at the top of the Templates page.
Your Importer's ID: You can find this in the table on the Templates page.

For more information see our full documentation.

Check it out in action:

Registration

If you don't have an account yet, you can go over the Registration.

Create Your First Importer

If you don’t have an Importer yet, you can go over Create Your First Importer. Importer represents the fields and validations that your own system accepts, also known as your data schema.

Getting started

<!DOCTYPE html>
<html>
  <head>
    <script
      type="text/javascript"
      src="https://unpkg.com/fuse-importer@latest"
    ></script>
    <script type="text/javascript">
      const organizationApiKey = "YOUR ORGANIZATIONS API KEY";
      const importerId = "YOUR IMPORTER ID";
      const importer = new FuseImporter(organizationApiKey, importerId);

      importer.onValidateRecord = async (record) => {
        // return no frontend validation errors or warnings
        return { errors: {}, warnings: {} };
      };

      importer.onSubmit = async (records) => {
        // an empty hash will tell us the import was successful!
        return {
          message: "Your data was imported successfully",
          errors: {},
        };
      };

      window.showFuseImporter = () => {
        if (
          organizationApiKey.indexOf("YOUR") !== -1 ||
          importerId.indexOf("YOUR") !== -1
        ) {
          window.confirm(
            "You need to configure your organization api key and Importer id."
          );
          return;
        }
        importer.show();
      };
    </script>
  </head>

  <body>
    <button onclick="javascript:showFuseImporter()">Show Importer</button>
  </body>
</html>

More Examples

Usage

import FuseImporter from "fuse-importer";

const organizationApiKey = "YOUR ORGANIZATIONS API KEY";
const importerId = "YOUR IMPORTER ID";
const importer = new FuseImporter(organizationApiKey, importerId);

FuseImporter Hooks

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();

`close`

The close function allows you to remove the importer from the view.

importer.close();

`onClose`

The onClose function allows you to be notified when the importer is removed from the view.

importer.onClose = () => {
  console.log("The importer was closed!");
};

`onValidateRecord`

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 be 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`

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 = async (record) => {
  const newRecord = { ...record };

  // capitalize 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`

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.",
      },
    },
  };
};

@infinitebrahmanuniverse/nolb-fus @everything-registry/sub-chunk-1712

9 days ago

18 days ago

18 days ago

18 days ago

18 days ago