This add-on is operated by Layercode Limited

Easy CSV & Excel import for your app.

Last updated March 03, 2023

UseCSV makes it easy to add simple and secure CSV & Excel import functionality to your app. Integrate UseCSV Javascript into your application and then import data via a modal window. Import functionality is provided by the UseCSV CSV importer. Imported data is sent as JSON to your backend by secure webhook. Alternatively, use a JS callback if you want to keep data local.

Provision the Add-on

Attach UseCSV to a Heroku application via the CLI:

$ heroku addons:create usecsv
-----> Adding usecsv to my-app-1234... done, v1 (free)

You can also attach your UseCSV add-on to another Heroku app using the following command:

$ heroku addons:attach usecsv-convex-12345 -a my-app-1234
-----> Attaching usecsv-convex-12345 to my-app-1234... done, v1 (free)

After provisioning UseCSV, the USECSV_WEBHOOK_SECRET config variable will be available in your app’s configuration. Use it to verify webhook requests that come from UseCSV when data is uploaded.

Visit the UseCSV Dashboard to configure an Importer. An Importer sets the columns and validation rules for imports.

Local Setup

Environment Setup

After provisioning the add-on, it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Use the Heroku Local command-line tool to configure, run, and manage process types specified in your app’s Procfile. Heroku Local reads configuration variables from a .env file. To view all of your app’s config variables, type heroku config. Use the following command for each value that you want to add to your .env file:

$ heroku config:get USECSV_WEBHOOK_SECRET -s  >> .env

For more information, see the Heroku Local article.

Dashboard

Use the UseCSV dashboard to:

• Configure Importers, their columns and validation rules.
• Get the Key for an Importer, which is required when using the frontend library.
• Get usage metrics and monitor your add-on usage.
• Rotate your webhook secret. This action generates a secret and changes the value of the USECSV_WEBHOOK_SECRET config var.

You can access the dashboard via the CLI:

$ heroku addons:open usecsv
Opening usecsv for my-app-1234

or by visiting the Heroku Dashboard and selecting the application in question. Select UseCSV from the Add-ons menu.

Configure Importers

Importers define the columns and validations rules for your users when importing data with UseCSV. Before integrating UseCSV with your frontend and backend, you must configure at least one Importer.

Manage Imports from the UseCSV dashboard.

To create an Importer:

1. Click Add Importer.
2. Enter a name for the Importer.
3. Click Save.

You’ll now see the details for this new Importer. The next step is to configure it.

Create Columns

Click Add Column and enter a Name, Description, and Example and then choose a Validation Format. Add as many columns as required.

Configure a Webhook URL

To receive imported data as a webhook, you must enter a Webhook URL. The Webhook URL endpoint must accept a JSON POST request. See the Webhook docs for more information.

If you don’t want to send imported user data to UseCSV, use the frontend onData callback method to disable the webhook. If you disable the webhook, only metadata is sent to UseCSV.

Include the Importer in Your Frontend

Next add the UseCSV Importer modal to your frontend so your users can import their data using the step-by-step UseCSV import process. Visit documentation your relevant framework below:

• Javascript
• React
• Vue.js
• Angular

Receive Imported Data

You’re now ready to receive imported data. Use the Webhook or onData callback options below.

Using Webhooks to Your Backend

When a client uploads a csv file using your Importer in the frontend, UseCSV sends the csv rows to the Webhook URL in 1,000 row batches. Each batch request waits for a response from your backend before sending the next batch request. This makes it easy for you to process the import in your backend as part of the webhook request, without the need to manage your own processing queuing system.

Webhook Request Format

POST <Webhook URL (set in Importer)>
HEADERS
  WEBHOOK_SECRET: <Webhook Secret (find it in API Keys section of UseCSV admin)>
body:
{
  "uploadId": 231 // ID of the uploaded file
  "importerId": "35a01b40-31f5-4d35-9f79-b844d5b1a423" // ID of the Importer
  "batch": {
    "index": 1 // which batch number this request is (starts at 1)
    "count": 2 // total number of batches to be sent
    "totalRows": 2000 // total rows in all batches in this import
  }
  "user": {
    "userId":1 // JSON data provided by you through the plugin
  },
  "metadata": {...}, // JSON data provided by you through the plugin
  "rows": [
    {
        "firstname": "john",
        "lastname : "adams"
     },
    ......
  ]
}

Your webhook server must respond to receive the next batch. There’s a 10-minute request timeout.

Respond with a 200 status to continue and receive the next batch. Responding with any other status code halts further webhook requests for the batch.

If specific rows can’t be imported, and you want to let the user know, you can include an errors JSON array in the body of your 200 response:

status: 200
body: {
  errors: [
    {
      row: 1, // row number
      msg: "this row is invalid"
    }
  ]
}

The user is able to download a csv file of failed rows with these errors included in an error column.

Verify Webhook Requests

Webhook requests include a WEBHOOK_SECRET header, which can be used to verify that the request has come from UseCSV. Find the WEBHOOK_SECRET value in the API Keys admin section, and when you receive a webhook request, check the WEBHOOK_SECRET header matches this value. Reject requests that don’t match the value or don’t include the WEBHOOK_SECRET header.

The Webhook Secret config var is automatically set in your Heroku app as USECSV_WEBHOOK_SECRET.

Validate Uploads

When a user uploads a file using the Importer plugin in your app, you can validate who made the upload by including one or more attributes in the frontend Importer user and/or metadata props. For example, you can include a userId attribute in the user prop, which you can then verify in your backend when a webhook is received.

Using the onData Callback in Your Frontend

If you prefer to handle your data locally, you can use the onData callback option. When a user completes the import process, this function is called with the imported data. Using this automatically disables the webhook and only metadata is sent to UseCSV. Refer to the options section in the relevant CSV importer library for more information about using the onData callback.

Removing the Add-on

You can remove UseCSV via the CLI:

$ heroku addons:destroy UseCSV
-----> Removing UseCSV from sharp-mountain-4005... done

Support

UseCSV support and runtime issues should be submitted via one of the Heroku Support channels. We recommend adding support@stackhero.io in copy for urgent issues.