Guide to configuring the Salesforce widget

In this article, we’ll show you how to display data from your Salesforce reports on your Geckoboard dashboards.

Salesforce reports are a powerful tool for making sense of all that data available within your Salesforce account. Our Salesforce integration makes visualizing your Salesforce reports really easy – you create the reports in Salesforce first and then build visualizations using those reports in Geckoboard.

Creating reports in your Salesforce account

Tip

Just starting out with using Salesforce reports? See our article on creating a report in Salesforce for Geckoboard. We also have a Salesforce reporting basics blog post that you may find useful.

For a more detailed guide to creating reports, see Salesforce's documentation.

Before you start

Some helpful points to keep in mind when using Geckoboard with Salesforce reports.

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.
  • Only support Summary and Matrix reports. Create a custom Summary or Matrix report for tracking the metrics you're interested in — just as you'd normally do 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.

Additionally, make sure that when 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.
  • 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.

So, 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. You can find more details in our Salesforce troubleshooting article.

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.

Further reading

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 – for example, 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.

Further reading

Salesforce help: How to summarize your report data

How Salesforce reports connect with Geckoboard

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.

In summary:

  • 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.
  • Leaderboards: Grouped fields will be available as the 'Labels' options and Summary fields as the corresponding 'Values'.
  • 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.

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:plot_options_report_config.png

You’ll then have 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, Column, and Bar Charts

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

Leaderboards

Labels: Opportunity Owner, Stage
Values: Sum of Amount, Average Probability, Average Number of Employees, Record Countplot_options_leaderboard.png

Number and Geck-O-Meter

Metric: Sum of Amount, Average Probability, Average Number of Employees, Record Countplot_options_number_geckometer.png

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

Build and display a Salesforce widget on your dashboard

  1. Click Add widget, located in the top right of your dashboard.
  2. Search for Salesforce using the Search sources field.

    Alternatively, you can also scroll down the alphabetical list of integrations until you reach the Salesforce integration.
  3. Click on the Salesforce integration.
  4. If you haven’t already, you’ll be prompted to connect your Salesforce account to Geckoboard.
  5. 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 your chosen report. Click on the report.choose_report.png
  6. 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.select_your_visualization.png

    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. 

  7. If required use the toggle switch 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.
  8. Next, click on the 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.fine_tune_widget.png

    Tip

    The 'Units' field supports emojis too!💰 😉

  9. Once you’re happy with how your widget is previewing, switch back to the Build tab.
  10. 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. widget_refresh_rate.png

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

  11. At any point, while configuring your widget you can Change report, Reload report, and Open report in Salesforce. 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_reload_open_report.png
  12. When you're happy with all the widget settings, click Add dashboard.
  13. Hover over your newly created widget and add a widget title.add_widget_title.png
  14. Drag the bottom right corner of your widget to adjust its size.

And you're done! You now have a widget on your dashboard displaying metrics from your Salesforce account 💥

Further reading

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

  • 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!
Was this article helpful?

Awesome! 👍  Thanks so much for your feedback!