Start Free Trial   Support

Salesforce Einstein Advanced Settings

Salesforce Einstein Analytics uses the OAuth 2 authentication standard. You will need to obtain the OAuthClientId and OAuthClientSecret by registering an app with Salesforce Einstein Analytics. See our authentication guide in Connecting to Salesforce Einstein Analytics.

Connecting to Salesforce Einstein Analytics

OAuth requires the authenticating user to interact with Salesforce Einstein Analytics using the browser. The provider facilitates this in various ways as described in the following sections.

Create a Connected App 

You can follow the procedure below to obtain the OAuth client credentials, the consumer key and consumer secret:

  1. If your organization uses the Salesforce Lightning Experience UI, from Setup enter App in the Quick Find box, select App Manager (not Manage Connected Apps), and click New Connected App.

    If your organization uses the Salesforce Classic UI, from Setup enter Apps in the Quick Find box and then select Apps, under Build or Create. Under Connected Apps, click New.

  2. Enter a name to be displayed to users when they log in to grant permissions to your app, along with a contact email address.

  3. Click Enable OAuth Settings and enter a value in the Callback URL box.

    If you are making a desktop application, set the Callback URL to http://localhost:33333 or a different port number of your choice.

    If you are making a Web application, set the Callback URL to a page on your Web app you would like the user to be returned to after they have authorized your application.

  4. Select the following OAuth scopes:

    Access and manage your wave data (wave_api)

    Access and manage your data (api)

    Perform requests on your behalf at any time (refresh_token, offline_token)

  5. Once you have created the app, click your app name to open a page with information about your app. The OAuth client credentials, the consumer key and consumer secret, are displayed.

Authenticate to Salesforce Einstein Analytics from a Desktop Application 

After setting the following connection properties, you are ready to connect:

  • OAuthClientId: Set this to the consumer key in your app settings.
  • OAuthClientSecret: Set this to the consumer secret in your app settings.
  • CallbackURL: Set this to the callback URL in your app settings.
  • InitiateOAuth: Set this to GETANDREFRESH. You can use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken connection property. 

When you connect the provider opens the OAuth endpoint in your default browser. Log in and grant permissions to the application. The provider then completes the OAuth process:

  1. Gets the callback URL and sets the access token to authenticate requests.
  2. Saves OAuth values in OAuthSettingsLocation to be persisted across connections.
  3. Exchanges the returned refresh token for a new, valid access token.

Authenticate to Salesforce Einstein Analytics from a Web Application 

To obtain the access token, set the following connection properties and follow the steps below:

  • OAuthClientId: Set this to the consumer key in your app settings.
  • OAuthClientSecret: Set this to the consumer secret in your app settings.
  • CallbackURL: Set this to the callback URL in your app settings.
When connecting via a Web application, or if the provider is not authorized to open a browser window, call the following stored procedures to obtain the access token:
  1. Call the GetOAuthAuthorizationURL stored procedure. The stored procedure returns the URL to the OAuth endpoint.

  2. Log in and authorize the application. You are redirected back to the callback URL.

  3. If you set the Grant_Type parameter to "code", the callback URL contains the verifier code in the query string parameter named "code". Extract the verifier code and call the GetOAuthAccessToken stored procedure.
To connect to data, set the following connection properties:
  • OAuthAccessToken
  • SalesforceInstanceUrl

Refreshing Access Tokens 

To automatically refresh the access token when it expires, set InitiateOAuth to "REFRESH" and set OAuthRefreshToken. Alternatively, call the RefreshOAuthAccessToken stored procedure when the access token expires. Given a refresh token as input, the procedure returns a valid OAuth access token.

Note: You can configure the session timeout in Salesforce by navigating to Setup -> Administration Setup -> Security Controls -> Session Settings.

Selecting Datasets

The following sections show how to execute SELECT statements to your Analytics datasets or lenses. See Data Model for information on how the provider models datasets as tables and lenses as views.

Selecting Datasets 

Reference the table name of a dataset by adding "Dataset_" as a prefix to the dataset name, as in the following query:

SELECT Id, Name, Item, Quantity, Amount FROM DataSet_Test WHERE Amount = 50
The following query assumes that the dataset has the column names Id, Name, Quantity, and Amount. The dataset may have more columns than what were selected and they can be in any order.
 
Selecting Lenses 

*Note: Auto-Generated Lenses, may not work correctly in our driver, due to some API restrictions. In order to make them work, currently we have this workaround as solution.

  1. From your dashboard choose LENSES
  2. Open the LENS which is not working and go to "SAQL Mode"
  3. Make a minor update (i.e: a white space in the end of the query)
  4. Save the LENS and wait some seconds for the changes to by applied
  5. After that you should be able to query that LENS 

Reference the table name of a lens by adding "Lens_" as a prefix to the lens name, as in the following query.

SELECT Id, Name, Item, Quantity, Amount FROM Lens_Test WHERE Amount = 50
The query above assumes that the lens has the column names Id, Name, Quantity, and Amount. The lens may have more columns than what were selected and they can be in any order.
 

Inserting Datasets

The provider offers the possibility to insert data into your Salesforce Analytics datasets.
 
Getting the metadata file
 
To insert data into an exisiting dataset, first you need to download the metadata file. You can download the metadata file during the process of creating a new dataset by performing the following steps:
  1. In Analytics, go to the home page, click Create, and then choose Dataset.
  2. Select CSV file to upload and click Next.
  3. From new opened window download the JSON metadata schema file by clicking Download File in dropdown list at Data Schema File section.
  4. For more info on Metadata format refer to this guide: https://resources.docs.salesforce.com/200/latest/en-us/sfdc/pdf/bi_dev_guide_ext_data_format.pdf 

or for an existing dataset, if you have a csv file with the dataset's data go through the same process as when creating a new dataset to get the metadata json file for it, but don't actually create the dataset.

Inserting data

To insert new data, the MetadataFilesLocation connection property is required. You must set its value to the location of the file where your metadata files are stored.
INSERT INTO Dataset_Example (Col1, Col2, Col3) VALUES ('val1', 'val2', 'val3')

INSERT INTO SELECT (Bulk inserting)

First you need to insert data into a temporary table. Temporary tables are denoted by a # appearing in their name. When using a temporary table to insert, the temporary table must be named in the format [TableName]#TEMP, where TableName is the name of the table you will be inserting to. For instance:
INSERT INTO Dataset_Example#Temp (Col1, Col2, Col3) VALUES ('val1', 'val2', 'val3')
INSERT INTO Dataset_Example#Temp (Col1, Col2, Col3) VALUES ('val4', 'val5', 'val6')
INSERT INTO Dataset_Example#Temp (Col1, Col2, Col3) VALUES ('val7', 'val8', 'val9')
Then you need to insert to the actual table.
INSERT INTO Dataset_Example (Col1, Col2, Col3) SELECT Col1, Col2, Col3 FROM Dataset_Example#Temp
If the AsyncBulkOperation connection property is set to 'true' the provider will allow Salesforce Einstein Analytics to process the data while your application continues executing. The downside of using asynchronous services is that you will need to check the status of the upload manually to see if Salesforce has finished processing the request and see if there were any issues. You can do this by calling the GetJobStatus stored procedure. You can get the value of the JobId required for the GetJobStatus stored procedure from the LastResultInfo#Temp table.
SELECT JobId FROM LastResultInfo#Temp

Upserting Datasets

The provider offers the possibility to upsert data into your Salesforce Analytics datasets.
 
Getting the metadata file
To upsert data into an exisiting dataset, first you need to download the metadata file. You can download the metadata file during the process of creating a new dataset by performing the following steps:
  1. In Analytics, go to the home page, click Create, and then choose Dataset.
  2. Select CSV file to upload and click Next.
  3. From new opened window download the JSON metadata schema file by clicking Download File in dropdown list at Data Schema File section.
  4. For more info on Metadata format refer to this guide: https://resources.docs.salesforce.com/200/latest/en-us/sfdc/pdf/bi_dev_guide_ext_data_format.pdf 

or for an existing dataset, if you have a csv file with the dataset's data go through the same process as when creating a new dataset to get the metadata json file for it, but don't actually create the dataset.

Upserting data

To upsert new data, the MetadataFilesLocation connection property is required. You must set its value to the location of the file where your metadata files are stored.
Note: The metadata file must contain one (and only one) field with a unique identifier.
UPSERT INTO Dataset_Example (Col1, Col2, Col3) Values ('val1', 'val2', 'val3')

UPSERT INTO SELECT (Bulk upserting)

First you need to insert data into a temporary table. Temporary tables are denoted by a # appearing in their name. When using a temporary table to upsert, the temporary table must be named in the format [TableName]#TEMP, where TableName is the name of the table you will be upserting to. For instance:
INSERT INTO Dataset_Example#Temp (Col1, Col2, Col3) VALUES ('val1', 'val2', 'val3')
INSERT INTO Dataset_Example#Temp (Col1, Col2, Col3) VALUES ('val4', 'val5', 'val6')
INSERT INTO Dataset_Example#Temp (Col1, Col2, Col3) VALUES ('val7', 'val8', 'val9')
Then you need to upsert to the actual table.
UPSERT INTO Dataset_Example (Col1, Col2, Col3) SELECT Col1, Col2, Col3 FROM Dataset_Example#Temp
If the AsyncBulkOperation connection property is set to 'true' the provider will allow Salesforce Einstein Analytics to process the data while your application continues executing. The downside of using asynchronous services is that you will need to check the status of the upload manually to see if Salesforce has finished processing the request and see if there were any issues. You can do this by calling the GetJobStatus stored procedure. You can get the value of the JobId required for the GetJobStatus stored procedure from the LastResultInfo#Temp table.
SELECT JobId FROM LastResultInfo#Temp

Deleting Datasets

The provider offers the possibility to delete data from your Salesforce Analytics datasets.

Getting the metadata file

To delete data from an exisiting dataset, first you need to download the metadata file. You can download the metadata file during the process of creating a new dataset by performing the following steps:
  1. In Analytics, go to the home page, click Create, and then choose Dataset.
  2. Select CSV file to upload and click Next.
  3. From new opened window download the JSON metadata schema file by clicking Download File in dropdown list at Data Schema File section.
  4. For more info on Metadata format refer to this guide: https://resources.docs.salesforce.com/200/latest/en-us/sfdc/pdf/bi_dev_guide_ext_data_format.pdf 

or for an existing dataset, if you have a csv file with the dataset's data go through the same process as when creating a new dataset to get the metadata json file for it, but don't actually create the dataset.

Deleting data

To delete existing data, the MetadataFilesLocation connection property is required. You must set its value to the location of the file where your metadata files are stored.
Note: The metadata file must contain one (and only one) field with a unique identifier.
DELETE FROM Dataset_Example WHERE Col1='uniqueValue'

DELETE FROM EXISTS SELECT (Bulk deleting)

First you need to insert data into a temporary table. Temporary tables are denoted by a # appearing in their name. When using a temporary table to delete, the temporary table must be named in the format [TableName]#TEMP, where TableName is the name of the table you will be deleting from. For instance:
INSERT INTO Dataset_Example#Temp (Col1) VALUES ('uniqueValue')
INSERT INTO Dataset_Example#Temp (Col1) VALUES ('uniqueValue')
INSERT INTO Dataset_Example#Temp (Col1) VALUES ('uniqueValue')
Then you need to delete from the actual table.
DELETE FROM Dataset_Example WHERE EXISTS SELECT Col1 FROM FROM Dataset_Example#Temp
If the AsyncBulkOperation connection property is set to 'true' the provider will allow Salesforce Einstein Analytics to process the data while your application continues executing. The downside of using asynchronous services is that you will need to check the status of the upload manually to see if Salesforce has finished processing the request and see if there were any issues. You can do this by calling the GetJobStatus stored procedure. You can get the value of the JobId required for the GetJobStatus stored procedure from the LastResultInfo#Temp table.
SELECT JobId FROM LastResultInfo#Temp

Uploading Datasets

The provider offers the possibility to to create datasets or insert data into your Salesforce Analytics datasets by using CSV files.

Uploading CSV files

You can upload CSV files to datasets by using the UploadCSVToDataset stored procedure. To upload a CSV file to a dataset the following parameters are required: DatasetName, CSVFileLocation. If the AsyncBulkInsert connection property is set to 'true' the provider will allow Salesforce Einstein Analytics to process the data while your application continues executing. The downside of using asynchronous services is that you will need to check the status of the upload manually to see if Salesforce has finished processing the request and see if there were any issues. You can do this by calling the GetJobStatus stored procedure.
  • DatasetName: The name of dataset you want to create or append data to.
  • CSVFileLocation: The location of the CSV file containing the data that will be uploaded.
  • Operation: The operation you want to use when you're loading data into the dataset. It is set to 'Append' by default. If set to 'Overwrite', a dataset with the given data will be created, and replaced if it exists.If set to 'Append', the given data will be added to an exisiting dataset or a new dataset will be created if it does not exist. A metadata file is required for 'Append' operations. The data and metadata for the 'Append' operations must exactly match the dataset on which the operation is happening.
  • MetadataFileLocation: This parameter is required when Operation is set to 'Append'.

Customizing the SSL Configuration 

By default, the provider attempts to negotiate SSL/TLS by checking the server's certificate against the system's trusted certificate store. To specify another certificate, see the SSLServerCert property for the available formats to do so.

Connecting Through a Firewall or Proxy

HTTP Proxies 

To connect through the Windows system proxy, you do not need to set any additional connection properties. To connect to other proxies, set ProxyAutoDetect to false.

In addition, to authenticate to an HTTP proxy, set ProxyAuthScheme, ProxyUser, and ProxyPassword, in addition to ProxyServer and ProxyPort.

Other Proxies 

Set the following properties:

  • To use a proxy-based firewall, set FirewallType, FirewallServer, and FirewallPort.
  • To tunnel the connection, set FirewallType to TUNNEL.
  • To authenticate, specify FirewallUser and FirewallPassword.
  • To authenticate to a SOCKS proxy, additionally set FirewallType to SOCKS5.

Troubleshooting the Connection 

To show provider activity from query execution to network traffic, use Logfile and Verbosity. The examples of common connection errors below show how to use these properties to get more context. Contact the support team for help tracing the source of an error or circumventing a performance issue.

  • Authentication errors: Typically, recording a Logfile at Verbosity 4 is necessary to get full details on an authentication error.
  • Queries time out: A server that takes too long to respond will exceed the provider's client-side timeout. Often, setting the Timeout property to a higher value will avoid a connection error. Another option is to disable the timeout by setting the property to 0. Setting Verbosity to 2 will show where the time is being spent.
  • The certificate presented by the server cannot be validated: This error indicates that the provider cannot validate the server's certificate through the chain of trust. If you are using a self-signed certificate, there is only one certificate in the chain.

    To resolve this error, you must verify yourself that the certificate can be trusted and specify to the provider that you trust the certificate. One way you can specify that you trust a certificate is to add the certificate to the trusted system store; another is to set SSLServerCert.