First steps for using the nuvo importer

Importer workflow

Our NuvoImporter is a component that you can easily embed into your application's frontend. This component enables you to guide your users through our data onboarding workflow, which contains the following steps:

1. Upload: The user can upload one or multiple files by either dragging the spreadsheet(s) within the dropzone or pressing the "Select file" button. (We currently support .xls, .xslx, .csv, .tsv, .xml, .json and .pdf files.)
2. Sheet Selection: If the uploaded file contains more than one sheet or if more than one file is uploaded, the user has to select the sheet(s) with the data that matter for the import.
3. Header Selection: The user must select the header row containing the column names for each imported sheet.
4. Join Sheets (optional): This step is only displayed if the multipleFileUpload is set to true and the user has uploaded and selected more than one sheet. Here the user specifies for each sheet the column whose values are used as keys for the join.
5. Match Columns: The imported columns are matched to the columns of the target data model by our smart ML-supported algorithm. The user can here resolve recommended matches and also create new mappings.
6. Review Entries: In this step, the user reviews the restructured data, cleans errors and finishes the data import.

How to start?

If you want to implement our nuvo importer fastly, we recommend you to follow the next steps:

1. Technical implementation: Choose your preferred JavaScript framework and follow the instructions of the "Technical implementation" section below for getting our component up and running within your application.
2. Target model & settings configuration: The most essential element of our importer is the target data model, which contains all columns of your preferred output structure. The columns array, which includes all requested columns, is defined within the settings property, with which you can adjust the import workflow and disable certain features.
3. Set up validation rules & cleaning functions: After the first two steps, you can already use the importer within a production environment. But to use the full potential of the nuvo importer and also to serve more complex use cases, you can add additional validation rules to each column by defining them within the validations property or by using our cleaning functions. For each column, you can add regular expressions, column-cross dependencies, column types (very similar to data types) and/or add a required- as well as an unique-rule. With our cleaning functions, you can transform data automatically and display feedback to the user.
4. Dealing with the result: With the onResults callback function, you can define what is supposed to happen with user-submitted data. You have many possibilities at your disposal. For instance, you can send the data to your preferred API endpoint, define variables within the frontend, modify the structure and the values of the result array object, or call a function that leads to an XLSX- or CSV-Download. Moreover, you can define when an import process was successful or when an import has failed. In the last case, you can customize the displayed error modal and decide if the import process is cancelled or if the user remains inside the last step.
5. Styling & multi-language support (optional): The nuvo importer is a fully customizable component that can be adjusted in many ways to fit your importing process. As mentioned above, you can disable certain features or make adjustments to the workflow with the settings property. Moreover, you can fully customize the nuvo importer's design and change all interface texts with our i18nOverrides option. The last can be used for providing multi-language support.

If you would like to see a full example of how to implement the nuvo importer, you can take a look at our CRM data importer example.

Technical implementation

It's relatively easy to get started with the nuvo importer. Usually, it only takes a couple of minutes to get the nuvo importer up and running. In this section, you'll learn how to start using the nuvo importer within your application.

info

To implement the nuvo importer correctly, you will need a license key. Please use the dev key for testing and the live key for production activities. After logging into your account inside the nuvo user platform, you can find both by going to the setup page or the dashboard page.

info

No account yet? You can use our GitHub login to receive access to our importer immediately, or you can book a demo to talk to a nuvo sales manager upfront.

Install & import the NuvoImporter

We provide our nuvo importer for React, Angular, Vue.js and plain JavaScript. Our software library can be installed with NPM or Yarn, and we offer the option to directly source it from our CDN. You can find a list of all supported versions here.

React

Install the React package with NPM:

npm install nuvo-react

or install it with Yarn:

yarn add nuvo-react

This allows you to use the <NuvoImporter> component inside your application:

import { NuvoImporter } from "nuvo-react";

Angular

Install the Angular package with NPM:

npm install nuvo-angular

or install it with Yarn:

yarn add nuvo-angular

Execute the following steps to import the <NuvoImporter> inside your application:

1. Add the NuvoImporter module to the file app.module.ts.

import { NuvoImporterModule } from "nuvo-angular";

@NgModule({
  declarations: [AppComponent],
  imports: [NuvoImporterModule, BrowserModule, AppRoutingModule],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

2. Add the NuvoImporter component to the file app.component.html.

<nuvo-importer />

Vue

Install the Vue.js package with NPM:

npm install nuvo-vuejs

or install it with Yarn:

yarn add nuvo-vuejs

Add the NuvoImporter component inside of the <script> tag of the file App.vue

<script>
  import { NuvoImporter } from "nuvo-vuejs";
</script>

JavaScript

Use our vanilla JavaScript version with either NPM or Yarn, or by directly sourcing it from our CDN:

CDN

Add the following script tag into your app:

<script src="https://unpkg.com/nuvo-vanilla-js"></script>

NPM/Yarn

Install the vanilla JS package with NPM:

npm install nuvo-vanilla-js

or install it with Yarn:

yarn add nuvo-vanilla-js

info

For more information, check out the guide about installing a vanilla JavaScript library with NPM or yarn.

Next.js

Install the React package with NPM:

npm install nuvo-react

or install it with Yarn:

yarn add nuvo-react

Configure the nuvo importer for client-side rendering:

v12 or lower

import { ConfigureAPI } from "nuvo-react";

const NuvoImporter =
  dynamic <
  ConfigureAPI >
  (import("nuvo-react").then((item) => item.NuvoImporter),
  {
    ssr: false,
  });

v13 or higher

import { ConfigureAPI } from "nuvo-react";

const NuvoImporter =
  dynamic <
  ConfigureAPI >
  (() => import("nuvo-react").then((item) => item.NuvoImporter),
  {
    ssr: false,
  });

info

If you run into an "Global CSS cannot be imported from within node_modules." error, we recommend you to install the following package: https://www.npmjs.com/package/next-transpile-modules

After that go to the "next.config.js" file to adjust the configuration like the following:

const withTM = require("next-transpile-modules")(["nuvo-react"]);

/** @type {import('next').NextConfig} */
const nextConfig = {
  reactStrictMode: true,
};

module.exports = withTM(nextConfig);

Set up settings

The <NuvoImporter> instance must have settings & licenseKey as properties to launch. The following list contains all properties of the <NuvoImporter> that are adjustable. For more details, visit our settings page.

• licenseKey (required) - A valid license key is required to be allowed to use the nuvo importer. You can find both license keys (dev/live) within the nuvo user platform after you have logged in.
• settings (required) - Requires an object that contains the identifier and the columns of the target data model. For more details, visit our settings page.
• onResults - Allows you access to the user-submitted data and the data that contained errors, both in the form of JSON arrays. For more information, visit our results page.
• onCancel - Allows you to insert a callback function that runs if the user cancels the import process.
• onEntryChange - Allows you to insert a callback function that runs on each action involving changes, creations, or deletions of at least one row.
• onEntryInit - Allows you to insert a callback function that iterates through each entry and runs after the user confirms the "Match Columns" step.
• columnHooks - Allows you to insert a single or multiple callback functions that each have access to only one column and run after the user confirms the "Match Columns" step.
• renderUploadButton (deprecated) - Allows you to render your own button or component instead of the default nuvo element. For more details, visit our styling page.
• text (deprecated) - Allows you to define the text of the upload button.

You can copy the following code snippet to set up the nuvo importer quickly:

info

Please note the minimum screen width for the nuvo importer to work is 901px

info

Outside of your testing phase, onResults only returns the first 100 rows when using the dev license key. Please reach out to [email protected] for more information.

React/Next.js

<NuvoImporter
  licenseKey="Your License Key"
  settings={{
    developerMode: true,
    identifier: "product_data",
    columns: [
      {
        label: "Product ID",
        key: "product_id",
      },
      {
        label: "Article Name",
        key: "article_name",
      },
    ],
  }}
  onResults={(result, errors, complete, logs) => {
    console.log("Result:", result);
    console.log("Error rows:", errors);
    console.log("Logs:", logs);
    complete();
  }}
  onCancel={() => {
    console.log("onCancel");
  }}
  onEntryChange={(rows, logs) => {
    return rows.map((row) => {
      return {
        data: {
          product_id: { value: row.data.product_id + " on change" },
        },
        rowIndex: row.rowIndex,
      };
    });
  }}
  onEntryInit={(row, rowIndex) => {
    return { product_id: { value: row.product_id + " on init" } };
  }}
  columnHooks={{
    article_name: (values) => {
      return values.map(([item, index]) => [{ value: "#NU" + item }, index]);
    },
  }}
/>

Angular

1. Add the nuvo component in the HTML file.

<nuvo-importer
  [licenseKey]="licenseKey"
  [settings]="settings"
  [onResults]="onResults.bind(this)"
  [onEntryChange]="onEntryChange.bind(this)"
  [onEntryInit]="onEntryInit.bind(this)"
  [columnHooks]="columnHooks"
  [onCancel]="onCancel.bind(this)"
/>

2. Define the property in the component file.

licenseKey!: string
settings!: SettingsAPI;

ngOnInit(): void {
  this.licenseKey = "Your License Key"
  this.settings = {
    developerMode: true,
    identifier: "product_data",
    columns: [
      {
        label: "Product ID",
        key: "product_id",
      },
      {
        label: "Article Name",
        key: "article_name",
      },
    ]
  };
}
onResults=(result, errors, complete, logs) => {
  console.log("Result:", result)
  console.log("Error rows:", errors)
  console.log("Logs:", logs)
  complete()
}
onCancel=() => {
  console.log("onCancel");
}
onEntryChange=(rows, logs) => {
  return rows.map((row) => {
    return {
      data: {
        product_id: { value: row.data.product_id + ' on change' },
      },
      rowIndex: row.rowIndex,
    };
  });
}
onEntryInit=(row, rowIndex) => {
  return { product_id: { value: row.product_id + " on init" } };
}
columnHooks={
  article_name: (values) => {
    return values.map(([item, index]) => [{ value: "#NU" + item }, index]);
  }
}

Vue

info

We're phasing out support for Vue 2. If you're still using Vue 2, you can use "nuvo-vuejs" v2.9 or lower.

1. Add the nuvo component inside the <template> tag in the file App.vue.

<template>
  <div id="app">
    <NuvoImporter
      :licenseKey="licenseKey"
      :settings="settings"
      :onResults="onResults"
      :onEntryChange="onEntryChange"
      :onEntryInit="onEntryInit"
      :columnHooks="columnHooks"
    />
  </div>
</template>

2. Define the property inside the <script> tag in the component file.

export default {
  name: "App",
  components: {
    NuvoImporter,
  },
  data: () => {
    return {
      licenseKey: "Your License Key",
      settings: {
        developerMode: true,
        identifier: "product_data",
        columns: [
          {
            label: "Product ID",
            key: "product_id",
          },
          {
            label: "Article Name",
            key: "article_name",
          },
        ],
      },
      columnHooks: {
        article_name: (values) => {
          return values.map(([item, index]) => [{ value: "#NU" + item }, index]);
        },
      },
    };
  },
  methods: {
    onResults: (result, errors, complete, logs) => {
      console.log("Result:", result);
      console.log("Error rows:", errors);
      console.log("Logs:", logs);
      complete();
    },
    onCancel: () => {
      console.log("onCancel");
    },
    onEntryChange: (rows, logs) => {
      return rows.map((row) => {
        return {
          data: {
            product_id: { value: row.data.product_id + " on change" },
          },
          rowIndex: row.rowIndex,
        };
      });
    },
    onEntryInit: (row, rowIndex) => {
      return { product_id: { value: row.product_id + " on init" } };
    },
  },
};

JavaScript

info

Our vanilla JS syntax has changed since v2.9. If you use v2.8 or lower, please migrate to the latest version by following our migration guide.

<div class="nuvo-container" />
<script type="module">
  import { launchNuvoImporter } from "nuvo-vanilla-js";

  launchNuvoImporter(".nuvo-container", {
    licenseKey: "Your License Key",
    settings: {
      developerMode: true,
      identifier: "product_data",
      columns: [
        {
          label: "Product ID",
          key: "product_id",
        },
        {
          label: "Article Name",
          key: "article_name",
        },
      ],
    },
    columnHooks: {
      article_name: (values) => {
        return values.map(([item, index]) => [{ value: "#NU" + item }, index]);
      },
    },
    onCancel: () => {
      console.log("onCancel");
    },
    onEntryChange: (rows, logs) => {
      return rows.map((row) => {
        return {
          data: {
            product_id: { value: row.data.product_id + " on change" },
          },
          rowIndex: row.rowIndex,
        };
      });
    },
    onEntryInit: (row, rowIndex) => {
      return { product_id: { value: row.product_id + " on init" } };
    },
    onResults: (result, errors, complete, logs) => {
      console.log("Result:", result);
      console.log("Error rows:", errors);
      console.log("Logs:", logs);
      complete();
    },
  });
</script>