Plugins 〉Salesforce

Data Source
grafana
Enterprise

Salesforce

  • Overview
  • Installation
  • Change log
  • Related content

Salesforce Grafana data source

The Salesforce data source plugin allows you to visualize data from Salesforce in Grafana.

Requirements

The Salesforce data source has the following requirements:

Known limitations

  • Ad-hoc filters are not supported yet.
  • Only SOQL queries, and data that is accessible via SOQL are currently supported. SOSL and SAQL query formats are not yet supported.

Install the plugin

To install the data source, refer to Installation.

Prerequisite [Salesforce Connected App]

A Salesforce Connected App. Note: The plugin currently uses the OAuth 2.0 Username-Password Flow. The required callback URL in the Connected App is not used. Thus, you can set it to any valid URL.

Required settings for the Grafana plugin

Enable OAuth settings : Check this to enable Oauth.

Callback URL : This is required in Salesforce but not used by the plugin. You can use any valid URL.

Selected OAuth Scopes (minimum requirements) : Access and Manage your data (api)

Require Secret for Refresh Token Flow : This can be enabled or disabled

Configure the data source in Grafana

Add a data source by filling in the following fields:

Authentication - JWT

Certificate : A public certificate that is used as the digital signature in your connected app. Can be self-signed. Click "Generate" to create a self signed cert or use your own.

Private Key : A private key for the cert.

User Name : The user name for the Salesforce account you want to use to connect and query Salesforce.

Consumer Key : A Consumer key to connect to Salesforce. You can obtain this from your Connected App

Authentication - Credentials

User Name : The user name for the Salesforce account you want to use to connect and query Salesforce.

Password : The password for the above user.

Security Token : The Security Token for the above user.

Consumer Key : A Consumer key to connect to Salesforce. You can obtain this from your Connected App

Consumer Secret : A Consumer secret to connect to Salesforce. You can obtain this from your Connected App

Use Sandbox : Select this if you want to use a Salesforce sandbox.

Configure the data source with provisioning

It is possible to configure data sources using configuration files with Grafana’s provisioning system. To learn more, read about how it works and about all the settings for data sources at Provisioning Grafana.

apiVersion: 1

datasources:

  • name: Salesforce type: grafana-salesforce-datasource editable: true enabled: true jsonData: user: user name secureJsonData: password: password securityToken: securityToken clientID: consumer key clientSecret: consumer secret

Query the data source

The query editor supports the modes Query Builder and SOQL Editor. SOQL stands for Salesforce Object Query Language.

Query Builder also known as SOQL Builder

Query Builder is a user friendly interface for building SOQL queries. If you are not familiar with writing SOQL queries, you can use this mode to build the SOQL to query Salesforce objects. The FROM field in the query builder refers to the entity or entities in Salesforce. You need to select the FROM field before any other operation in the query builder. After you choose the FROM field, you need to choose the builder mode. SOQL Builder currently supports the following modes.

ModesDescriptions
ListList the items with their fields from the selected table/salesforce. Use this mode to get results such as, "Show me list of opportunities created in this fiscal quarter along with their name, value, and stage."
AggregateAggregate the items in an entity. Use this mode to get results such as,"Count the opportunities created in last month." or "What is the total value of the opportunities grouped by their stage name?"
TrendDisplay the aggregated results over time. Use this mode to get results such as, "Count the number of opportunities by CreatedDate." or "What is the total sum of value grouped by opportunities' closing dates."

After you choose the Entity/FROM and the mode in the query editor, build your query using the following options.

FieldsApplicable toDescriptions
SELECTALLSelect the list of fields that you want to see. For the aggregate or trend view, also select how you want to aggregate the values.
WHEREALL(optional) Specify the filter conditions. The results are filtered based on the conditions that you select.
ORDER BYLIST, AGGREGATE(optional) Select the field name and the sort order that you want for the results.
LIMITLIST, AGGREGATE(optional) Limit the number of results returned. The default is 100.
GROUP BYAGGREGATE(optional) Select the field if you need to split the aggregated value by any specific field.
TIME FIELDTRENDSpecify the date field by which you want to group your results. Results are filtered based on Grafana's time picker range.

As you configure the preceding fields in the query editor, you will also see a preview of generated SOQL below the query editor. If you are blocked with any limitations in the query builder, you can safely switch to SOQL Editor, where you can customize the generated SOQL query.

SOQL editor

The raw SOQL editor provides the option to query Salesforce objects via raw a SOQL query. The SOQL editor provides autocomplete suggestions, such as available entities per tables and corresponding fields. Use Ctrl+Space after SELECT or WHERE to see the available entities per tables. You can see the available fields, if you enter a dot after the entity name.

Shortcuts

Press Ctrl + Space to show code completion, which will show available contextual options.

Cmd + S runs the query.

Query as time series

Make a time series query by aliasing a date field to time, and a metric field to metric, then grouping by the metric and date.

The following is an example:

SELECT sum(Amount) amount, CloseDate time, Type metric from Opportunity
group by Type, CloseDate

Macros

To filter by the dashboard time range, you can use Macros in your SOQL queries:

$__timeFrom : Will be replaced by the start of the currently active time selection converted to time data type.

$__timeTo : Will be replaced by the end of the currently active time selection converted to time data type.

$__quarterStart : The start of the fiscal quarter ( derived from SalesForce Fiscal Year Settings )

$__quarterEnd : The end of the fiscal quarter ( derived from SalesForce Fiscal Year Settings )

SELECT UserId, LoginTime from LoginHistory where LoginTime > $__timeFrom

Templates and variables

To add a new Salesforce query variable, refer to Add a query variable. Use your Salesforce data source as your data source. You can use any SOQL query here.

If you want to use name/value pairs, for example a user id and user name, return 2 fields from your SOQL query. The first field will be used as the ID. You may want to do this when you want to filter by key (ID, etc) in your query editor SOQL.

Use the variable in your SOQL queries by using Variable syntax.

For more information about variables, refer to Templates and variables.

Get the most out of the plugin

For more information, visit the docs on plugin installation.

Changelog

[1.0.0] 2021-09-09

  • Support JWT Authentication

[0.12.0] 2021-08-18

  • Reports

[0.11.0] 2021-08-06

  • SOQL Builder

[0.10.0] 2021-07-30

  • Fixed a bug where incorrect auth URL used for non sandbox accounts.
  • In config, Password and Security token now captured separately.
  • Improved error messages in healthcheck config

[0.9.3] 2021-07-08

  • Feature: Macros for Quarter Start/End

[0.9.2] 2021-06-23

  • Fix: Parent-to-child (one to many) relationship queries

[0.9.1] 2021-06-16

  • Feature: Query Editor Suggestions

[0.9.0] 2021-06-07

  • Beta release