Elastic Salesforce connector reference
editElastic Salesforce connector reference
editThe Elastic Salesforce connector is a connector for Salesforce data sources.
Availability and prerequisites
editThis connector is available as a connector client using the Elastic connector framework. This connector client is compatible with Elastic versions 8.10.0+. To use this connector, satisfy all connector client requirements.
This connector is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features.
Compatibility
editThis connector is compatible with the following:
- Salesforce
- Salesforce Sandbox
Usage
editTo use this connector as a connector client, use the Connector workflow in the Kibana UI.
For additional operations, see connectors usage.
You need to create an Salesforce connected app with OAuth2.0 enabled to authenticate with Salesforce.
Create a Salesforce connected app
editThe Salesforce connector authenticates with Salesforce through a connected app. Follow the official Salesforce documentation for Configuring a Connected App for the OAuth 2.0 Client Credentials Flow.
When creating the connected app, in the section titled API (Enable OAuth Settings) ensure the following settings are enabled:
- Enable OAuth Settings
-
Enable for Device Flow
-
Callback URL should be the Salesforce dummy callback URL,
https://test.salesforce.com/services/oauth2/success
-
Callback URL should be the Salesforce dummy callback URL,
- Require Secret for Web Server Flow
- Require Secret for Refresh Token Flow
- Enable Client Credentials Flow
All other options should be disabled. Finally, in the section Selected OAuth Scopes, include the following OAuth scopes:
- Manage user data via APIs (api)
- Perform requests at any time (refresh_token, offline_access)
Deployment using Docker
editConnector clients are run on your own infrastructure.
You can deploy the Salesforce connector as a self-managed connector client using Docker. Follow these instructions.
Step 1: Download sample configuration file
Download the sample configuration file. You can either download it manually or run the following command:
curl https://raw.githubusercontent.com/elastic/connectors/main/config.yml.example --output ~/connectors-config/config.yml
Remember to update the --output
argument value if your directory name is different, or you want to use a different config file name.
Step 2: Update the configuration file for your self-managed connector
Update the configuration file with the following settings to match your environment:
-
elasticsearch.host
-
elasticsearch.api_key
-
connectors
If you’re running the connector service against a Dockerized version of Elasticsearch and Kibana, your config file will look like this:
# When connecting to your cloud deployment you should edit the host value elasticsearch.host: http://host.docker.internal:9200 elasticsearch.api_key: <ELASTICSEARCH_API_KEY> connectors: - connector_id: <CONNECTOR_ID_FROM_KIBANA> service_type: salesforce api_key: <CONNECTOR_API_KEY_FROM_KIBANA>
Using the elasticsearch.api_key
is the recommended authentication method. However, you can also use elasticsearch.username
and elasticsearch.password
to authenticate with your Elasticsearch instance.
Note: You can change other default configurations by simply uncommenting specific settings in the configuration file and modifying their values.
Step 3: Run the Docker image
Run the Docker image with the Connector Service using the following command:
docker run \ -v ~/connectors-config:/config \ --network "elastic" \ --tty \ --rm \ docker.elastic.co/enterprise-search/elastic-connectors:8.11.4.0 \ /app/bin/elastic-ingest \ -c /config/config.yml
Refer to DOCKER.md
in the elastic/connectors
repo for more details.
Find all available Docker images in the official registry.
Configuration
editThe following settings are required to set up this connector:
-
domain
(required) -
The domain for your Salesforce account.
This is the subdomain that appears in your Salesforce URL.
For example, if your Salesforce URL is
foo.my.salesforce.com
, then your domain would befoo
. If you are using Salesforce Sandbox, your URL will contain an extra subdomain and will look similar tofoo.sandbox.my.salesforce.com
. In this case, your domain would befoo.sandbox
. -
client_id
(required) - The Client ID generated by your connected app. The Salesforce documentation will sometimes also call this a Consumer Key
-
client_secret
(required) - The Client Secret generated by your connected app. The Salesforce documentation will sometimes also call this a Consumer Secret.
Finding the Client ID and Client Secret
editThe Client ID and Client Secret are not automatically shown to you after you create a connected app. You can find them by taking the following steps:
- Navigate to Setup
- Go to Platform Tools > Apps > App Manager
- Click on the triangle next to your app and select View
- After the page loads, click on Manage Consumer Details
Your Client ID and Client Secret should now be visible at the top of the page.
Sync rules
editBasic sync rules are identical for all connectors and are available by default.
Advanced sync rules are not available for this connector in the present version.
For more information read sync rules.
Documents and syncs
editThe connector syncs the following Salesforce objects:
- Accounts
- Campaigns
- Cases
- Contacts
- Content Documents (files uploaded to Salesforce)
- Leads
- Opportunities
The connector will not ingest any objects that it does not have permissions to query.
Content Extraction
editThe connector will retrieve Content Documents from your Salesforce source if they meet the following criteria:
- Are attached to one or more objects that are synced
- Are of a file type that can be extracted
This means that the connector will not ingest any Content Documents you have that are not attached to a supported Salesforce object. See documents and syncs for a list of supported object types.
If a single Content Document is attached to multiple supported objects, only one Elastic document will be created for it.
This document will retain links to every object that it was connected to in the related_ids
field.
See content extraction for more specifics on content extraction.
Known issues
editThere are currently no known issues for this connector. Refer to connector known issues for a list of known issues for all connectors.
Security
editSee connectors security.
Framework and source
editThis connector is included in the Elastic connector framework.
View the source code for this connector (branch 8.11, compatible with Elastic 8.11).