CSV widgets are one of the more flexible ways of adding proprietary data to your dashboard. In this article, we'll help you learn the key concepts of how to structure your data and push it to Geckoboard reliably using CSV widgets.
Why would I use a CSV widget?
Geckoboard integrates with 80+ cloud services out of the box. However, sometimes you may wish to display data from sources Geckoboard doesn’t integrate with. In these scenarios our CSV data source sits alongside our Google Sheets and Excel data source as an easy way to push data to your dashboard.
This article will run you through some of the scenarios when you might want to consider using this, will introduce you to how our CSV data source works, and provide some example configurations for you to test out.
Introducing Geckoboard’s CSV data source
Building widgets using a .csv file as a data source is a little different to using one of our other third-party data sources. Unlike other data sources, you'll need to find a way to format and host your data in a way that your widgets will understand. Depending on how your data is generated, you may also need to figure out a way to make your .csv file update frequently so you are displaying up-to-data values on your dashboard.
Formatting your CSV file
To push data to a CSV widget on Geckoboard, you must first create a .csv file that acts as your data source. As a minimum, this file should contain at least one column and one row, and should contain at least one number.
In addition, the data in your .csv file must contain only plain letters and numbers - special characters such as currency symbols will not be processed in your CSV widget and may produce an error.
Note: In order to display some visualizations your .csv file may need to contain more than one numerical value. See Widget Examples later in this guide for more information.
There is no hard limit to the number of columns or rows your .csv file can contain, and to make configuring your widget easier, Geckoboard displays the contents of the first row of data as you set your widget up. This makes it possible to use a single .csv file to serve multiple data sets - if you do this, consider using the first row of your CSV file for adding titles to your columns as this will make identifying data easier during setup.
Values in your .csv file can be updated manually or programmatically. If needed, for example, you could update sales figures in your CSV file every 10 minutes with a script that pulls raw data from your internal systems and updates a value in your .csv file.
Bear in mind that however you update your .csv file, in order for your widgets to display correctly, you will need to format your data in columns.
Hosting your CSV file
Once your .csv file comes together, you'll next need to host it at a URL Geckoboard can access. This URL will act as the data source you connect to your CSV widget. Depending on how you generate the data in your .csv file, one of the following approaches will work best:
Host using cloud-based storage
Dropbox is ideal for hosting your CSV file
This method requires no technical input, allows the file to be updated by other members of your organization to update data and is undoubtedly the quickest way to host a file. However, this approach lacks some of the security options available through other hosting techniques.
If you don't have your own web hosting solution already set up or just need a quick and simple way to host your .csv file, Dropbox, or similar cloud-based storage, offers a quick and simple solution.
Create a Dropbox account and upload your .csv file. Right click on the file on your desktop machine or log in to Dropbox.com to generate a public link to the file.
Host on web hosting
If you have your own web hosting, upload your .csv file via FTP to create a direct link to the file. If your data updates programmatically, make sure the resulting .csv file is available at a static URL.
Password protect your data
Geckoboard’s CSV widgets support basic auth, meaning that provided this is set up on your server, you can protect your .csv file via a username and password. These credentials are passed along in the URL you provide to Geckoboard to connect your data - along the lines of http://username:password@yourdomain.com/filename.csv - offering a basic level of protection to your data.
Pulling CSV data directly from a service
Some third-party platforms offer the ability to export data as a .csv file for use in other systems. In some cases this may work as a way for you to pull data into Geckoboard without having to go through the added step of hosting this data elsewhere, as long as the .csv file is available at a static URL. The success of this method very much depends on how the third-party service formats its data in the .csv file, so feel free to experiment!
Building and configuring your CSV widget
Once you have a valid .csv file that’s available at a static URL, the next step is to create a widget to visualize the data within it.
On your Geckoboard dashboard, click Add widget.
Choose CSV from the list of data sources. You can also type 'csv' in the Search sources box.
Select a widget from the available options.
Give your widget a Title.
Paste the link to your
.csvfile in the CSV URL field labelled.Click anywhere on the page away from this field, and your widget will then attempt to pull data from the URL you provided.
If your CSV is formatted correctly, your widget should load some additional option fields that will allow you to define the rows and columns data should be pulled from.
Start by defining which rows and columns you would like your widget to plot by selecting them in the drop-downs that appear.
The widget will pull through the first value it finds for each row and column in your
.csvfile as a preview. If you have set aside the first row and column in your.csvfile to be a descriptive title then this is what will be shown.After selecting your rows and columns, some widgets will provide further options for configuring the data how you want it.
Note: The options for selecting and visualizing your data that become available to you will vary depending on the widget you have chosen to set up.
A simple number widget, for example, will require you to simply select a column and row from your CSV data, after which the value from that cell is displayed as a number in your widget.
More advanced visualizations such as funnels and line charts will require you to select two columns in order for your widget to fetch data to plot the visualization you’ve chosen.
Examples of the CSV data source in action
The following examples display some of what's possible with the CSV data source, and all use data from the same .csv file.
Example CSV file
Download the example CSV file to try for yourself, or open the data in Google Sheets to see how it's been structured.
Further reading
Exporting CSV files from Excel: https://www.udemy.com/blog/convert-excel-to-csv-2/
Convert to/from CSV tool: http://www.convertcsv.com/