Salesforce Docs Portal

Define an External Data Source for Salesforce Connect Cross-Org Adapter

Set up a connection from your subscriber org to another Salesforce org so your users can access its data through external objects.

Required Editions

Available in: both Salesforce Classic and Lightning Experience (not for high-data-volume external objects)

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
  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
    Exernal Data Source

    A user-friendly name for the external data source. The label appears 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: Cross-Org.
    Connect to Determines which URL is used to connect to the provider org.
    URL If you selected Connect to Custom URL, enter the login URL for the provider org.
    API Version Select an API version that the provider org supports. The API version determines which of the provider org’s objects, fields, and types you can access from the subscriber org.
    Connection Timeout (seconds) Number of seconds to wait for a response from the provider org before timing out. By default, the value is set to the maximum of 120 seconds.
    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.
    Enable Search

    Determines whether global searches in the subscriber org also search the external objects’ data, which is stored in the provider org.

    When selected, you can control which external objects are searchable by selecting or deselecting Allow Search on each external object.

    Only text, text area, and long text area fields on external objects can be searched. If an external object has no searchable fields, searches on that object return no records.
  4. Select the authentication method, which specifies how the subscriber org authenticates with the target org. We recommend that you use named credentials for robust and secure authentication.
    • If you select Named Credential, then select the named credential to use in the Named Credential field.
    • If you select Legacy, then select the Identity Type. The identity type determines whether the subscriber org uses one set or multiple sets of credentials to access the provider org. See Identity Type for External Data Sources.
  5. If you selected Legacy, select the authentication protocol.
    • If you select Password Authentication, enter the username and password to access the external system.
    • If you select OAuth 2.0, complete these fields.
    Field Description
    Authentication Provider Select a Salesforce authentication provider. See Configure a Salesforce Authentication Provider. On a production org, an external data source can’t use an authentication provider that directs authorization or token requests to a sandbox org. Similarly, on a sandbox org, an external data source can’t use an authentication provider that directs authorization or token requests to a production org.
    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 page.
    • 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.
  6. Click Save.
  7. Click Validate and Sync, and confirm that the connection is successful.
    • If you receive an error message, refer to these resources: “Status Codes and Error Responses” in the REST API Developer Guide, and the “API Fault Element,” “ExceptionCode,” “Error,” and “StatusCode” sections of “Core Data Types Used in API Calls” in the SOAP API Developer Guide.
    • Starting in Winter ’26 (API version 65.0), the SOAP API login() method is disabled by default in new orgs. If you encounter an INVALID_OPERATION error while using password authentication, use API version 64.0 or earlier and manually enable the SOAP API login() in Setup to resolve it. See login().
  8. 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 Review these considerations before syncing.
    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