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:

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 and .json files.)
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.
Header Selection: The user must select the header row containing the column names for each imported sheet.
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.
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.
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:

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.
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.
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.
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.
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
Angular
Vue.js
JavaScript

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";

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:

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 {}

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

<nuvo-importer></nuvo-importer>

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>

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

CDN
NPM/Yarn

Add the following script tag into your app:

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

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.

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 as an array of JSON objects with the result parameter and access to the identifier. 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 iterates through each entry and runs when an entry/row is changed.
onEntryInit - Allows you to insert a callback function that iterates through each entry and runs after the user confirms the "Match Columns"-Step, so that the "Review Entries"-Step is initialised.
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, so that the "Review Entries"-Step is initialised.
renderUploadButton - Allows you to insert your buttons/components instead of the default nuvo element.
text (only for Angular & Vue.js) - Allows you to define the text of the upload button.
setText (only for vanilla JavaScript) - 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

React
Angular
Vue.js
JavaScript

<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, identifier, complete) => {
    console.log("Result:", result);
    console.log("Identifier:", identifier);
    complete();
  }}
  onCancel={() => {
    console.log("onCancel");
  }}
  onEntryChange={(row, rowIndex) => {
    return { product_id: { value: row.product_id + " on change" } };
  }}
  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]);
    },
  }}
/>

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)"
>
</nuvo-importer>

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, identifier, complete) => {
  console.log("Result:", result)
  console.log("Identifier:", identifier)
  complete()
}
onCancel=() => {
  console.log("onCancel");
}
onEntryChange=(row, rowIndex) => {
  return { product_id: { value: row.product_id + " on change" } };
}
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]);
  }
}

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>

info

The setup of Vue.js 2 and Vue.js 3 is slightly different. Please check the corresponding tab.

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

Vue.js 2
Vue.js 3

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, identifier, complete) => {
      console.log("Result:", result);
      console.log("Identifier:", identifier);
      complete();
    },
    onCancel: () => {
      console.log("onCancel");
    },
    onEntryChange: (row, rowIndex) => {
      return { product_id: { value: row.product_id + " on change" } };
    },
    onEntryInit: (row, rowIndex) => {
      return { product_id: { value: row.product_id + " on init" } };
    },
  },
};

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

<!DOCTYPE html>
<html>
  <body>
    <script src="https://unpkg.com/[email protected]"></script>
    <script type="text/javascript">
      const settings = {
        developerMode: true,
        identifier: "product_data",
        columns: [
          {
            label: "Product ID",
            key: "product_id",
          },
          {
            label: "Article Name",
            key: "article_name",
          },
        ],
      };

      const nuvoImporter = new window.nuvo.NuvoImporter("Your License Key", settings);

      nuvoImporter.onResults((values, identifier, complete) => {
        console.log("Result:", values);
        console.log("Identifier:", identifier);
        complete();
      });

      nuvoImporter.onCancel(() => {
        console.log("onCancel");
      });

      nuvoImporter.registerEntryInit((row) => {
        return { product_id: { value: row.product_id + " on init" } };
      });

      nuvoImporter.registerEntryChange((row, rowIndex) => {
        return { product_id: { value: row.product_id + " on change" } };
      });

      nuvoImporter.registerColumnHooks("article_name", (hookedRecordValues) => {
        return new Promise((resolve) => {
          setTimeout(() => {
            resolve(
              hookedRecordValues.map(([row, rowIndex]) => {
                return [
                  {
                    value: "#NU" + row,
                    info: [
                      {
                        level: "warning",
                        message: "This is a warning",
                      },
                    ],
                  },
                  rowIndex,
                ];
              })
            );
          }, 0);
        });
      });

      nuvoImporter.launch();
    </script>
  </body>
</html>

First steps for using the nuvo importer

Importer workflow​

How to start?​

Technical implementation​

Install & import the NuvoImporter​

Set up settings​

Importer workflow

How to start?

Technical implementation

Install & import the NuvoImporter

Set up settings