Skip to main content

Options

Required

importerKey: string

Which can be found in the admin panel.

importerKey: "your-importer-key";

Optional

user: json object

Contains details of the user, so that they can be identified when your backend receives a webhook.

user: {
userId: "12345";
}

metadata: json object

If you have additional data which you want to associate with the import but isn't related to the user, you can use the metadata prop. This will also be included in the webhook your backend receives.

metadata: {
anotherId: "123";
}

onData: Function

onData: (data: {
uploadId: number;
fileName: string;
rows: Record<string, string | number | undefiend>[];
user?: {
userId: string;
};
metadata?: Record<string, string | number>;
}) => void | Promise<{ errors?: { row: Record<string, string | number | undefined>; error: string }[] } | void>

If you prefer to handle your data locally (and disable uploading csv data to UseCSV), you can set the onData callback option and the data will not be uploaded to UseCSV and sent to your callback function instead when the user finishes importing the CSV.

// usage example
var importButton = document.getElementById("import-data-button");
importButton.onclick = function () {
useCsvPlugin({
importerKey: "your-importer-key",
user: {
userId: "12345",
},
metadata: {
anotherId: "1",
},
onData: (data) => {
console.log("data:", data);
},
});
};
// console output
data: {
uploadId: 334,
fileName: "data.csv",
user: {
userId: "12345"
},
metadata: {
anotherId: "1"
},
rows: [{
first_name: "Mari",
email: "Mari@gmail.com"
},
{
first_name: "John",
email: "John@gmail.com"
}
]
}

Return errors

  • You can retrun from the onData function an array of rows with errors and the user will be provided with a downloadable .csv file containing the rows and thier error.
// example of onData error handeling
onData: async (data) => {
/*
* do your validation
*/

// if no errors
return;

// if you found rows with errors, save the correct rows, and retrun an array of rows with errors
return Promise.resolve({
errors: [
{
row: {
first_name: "Mari",
email: "Mari@gmail.com",
},
error: "email already exists",
},
],
});
};

onRecordsInitial: Function

onRecordsInitial callback function is triggered after the user uploads a file and once the column matching is completed. Data from the columns with Data Hook enabled will be sent to your frontend, so you can run your own validation and return rows with errors if any and custom error messages to be shown to the user. Data will be sent in batches of 1000 rows.

type onRecordsInitial = ({
uploadId,
fileName,
importerId,
batch,
user,
metadata,
rows,
}: {
uploadId: string;
fileName: string;
importerId: string;
batch: {
index: number;
count: number;
totalRows: number;
};
user?: Record<string, string | number> | null;
metadata?: Record<string, string | number> | null;
rows: Array<{
row: number;
data: {
[columnName: string]: {
value: string | number;
isValid: boolean;
};
};
}>;
}) =>
| Promise<Array<{
row: number;
[columnName: string]: Array<{
message: string;
level: "error";
}>;
}> | void>
| Array<{
row: number;
data: {
[columnName: string]: Array<{
message: string;
level: "error";
}>;
};
}>
| void;

Usage example

Assuming Data Hooks are enabled for email and age columns only, where:

  • email column is configured with validation format of email in admin panel.
  • age column is configured with validation format of number in admin panel
var importButton = document.getElementById("import-data-button");
importButton.onclick = function () {
useCsvPlugin({
importerKey: "your-importer-key",
user: {
userId: "12345",
},
metadata: {
anotherId: "1",
},
onRecordsInitial: ({
uploadId,
fileName,
importerId,
batch,
user,
metadata,
rows,
}) => {
console.log({
uploadId,
fileName,
importerId,
batch,
user,
metadata,
rows,
});
// run custom validation

// if no errors
return;

// or return an array of errors
return Promise.resolve([
{
row: 1,
data: {
email: [
{
message: "Email already exists", // first error message
level: "error",
},
{
message: "Invalid email", // second error message (optional)
level: "error",
},
],
age: [
{
message: "Age must be 18 or above",
level: "error",
},
],
},
},
{
row: 2,
data: {
age: {
message: "Age must be a number",
level: "error",
},
},
},
{
row: 3,
data: {
email: [
{
message: "Invalid email",
level: "error",
},
],
},
},
]);
},
});
};
// console output
{
uploadId: 334,
fileName: "data.csv",
importerId: "123-456-789"
batch: {
index: 1;
count: 1;
totalRows: 3;
},
user: {
userId: "12345",
},
metadata: {
anotherId: "1",
},
rows: [{
row: 1,
data: {
email: {
value: "Mari@gmail.com",
isValid: true
}
age: {
value: 5,
isValid: true
}
}
},
{
row: 2,
data: {
email: {
value: "John@gmail.com",
isValid: true
},
age: {
value: "not a number",
isValid: false
}
}
} {
row: 3,
data: {
email: {
value: "invalid@email@.com",
isValid: false
},
age: {
value: 35,
isValid: true
}
}
}
]
}

onRecordsInitial callback function parameters

type ParamsType = {
uploadId: string;
fileName: string;
importerId: string;
batch: {
index: number;
count: number;
totalRows: number;
};
user?: Record<string, string | number> | null;
metadata?: Record<string, string | number> | null;
rows: Array<{
row: number;
data: {
[columnName: string]: {
value: string | number;
isValid: boolean;
};
};
}>;
};
  • uploadId: upload ID.
  • fileName: uploaded file name.
  • importerId: importer key that can be found in the admin panel.
  • batch: json object of batch details, with keys of:
    • index: number of batch starting from 1.
    • count: number of total batches expected to be received.
    • totalRows: number of total rows per file.
  • user json object of user object if provided.
  • metadatajson object of metadata object if provided.
  • rows: array of json objects of rows, with keys of:
    • row: number of row in the uploaded file starting from 1.
    • data: json object of columns:
      • columnName: array of json objects of the configured columns, with keys of:
        • value: value of cell.
        • isValid: boolean validation result according to the validation format configured for each column in admin panel when the column was created.

Return errors

type ResponseType = Array<{
row: number;
data: {
[columnName: string]: Array<{
message: string;
level: "error";
}>;
};
}>;
  • row: required row number already included in the recieved data.
  • data: json object of columns:
    • columnName: array of json objects with keys of: message and level. At lease one column should be included in the response.
      • message: custom error message shown to user.
      • level: currently the only implemented level is error but more will be added soon.

onRecordEdit: Function

onRecordEdit callback function is triggered after any of the cells is edited in the Match Columns step. The edited row will be sent to your frontend, so you can run your own validation and return errors if any and custom error messages to be shown to the user.

type onRecordEdit = ({
uploadId,
fileName,
importerId,
user,
metadata,
row,
}: {
uploadId: string;
fileName: string;
importerId: string;
user?: Record<string, string | number> | null;
metadata?: Record<string, string | number> | null;
row: {
row: number;
data: {
[columnName: string]: {
value: string | number;
isValid: boolean;
}
}
};
}) =>
| Promise<{
row: number;
data:{
[columnName: string]: Array<{
message: string;
level: "error";
}
};
}> | void>
| {
row: number;
data: {
[columnName: string]: Array<{
message: string;
level: "error";
}>
};
}
| void;

Usage example

Assuming Data Hooks are enabled for email and age columns only, where:

  • email column is configured with validation format of email in admin panel.
  • age column is configured with validation format of number in admin panel
var importButton = document.getElementById("import-data-button");
importButton.onclick = function () {
useCsvPlugin({
importerKey: "your-importer-key",
user: {
userId: "12345",
},
metadata: {
anotherId: "1",
},
onRecordEdit: ({ uploadId, fileName, importerId, user, metadata, row }) => {
console.log({
uploadId,
fileName,
importerId,
user,
metadata,
row,
});
// run custom validation

// if no errors
return;

// or return a json object
return Promise.resolve({
row: 2,
data: {
email: [
{
message: "Invalid email", // first error message
level: "error",
},
{
message: "Email does not exist", // second error message (optional)
level: "error",
},
],
},
});
},
});
};
// console output
{
uploadId: 334,
fileName: "data.csv",
importerId: "123-456-789"
user: {
userId: "12345",
},
metadata: {
anotherId: "1",
},
row: {
row: 2,
data: {
email: {
value: "invalid@email@.com",
isValid: false
},
age: {
value: 35,
isValid: true
}
}
}
}

onRecordEdit callback function parameters

type ParamsType = {
uploadId: string;
fileName: string;
importerId: string;
user?: Record<string, string | number> | null;
metadata?: Record<string, string | number> | null;
row: {
row: number;
data: {
[columnName: string]: {
value: string | number;
isValid: boolean;
};
};
};
};
  • uploadId: upload ID.
  • fileName: uploaded file name.
  • importerId: importer key that can be found in the admin panel.
  • user json object of user object if provided.
  • metadatajson object of metadata object if provided.
  • row: json object of edited row, with keys of:
    • row: number of row in the uploaded file.
    • data: json object of columns:
      • columnName: array of json objects of the configured columns, with keys of:
        • value: value of cell.
        • isValid: boolean validation result according to the validation format configured for each column in admin panel when the column was created.

Return errors

type ResponseType = {
row: number;
data: {
[columnName: string]: Array<{
message: string;
level: "error";
}>;
};
};
  • row: required row number already included in the recieved data.
  • data: json object of columns:
    • columnName: json object with keys of: message and level. At lease one column should be included in the response.
      • message: custom error message shown to user.
      • level: currently the only implemented level is error but more will be added soon.