DocumentationPluginsSalesforce 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:

• A Salesforce account
• A Salesforce Connected App
• One of the following account types:
  • Available for users with a Grafana Cloud Free, Advanced or Trial account or with an activated Grafana Enterprise license.

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 Copy

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 Copy

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.

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

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 Copy

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 Copy

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

• Add Annotations.
• Configure and use Templates and variables.
• Add Transformations.
• Set up alerting; refer to Alerts overview.