Menu

Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Documentationbreadcrumb arrow Pluginsbreadcrumb arrow Salesforce data source for Grafana

Salesforce Grafana data source

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

Requirements

This plugin 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

Credentials based

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

JWT based

Enable OAuth settings
Check this to enable Oauth.
Callback URL
sfdc://oauth/jwt/success

Enable Use digital signatures and upload the digital certificate

Selected OAuth Scopes (minimum requirements)
Access and Manage your data (api)
Perform requests on your behalf at any time
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
Environment
Defaults to Production salesforce environment. Select SandBox if you want to use a Salesforce sandbox environment. To learn more about Salesforce sandbox types, read salesforce docs

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.

yaml
apiVersion: 1
datasources:
  - name: Salesforce - user password authentication
    type: grafana-salesforce-datasource
    jsonData:
      authType: user
      user: user name
    secureJsonData:
      password: password
      securityToken: securityToken
      clientID: consumer key
      clientSecret: consumer secret
  - name: Salesforce - jwt authentication
    type: grafana-salesforce-datasource
    jsonData:
      authType: jwt
      user: user name
    secureJsonData:
      clientID: consumer key
      cert: |
        -----BEGIN CERTIFICATE-----
        xxxxxxxxxxxxxxxxxxxxxxxxxxx
        -----END CERTIFICATE-----
      privateKey: |
        -----BEGIN PRIVATE KEY-----
        xxxxxxxxxxxxxxxxxxxxxxxxxxx
        -----END PRIVATE KEY-----

To provision a sandbox environment, update the jsonData settings with sandbox property

yaml
jsonData:
  sandbox: true

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/Table (FROM) and the mode in the query editor, build your query using the following options.

FieldsApplicable toDescriptions
Fields (SELECT)ALLSelect the list of fields that you want to see. For the aggregate or trend view, also select how you want to aggregate the values.
Filters (WHERE)ALL(optional) Specify the filter conditions. The results are filtered based on the conditions that you select.
Order By (ORDER BY)LIST, AGGREGATE(optional) Select the field name and the sort order that you want for the results.
Limit (LIMIT)LIST, AGGREGATE(optional) Limit the number of results returned. The default is 100.
Group by (GROUP BY)AGGREGATE(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.

Filter Limitations

When using the Query Builder, queries will fail if using complex filter logic. If a query only has AND statements (or only has OR statements) on multiple filters, then the query will return properly. However, if leveraging both AND & OR statements, then it is recommended to use the SOQL Editor. The same is true if using nested filters.

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:

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