Select spec version:

Salesforce Destination Config Reference

Beta

Complete Rudder CLI reference for the Salesforce destination config keys, authentication, record mapping, source types, and secrets.

Available Plans

free
growth
enterprise

6 minute read

Salesforce is a CRM destination. RudderStack creates and updates Salesforce leads — or other Salesforce objects — from identify events, from its servers.

In a Salesforce destination spec:

type: salesforce
definition_version: 1

RudderStack has deprecated this destination in favor of Salesforce v2, which Rudder CLI doesn’t support.

Sample configuration

yaml

version: rudder/v1
kind: destination
metadata:
  name: salesforce-prod
spec:
  id: salesforce-prod
  display_name: Salesforce Production
  type: salesforce
  definition_version: 1
  enabled: true
  config:
    user_name: "{{ .SALESFORCE_USER_NAME }}"
    password: "{{ .SALESFORCE_PASSWORD }}"
    initial_access_token: "{{ .SALESFORCE_SECURITY_TOKEN }}"
    sandbox: false

    map_properties: true
    use_contact_id: false

    connection_mode:
      web: cloud
      cloud: cloud
    consent_management:
      web:
        - provider: oneTrust
          consents:
            - marketing

The above example signs in to a production org. initial_access_token holds the user’s security token, not an access token — see Authentication.

Config keys

config accepts only the keys listed below. The shared config key rules cover unknown keys, defaults, and immutability.

Salesforce accepts only identify events. RudderStack doesn’t deliver any other event type to it. See Send events to Salesforce in cloud mode.

Authentication

RudderStack signs in as a Salesforce user through the OAuth 2.0 username-password flow, which your org must allow. It sends password with initial_access_token appended, as Salesforce expects for API sign-ins. See Connection settings.

user_name

RequiredSecret

Type: string

Description: Username of the Salesforce user RudderStack signs in as.

Notes:

At most 100 characters, and must not contain line breaks.
A {{ path || fallback }} template is accepted in place of a literal.

Supply it as a {{ .VAR }} reference rather than a literal — see Secrets.

password

RequiredSecret

Type: string

Description: Password of that user.

Notes:

At most 100 characters, and must not contain line breaks.

Supply it as a {{ .VAR }} reference rather than a literal — see Secrets.

initial_access_token

RequiredSecret

Type: string

Description: The user’s Salesforce security token.

Notes:

At most 100 characters, and must not contain line breaks.
A spec that omits this key fails validation with 'initial_access_token' is required.

Despite its name, this key holds the user’s security token — the dashboard calls it Security Token — not an OAuth access token. Salesforce issues it to the user, and RudderStack appends it to password to sign in.

Supply it as a {{ .VAR }} reference rather than a literal — see Secrets.

sandbox

Type: boolean

Default value: false

Description: Sign in to a Salesforce sandbox through test.salesforce.com instead of a production org through login.salesforce.com. The dashboard calls it Sandbox mode.

Developer instances aren’t supported — see Does RudderStack support dev instances of Salesforce?.

Record mapping

Without an external ID naming a Salesforce object, RudderStack looks the lead up by the event’s email and updates it, or creates a lead when none matches. An identify event without an email then fails. See Update Salesforce objects.

map_properties

Type: boolean

Default value: true

Description: Map traits onto standard Lead and Contact fields, such as firstName to FirstName, and send other traits to custom fields named after them with a __c suffix. Other Salesforce objects receive traits as they are. The dashboard calls it Map Rudder Properties to Salesforce Properties.

RudderStack doesn’t read this key for this destination, and always maps. Setting map_properties to false has no effect.

See Update custom fields and Supported mappings.

use_contact_id

Type: boolean

Default value: false

Description: When the lead matching the event’s email has been converted, update the contact it was converted to instead of the lead. The dashboard calls it Use contactId for converted leads, and suggests turning it on when your lead and contact field mappings are the same.

Per-source keys

Both keys are objects keyed by the local source type — the tokens listed under Source types. A key naming a source type this destination doesn’t support fails validation.

connection_mode

Type: object

Description: Maps each source type you connect to the mode its events reach Salesforce in, using the modes in Source types.

Notes:

An entry is required for each source type you connect — see Connect a source.

yaml

connection_mode:
  web: cloud
  cloud: cloud

consent_management

Type: object

Description: Consent provider configuration per source type. The entry shape, accepted providers, and the rules on resolution_strategy and consents are shared across all destination types — see Consent management.

Source types

Salesforce accepts events from these source types in the mentioned connection modes:

Source type	Connection mode
`android`	`cloud`
`android_kotlin`	`cloud`
`ios`	`cloud`
`ios_swift`	`cloud`
`web`	`cloud`
`unity`	`cloud`
`react_native`	`cloud`
`flutter`	`cloud`
`cordova`	`cloud`
`cloud`	`cloud`
`warehouse`	`cloud`

Every source type is cloud only — events reach Salesforce from RudderStack’s servers, never in device mode.

warehouse is the token a Reverse ETL source resolves to. Rudder CLI manages the destination’s warehouse entry — if the destination is connected to a Reverse ETL source, set connection_mode.warehouse: cloud in its spec, or apply removes it.

Rudder CLI can also declare the Reverse ETL connection itself, for the types listed under Supported destinations — see Manage Reverse ETL Connections using Rudder CLI.

The dashboard additionally offers Salesforce to AMP and Shopify sources. Rudder CLI doesn’t manage those connections, so amp and shopify are invalid here.

Connect a source

An event stream connection to this destination is checked against two rules at validate time.

The source’s type must be supported. A source’s type resolves to one of the tokens above before the check — a JavaScript source resolves to web, and webhook and server-side SDK sources resolve to cloud. Every type an event stream source can resolve to is supported here, so this check always passes.

The destination config must carry a connection_mode entry for that source type. This lives on the destination spec, not on the connection spec. Without it:

destination 'salesforce-prod' config has no 'connection_mode' entry for source type 'web'

Salesforce needs no additional config keys to connect a source of any type.

Secrets

user_name, password, and initial_access_token are the secret keys. Write each as a {{ .VAR }} reference and supply the value at apply time:

yaml

config:
  user_name: "{{ .SALESFORCE_USER_NAME }}"
  password: "{{ .SALESFORCE_PASSWORD }}"
  initial_access_token: "{{ .SALESFORCE_SECURITY_TOKEN }}"

bash

export RUDDER_SALESFORCE_USER_NAME="..."
export RUDDER_SALESFORCE_PASSWORD="..."
export RUDDER_SALESFORCE_SECURITY_TOKEN="..."
rudder-cli apply

# or
rudder-cli apply --var-file secrets.vars.yaml

Note that:

rudder-cli import writes only the secrets the API returns, as {{ .VAR }} references, and leaves the others out. Add any secret key it leaves out, then supply the variables before you apply — see Secrets.

See How to Use Variable Substitution in Rudder CLI.

Changes by release

No changes since this type became available.

For changes across every destination type, see Destination Type Changes by Release.

See more

Salesforce Setup Guide for the API user, the username-password flow, and supported editions
Destination Type Reference for Rudder CLI for the rules shared across destination types
Destination YAML Reference for the spec envelope

Salesforce Destination Config Reference

Sample configuration

Config keys

Authentication

Record mapping

Per-source keys

Source types

Connect a source

Secrets

Changes by release

See more

Questions? Let's figure it out together.