Moving to Portal v2

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

If you're on version 1 and using NPM, install the new Portal adapter.

npm install @flatfile/adapter

After installing, your package.json should reflect version 2.0.0 or higher.

{
  "dependencies": {
    "@flatfile/adapter": "^2.1.1"
  }
}

If you are going the NPM route, you'll want to make sure to remove the old dependncy from your code as the two versions assume you're using different versions of Flatfile by default.

npm uninstall flatfile-csv-importer

If you're loading Flatfile via CDN, change the CDN link to https://unpkg.com/@flatfile/adapter/build/dist/index.min.js.

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.