Elastic Salesforce connector reference

edit

Elastic Salesforce connector reference

edit

The Elastic Salesforce connector is a connector for Salesforce data sources.

Availability and prerequisites

edit

This 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

edit

This connector is compatible with the following:

  • Salesforce
  • Salesforce Sandbox

Usage

edit

To 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

edit

The 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
  • 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

edit

Connector 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

edit

The 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 be foo. If you are using Salesforce Sandbox, your URL will contain an extra subdomain and will look similar to foo.sandbox.my.salesforce.com. In this case, your domain would be foo.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

edit

The 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

edit

Basic 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

edit

The 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

edit

The 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

edit

There are currently no known issues for this connector. Refer to connector known issues for a list of known issues for all connectors.

Security

edit

See connectors security.

Framework and source

edit

This connector is included in the Elastic connector framework.

View the source code for this connector (branch 8.11, compatible with Elastic 8.11).