Below is a video tutorial where I go from create React app to a CSV import thanks to Flatfile Portal. Flatfile Portal is a drop-in data importer that helps users ingest, structure and validate data in minutes versus weeks. I’ve also outlined the steps. Let’s give it a try!
Before you begin you’ll need to have a license key. You can sign up here or if you spin up the local demos, you can use GitHub to sign up for your account.
Let’s also take a moment to check out the complete code example before breaking it down into separate sections.
Step 1: NPM Install
Before implementing flatfile, we need to install the packages using either NPM or Yarn.
npm install @flatfile/adapter
yarn install flatfile-csv-importer
Step 2: Import Flatfile/setVersion
Be sure to import the CSV importer into the project file that you intend to use this in. This gives access to the importer and all the SDK references it comes with. Be sure to specify the correct version of Flatfile's data importer. To do this, we need to use setVersion and specify version 2.
IMPORTANT NOTE: If you forget to set the version to 2, this will default to version 1 and you will likely see lots of errors. Version 1 is a legacy product that we no longer actively support. Please make sure to set version 2 here. Are you currently on version 1 and want to move to version 2? Here are the differences between the two and how you can switch. Additionally, check out the full list of 30+ features in Flatfile Portal 2.0 here.
Step 3: Use it and provide the license key
Next let's open an instance of Flatfile importer. We recommend defining it as a variable as you see below. The Flatfile Importer function takes in the license key and the configuration options as its two parameters. If you're following along with the demos we provided and you signed in with GitHub, you’ll notice we’re returning the license key to the demo for you as a URL Parameter. If you don’t go this route, you'll need to grab your license key from the dashboard here and put it in this function.
Step 4: Configuration - type and fields required
There are two required items for the configuration to work:
First is type. This means the type of imports you’re doing. This comes in handy if you use Flatfile's data importer for multiple parts of your application to specify which type of import is happening.
The second is fields. The fields configuration is an array of objects, each item in the array is one field or column in your data model. At a minimum, this is where you will define your data model. The only two required keys for each field are key (this should be what you call this data type in your database) and label (this is what your users will see as the field type). We’ll use name and email as the fields here. If you're looking for more details on what else is available to use for the field configuration, check out the field configuration section of the docs.
Step 5: Setting the customer
For imports to work properly, you'll have to set the customer/user in order to specify who the user is that’s uploading the file.This helps you identify who belongs to what file for your records, and also, if you've got your Flatfile dashboard set up properly, you'll be able to see the file and user there as well.
Step 6: Launch the importer
At a minimum, we need a way to launch the importer (this will be a button or link or some flow from your application that triggers an import), to use the requestDataFromUser SDK reference within the importer which returns a promise with the results. We can then take the results and do with them as you please!
While the above is the minimum required to get Flatfile working and processing your files, we recommend you also include two extra pieces of the SDK (and then also check out more of the SDK to see what else you can do). One, we suggest that you use the displayLoader() function. For a lot of files, this won't make a huge difference for imports, but for larger files that may take a few moments to process, this will give the UI a status bar indicator so that the application doesn't appear to be hung up or unresponsive to a user. The second thing we recommend is adding the displaySuccess() method. This allows you to pass a custom success message to 1) let the user know the upload was successful and 2) closes the importer when they’ve acknowledged the successful import. If this method is not used, the UI hangs on from the last step and the user would need to close out of the importer (using the ‘x’ at the top).
The final piece is assigning this function call to some UI element to open the importer. Within the context of a fresh create-react-app instance, we just created a button and called the function onClick, but you could build this into its own component as well.
Step 7: Returned data
Once the user has successfully gone through the import process, you’ll have results returned as JSON. In the example, we just logged the results to the console, but you could send them to your server or use them directly within your application here. We also used validData, but there are multiple other options for getting the exact data needed on FlatfileResults, such as allData. Check out the SDK docs for a complete list of those options.
Launching Flatfile and matching data accurately
At this point the React app looks exactly the same but the basics have been set up for the Flatfile application and we can run Flatfile. We’ll create a button with an onClick event calling the launch function and click on that to launch Flatfile. This will take you into the normal flatfile import flow. Based on how we set this up, when that flow is complete, it will log the flatfile results to the console. Check out the developer documentation from Flatfile if you need any help. (And learn more about creating a truly seamless CSV import experience here.)