Guide to configuring the Salesforce widget

In this tutorial, we’ll check out how to display data from your Salesforce reports on your Geckoboard dashboards.

Your Salesforce account offers a wealth of data. Behind the scenes, it’s just a database containing information about your leads, accounts, opportunities, etc. Salesforce reports are a powerful tool for making sense of all that data available within your (Salesforce) account — to answer important business questions.

Geckoboard dashboards are then a great way of displaying those important metrics to your Sales (and other) teams — making the data useful and actionable to everyone!

Our integration makes visualizing your Salesforce reports really easy. The way our integration works — you create the reports in Salesforce first and then build visualizations using those reports in Geckoboard.

Let’s get started!

Creating reports in your Salesforce

As Salesforce already offers comprehensive documentation and guides on creating reports, we’ll not be covering this again here. If you’re just starting out with using Salesforce reports, we have a Salesforce reporting basics blog post that you may find useful.

Further, you can always search online for more guides that’ll help you build Salesforce reports to fetch the particular numbers you’re interested in.

Some helpful points to keep in mind:

  1. Our Salesforce integration can only visualize data from Custom Reports. Salesforce provides a collection of standard reports by default. These will not show up in Geckoboard, and you cannot visualize data from them on your dashboards.

    You can create a custom report by either building a new report from scratch or by customizing an existing standard report to your requirements. 

  2. Our Salesforce integration supports only Summary and Matrix reports. Basically, the idea here is that you create a custom Summary or Matrix report for tracking the metrics you're interested in — just as you normally would in Salesforce. Geckoboard will then be able to pull in and display those metrics on your dashboards.

    Get in touch: If you'd like to use Tabular or Joined reports, drop us a line and let us know how they'll be useful to you.

  3. Make sure you save your reports in a folder that your Salesforce user account (i.e. the one connected to Geckoboard) has access to or under public folders. Geckoboard cannot read private reports that your Salesforce user doesn't have access to.
  4. Whenever you create a new report or make changes to an existing one, make sure to run the report as well, using the Save and Run Report option within Salesforce.

Grouping your report data

The data within your reports need to be aggregated using groups to be plottable in a chart.

Thus, regardless of whether you’re using a Summary or Matrix report, you’ll need to have at least one grouped field (column) within your Salesforce report. Otherwise, you’ll receive an error such as "Cannot read property 'xAxis' of undefined" or similar depending on your browser (more details under the 'General Salesforce troubleshooting tips' section here).

Summary reports can have up to three groupings while Matrix reports can have four (two row and two column groupings). For Matrix reports, you can't use the same field for both row and column groupings.

Grouping your report data will also automatically provide you with the record count metric (number of items) for each group.

If you need, you can learn how to group your report data from the Salesforce documentation.

Tip: If you group your report by a date field, you can click the group menu, select Group Dates By, and specify the grouping time frame: day, week, month, quarter, year, etc. group_dates_by.png

Summarizing your report data

Showing the record count (number of items) for each group is useful, but often you’re interested in other metrics as well such as say the total sales value or average probability.

This is where summarizing your report data comes into play. Any numeric property can be added as a summary field. The report builder in Salesforce gives you the choice Sum, Average, Min, or Max.

Summary fields show at all grouping levels (that is, for each group within your report + even if there are multiple groupings). In Summary and Matrix reports, they also appear at the grand total level.

If you need, you can learn how to summarize your report data from the Salesforce documentation. 

How your reports translate and plot within Geckoboard?

Here’s where things get interesting! 😃

The grouped fields from your report act as the base while the summary fields act as the metrics. That is, you can plot a summary metric against a grouped field.

What this actually means is:

  • For Line Charts, Column Charts, and Bar Charts: Grouped fields will be available as the X-Axis options while Summary fields as the Y-Axis options. 
  • For Leaderboards: Grouped fields will be available as the 'Labels' options and Summary fields as the corresponding 'Values'.
  • For Number and Gecko-O-Meter: As these widgets can display only numerical data, they display values from just the summary fields. The value displayed will be the summarized metric (i.e. Sum, Avg, Min, Max) calculated based on all the records available within the report. For example, the metric displayed can be Sum of Total Sales Amount, Average Probability, Maximum Price, etc.

For example, let’s say you have a Salesforce report (can be either Summary or Matrix) with the following Grouped fields: Opportunity Owner, Stage and the following Summary fields: Amount (sum), Probability (avg), Number of Employees (avg). The report preview would look something like this:


You’ll then have the following options to plot within your Geckoboard widgets:

Tip: On all widgets, the Record Count (number of items) summary metric will always be available for each grouped field within your report. 

Line Charts, Column Charts, and Bar Charts

X-Axis options: Opportunity Owner, Stage
Y-Axis options: Sum of Amount, Average Probability, Average Number of Employees, Record Count



Labels: Opportunity Owner, Stage
Values: Sum of Amount, Average Probability, Average Number of Employees, Record Count


Number and Geck-O-Meter

Metric: Sum of Amount, Average Probability, Average Number of Employees, Record Count


Now that you have a good grasp of how things work, let’s check out how to build the widget in Geckoboard 📈

Building and displaying the widget on your dashboard

  1. Click Add widget, located in the top right of your dashboard.Add_widget.jpg
  2. Search for 'Salesforce' using the ' Search sources' field. Alternatively, you can also scroll down the list of integrations ordered alphabetically till you reach the Salesforce integration. Click on the integration to proceed further.
  3. If you haven’t already, you’ll be prompted to connect your Salesforce account to Geckoboard.
  4. You'll now see the 'Choose Report' page which displays the list of your Salesforce reports folders. You can use the ' Search' field or manually navigate through the folders to arrive at the report you want. Click on the report to proceed further.
  5. The widget configuration page will show up — this is where you actually build your widget.

    Select the visualization from the top right. You'll see a preview of the widget.

    Tip: Using appropriate visualizations can make a world of difference while consuming your dashboards and can help inspire action. We’ve created this handy flowchart which makes it easy to identify the best visualization for the metric you're looking to display. 

  6. If you need, enable the option to set a Goal and fill in your Goal value. You can also specify whether it's a 'Less than' and 'More than' Goal.

    On the Number widget, you'll have the option to 'Track % progress' toward the Goal. While on the Geck-O-Meter, you'll have options to also specify the min. and max. values.
  7. Next, click on 'Fine-tune' tab, towards the top-left, to configure abbreviations, decimal places, and units. You can leave these at their default 'Auto' settings if things already look good.

    Tip: The 'Units field supports emojis too!💰 😉

  8. Once you’re happy with how your widget is displaying (within the preview), switch back to the 'Build' tab.

    From near the bottom-left, specify how often you want this widget to refresh. It'll also let you know how many API calls the widget will use per day. You'll need to specify the refresh rate for each Salesforce widget you add. 

    Tip: We have a useful guide which explains how to choose an appropriate refresh rate and offers some suggestions on how you can optimize and reduce the number of API calls used by your Geckoboard widgets (especially helpful if you have a lot of Salesforce widgets on your dashboards).

  9. At any point, while configuring your widget:

    You can open the corresponding report within your Salesforce. 

    Reload the report — Any changes you've made within your report will be picked up and fetched immediately into the widget. This is especially handy when initially building the widget or while testing things.

    Change the report being used to power the widget. 
  10. When you're happy with all the widget settings, click 'Add to dashboard'.
  11. Hover over your newly created widget and add a widget title.add_widget_title.png
  12. Drag the bottom right corner of your widget to adjust its size.
Great job! You now have a widget on your dashboard displaying metrics from your Salesforce 💥

Recommended further reading

Now that you're comfortable with adding Salesforce widgets, we'd recommend checking out the following articles next: 

  • How to troubleshoot issues with your Salesforce widgets.
  • A Sales Dashboard example and step-by-step guide to building it from scratch using our Salesforce integration. We explain how to build some useful and interesting Salesforce widgets there!

Happy Dashboarding! 📈 📊

Was this article helpful?

Thank you for your feedback!