Skip Navigation
Show nav
Heroku Dev Center
  • Get Started
  • Documentation
  • Changelog
  • Search
  • Get Started
    • Node.js
    • Ruby on Rails
    • Ruby
    • Python
    • Java
    • PHP
    • Go
    • Scala
    • Clojure
  • Documentation
  • Changelog
  • More
    Additional Resources
    • Home
    • Elements
    • Products
    • Pricing
    • Careers
    • Help
    • Status
    • Events
    • Podcasts
    • Compliance Center
    Heroku Blog

    Heroku Blog

    Find out what's new with Heroku on our blog.

    Visit Blog
  • Log inorSign up
View categories

Categories

  • Heroku Architecture
    • Dynos (app containers)
    • Stacks (operating system images)
    • Networking & DNS
    • Platform Policies
    • Platform Principles
  • Command Line
  • Deployment
    • Deploying with Git
    • Deploying with Docker
    • Deployment Integrations
  • Continuous Delivery
    • Continuous Integration
  • Language Support
    • Node.js
    • Ruby
      • Working with Bundler
      • Rails Support
    • Python
      • Background Jobs in Python
      • Working with Django
    • Java
      • Working with Maven
      • Java Database Operations
      • Working with Spring Boot
      • Java Advanced Topics
    • PHP
    • Go
      • Go Dependency Management
    • Scala
    • Clojure
  • Databases & Data Management
    • Heroku Postgres
      • Postgres Basics
      • Postgres Getting Started
      • Postgres Performance
      • Postgres Data Transfer & Preservation
      • Postgres Availability
      • Postgres Special Topics
    • Heroku Data For Redis
    • Apache Kafka on Heroku
    • Other Data Stores
  • Monitoring & Metrics
    • Logging
  • App Performance
  • Add-ons
    • All Add-ons
  • Collaboration
  • Security
    • App Security
    • Identities & Authentication
    • Compliance
  • Heroku Enterprise
    • Private Spaces
      • Infrastructure Networking
    • Enterprise Accounts
    • Enterprise Teams
    • Heroku Connect (Salesforce sync)
      • Heroku Connect Administration
      • Heroku Connect Reference
      • Heroku Connect Troubleshooting
    • Single Sign-on (SSO)
  • Patterns & Best Practices
  • Extending Heroku
    • Platform API
    • App Webhooks
    • Heroku Labs
    • Building Add-ons
      • Add-on Development Tasks
      • Add-on APIs
      • Add-on Guidelines & Requirements
    • Building CLI Plugins
    • Developing Buildpacks
    • Dev Center
  • Accounts & Billing
  • Troubleshooting & Support
  • Integrating with Salesforce
  • Add-ons
  • All Add-ons
  • UseCSV
UseCSV

This add-on is operated by Layercode Limited

Easy CSV & Excel import for your app.

UseCSV

Last updated March 03, 2023

The UseCSV add-on is currently in beta.

Table of Contents

  • Provision the Add-on
  • Local Setup
  • Dashboard
  • Configure Importers
  • Include the Importer in Your Frontend
  • Receive Imported Data
  • Using Webhooks to Your Backend
  • Using the onData Callback in Your Frontend
  • Removing the Add-on
  • Support

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:

See a list of all plans available here.

$ 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

Don’t commit credentials and other sensitive configuration values to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

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 should rotate passwords every 90 days.

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.

You must create an Importer for each data schema your users must import.

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.

When importing data, your users match their uploaded CSV or Excel file to the destination columns you’ve configured.

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:

This destroys all associated data and can’t be undone!

$ 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.

Keep reading

  • All Add-ons

Feedback

Log in to submit feedback.

Ziggeo User Agent Identifier

Information & Support

  • Getting Started
  • Documentation
  • Changelog
  • Compliance Center
  • Training & Education
  • Blog
  • Podcasts
  • Support Channels
  • Status

Language Reference

  • Node.js
  • Ruby
  • Java
  • PHP
  • Python
  • Go
  • Scala
  • Clojure

Other Resources

  • Careers
  • Elements
  • Products
  • Pricing

Subscribe to our monthly newsletter

Your email address:

  • RSS
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku Blog
    • Heroku News Blog
    • Heroku Engineering Blog
  • Heroku Podcasts
  • Twitter
    • Dev Center Articles
    • Dev Center Changelog
    • Heroku
    • Heroku Status
  • Facebook
  • Instagram
  • Github
  • LinkedIn
  • YouTube
Heroku is acompany

 © Salesforce.com

  • heroku.com
  • Terms of Service
  • Privacy
  • Cookies
  • Cookie Preferences