Migration Guide

ⓘ Reach out to your Flatfile support team to make sure your plan has access to version 2.0.

If you're looking to move to Flatfile Portal version 2.0 from version 1, then this guide will show you the recommended steps to upgrade and the differences in configuration.

Estimated conversion time: 5-30 minutes

If you're on version 1 and using NPM, make sure that you update your NPM package using the following command.

npm update flatfile-csv-importer

After updating, your package.json should reflect version 0.2.6 or higher.

{
"dependencies": {
"flatfile-csv-importer": "^0.2.6"
}
}

If you're loading Flatfile via CDN, you're all ready to go.

Configuration Changes

We've updated how some of the configuration works to consolidate everything into only one way to initialize features. Here are the specifics:

label:

All of configurations within fields must now have a label.

// Before
fields: [
{
key: 'name'
}
]
// After
fields: [
{
label: 'Name',
key: 'name'
}
]

validator:

We've deprecated the single validator configuration, and now all validators will be used in the validators configuration.

// Before
{
label: 'Name',
key: 'name',
validator: {validate: 'required'}
}
// After
{
label: 'Name',
key: 'name',
validators: [
{validate: 'required'}
]
}

isRequired:

The isRequired configuration key has been deprecated, and all validators will need to be put within the validators array.

// Before
{
label: 'Name',
key: 'name',
isRequired: true
}
// After
{
label: 'Name',
key: 'name',
validators: [
{validate: 'required'}
]
}

Regex changes

All regex shorthands (email, boolean, numeric) have been deprecated.

// Before
validators: [
{
validate: 'regex_matches',
regex: 'numeric',
error: 'must be a number'
}
]
// After
validators: [
{
validate: 'regex_matches',
regex: '^[0-9]+$',
error: 'must be a number'
}
]

All regex values now need to be a string. Because of this, there can be issues with escaping certain characters. If you need help with escaping, use this tool: click here.

// Before
validators: [
{
validate: 'regex_matches',
regex: ^[0-9]+$,
error: 'must be a number'
}
]
// After
validators: [
{
validate: 'regex_matches',
regex: '^[0-9]+$',
error: 'must be a number'
}
]

Select Options

Options may no longer use an array of strings, and must all use an array of objects with both value and label keys.

// Before
{
label: 'Color',
key: 'color',
description: 'Color Options',
type: 'select',
options: ['red', 'blue', 'yellow'] // deprecated syntax
}
// After
{
label: 'Color',
key: 'color',
description: 'Color Options',
type: 'select',
options: [
{ value: 'red', label: 'Red' },
{ value: 'blue', label: 'Blue' },
{ value: 'yellow', label: 'Yellow' }
]
}

Setting the Customer

One final requirement on version 2 is that the setCustomer method is now required. This method is where you will identify the user that is uploading a file. There are 5 keys that can be used for this object, but the userId is the only one that is required to be passed in.

FlatfileImporter.setCustomer({
userId: '12345',
name: 'John Doe', // Optional
email: 'johndoe@doe.com', // Optional
companyId: '09876', // Optional
companyName: 'Some Company' // Optional
})

Once you've updated your version and changed your Flatfile config, you're free to start using some of the new features on version 2.