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.
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. SelectSandBox
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.
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
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.
Modes | Descriptions |
---|---|
List | List 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.” |
Aggregate | Aggregate 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?” |
Trend | Display 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.
Fields | Applicable to | Descriptions |
---|---|---|
Fields (SELECT ) | ALL | Select 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 field | TREND | Specify 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:
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
- Add Annotations.
- Configure and use Templates and variables.
- Add Transformations.
- Set up alerting; refer to Alerts overview.