Salesforce Docs Portal

Define an External Data Source for Salesforce Connect—Custom Adapter

Connect your Salesforce org to any data anywhere via a Salesforce Connect custom adapter that you create with the Apex Connector Framework.

Required Editions

Available in: both Salesforce Classic and Lightning Experience

Available in: Developer Edition

Available for an extra cost in: Enterprise, Performance, and Unlimited Editions

User Permissions Needed
To create and edit external data sources: Customize Application

Before you begin, develop the custom adapter for Salesforce Connect. If the custom adapter uses Apex callouts, also define remote sites for the callout endpoints. See Set Up Salesforce Connect to Access External Data with a Custom Adapter.

  1. From Setup, enter External Data Sources in the Quick Find box, then select External Data Sources.
  2. Click New External Data Source, or click Edit to modify an existing external data source.
  3. Complete the fields.
    Field Description
    Label

    A user-friendly name for the external data source. The label is displayed in the Salesforce user interface, such as in list views.

    If you set Identity Type to Per User, this label appears when your users view or edit their authentication settings for external systems.

    Name

    A unique identifier that’s used to refer to this external data source definition through the API.

    The name can contain only underscores and alphanumeric characters. It must be unique, begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.
    Type

    Select Salesforce Connect: Custom—<your DataSource.Provider class name>.

    If you change and save a DataSource.Connection class, resave the corresponding DataSource.Provider class. Otherwise, when you define the external data source, the custom adapter doesn’t appear as an option for the Type field.

    URL

    URL of the external system.

    Available only when the DataSource.Provider class declares the REQUIRE_ENDPOINT capability. If the class also declares the REQUIRE_HTTPS capability, the URL must begin with https://.

    If the endpoint is defined in a named credential, enter the named credential URL. A named credential URL contains the scheme callout:, the name of the named credential, and an optional path. For example: callout:My_Named_Credential/some_path.

    You can append a query string to a named credential URL. Use a question mark (?) as the separator between the named credential URL and the query string. For example: callout:My_Named_Credential/some_path?format=json.
    Writable External Objects The Lightning Platform and users in this org can create, update, and delete records for external objects associated with the external data source. The external object data is stored outside the org. By default, external objects are read only.
    High Data Volume Salesforce enforces rate limits for retrieving and viewing data from external systems. If your org hits rate limits when accessing external objects, consider selecting the High Data Volume option on the associated external data sources. Doing so bypasses most rate limits, but some special behaviors and limitations apply. See High Data Volume Considerations for Salesforce Connect—Custom Adapters.
    Certificate

    If you specify a certificate, your Salesforce org supplies it when establishing each two-way SSL connection with the external system. The certificate is used for digital signatures, which verify that requests are coming from your Salesforce org.

    Available only when the DataSource.Provider class declares the CERTIFICATE authentication capability.

    Identity Type

    Determines whether you're using one set or multiple sets of credentials to access the external system. See Identity Type for External Data Sources.

    Available only when the DataSource.Provider class declares the BASIC or OAUTH authentication capability.

  4. Select the authentication protocol.
    • If you select Password Authentication, enter the username and password for accessing the external system.

      Password authentication is available only when the DataSource.Provider class declares the BASIC authentication capability.

    • If you select OAuth 2.0, complete the following fields.

      OAuth 2.0 is available only when the DataSource.Provider class declares the OAUTH authentication capability.

    Field Description
    Authentication Provider Choose the provider. See Authentication Providers.
    Scope

    Specifies the scope of permissions to request for the access token. Your authentication provider determines the allowed values. See Use the Scope Parameter.

    Keep these considerations in mind when you set a scope.

    • The value that you enter replaces the Default Scopes value that’s defined in the specified authentication provider.
    • Whether scopes are defined can affect whether each OAuth flow prompts the user with a consent screen.
    • We recommend that you request a refresh token or offline access. Otherwise, when the token expires, you lose access to the external system.
    Start Authentication Flow on Save

    To authenticate to the external system and obtain an OAuth token, select this checkbox. This authentication process is called an OAuth flow.

    When you click Save, the external system prompts you to log in. After successful login, the external system grants you an OAuth token for accessing its data from this org.

    Redo the OAuth flow when you need a new token—for example, if the token expires—or if you edit the Scope or Authentication Provider fields. When the token expires, the external system returns a 401 HTTP error status.

  5. Click Save.
  6. Click Validate and Sync, and confirm that the connection is successful.
    This step also invokes the sync() method on the DataSource.Connection class to obtain the list of tables that you can sync to create external objects and their fields.
  7. Optionally, select tables and click Sync to do the following for each selected table.
    • Automatically create a Salesforce external object.
    • Automatically create a custom field for each table column that’s compatible with a Salesforce metadata field type.
    Note
    Note Before you sync, make sure that you understand the considerations that are described in these topics.
    You can instead choose to manually create the external objects and custom fields that map to the external data. Doing so lets you customize the external object names, decide which table columns to create custom fields for, and customize the custom field names. However, this approach takes longer and requires manual maintenance.

See Also