Define an External Data Source for Salesforce Connect—OData 2.0 or 4.0 Adapter
Connect your Salesforce org to data that’s stored in an external system, such as SAP® NetWeaver Gateway, Microsoft Dynamics® NAV, or IBM WebSphere®.
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 |
- The external data must be exposed by a service that uses Open Data Protocol (OData) Version 2.0 or 4.0. Such a service is called an OData producer.
- The URL for reaching the OData producer must be accessible by Salesforce application servers through the Internet. You can access by adding Salesforce server IP addresses on your corporate network firewall to the allow list or by setting up a reverse-proxy XML Gateway.
- The extent to which you can customize data visibility depends on the external system. To determine the optimal settings for integration with Salesforce, consult the external system’s documentation.
- From Setup, enter External Data Sources in the Quick Find box, then select External Data Sources.
- Click New External Data Source, or click Edit to modify an existing external data source.
-
Complete the fields.
Field Description External Data Source 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: OData 2.0 or Salesforce Connect: OData 4.0. URL The OData service root URL. Make sure that you escape all special characters.
Each service endpoint requires its own external data source definition, but you can have multiple entities under one service root URL. For more information about the service root URL and other URL conventions, go to www.odata.org.
Examples:
- http://services.example.org/Warehouse.svc
- https://services.example.org/Payroll.svc
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.If you enter a named credential URL, skip the Authentication section for the external data source. To access the external system, Salesforce Connect uses the authentication settings that are defined in the named credential.
Connection Timeout Number of seconds to wait for a response from the external system before timing out. By default, the value is set to the maximum of 120 seconds.
Depending on the availability of and the connection to the external system, it can take a long time to retrieve external data. Use this field to limit how long to wait for external data to load into your org.
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—OData 2.0 and 4.0 Adapters.
High-data-volume external data sources are still limited to 20,000 OData queries per hour for Enterprise, Performance, and Unlimited Editions. If you require higher limits, create a support case. See callout limits in General Limits for Salesforce Connect OData Adapters.
Server Driven Pagination It's common for Salesforce Connect queries of external data to have a large result set that's broken into smaller batches or pages. To have the external system control the paging behavior, select this option. See Client-Driven and Server-Driven Paging for Salesforce Connect OData Adapters. Request Row Counts Includes one of the following system query options in each OData query so that the response includes the total row count of the result set.
$inlinecount=allpagesfor the OData 2.0 adapter$count=truefor the OData 4.0 adapter
Some external systems don’t support these system query options. If you receive errors or notice long load times when you try to access their data, deselect Request Row Counts on the external data source. If you do so, however, the external data source and its associated external objects can’t support the following functionality, which requires the total row count.
- SOQL
COUNT()aggregate function - Batch Apex with
Database.QueryLocator
Compress Requests When selected, Salesforce sends compressed HTTP requests to the external system. Make sure that the external system is set up to receive gzip-compressed data. Salesforce automatically accepts gzip-compressed responses. Enable Search Determines whether SOSL and Salesforce global searches also query the external objects that are associated with this external data source.
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.
To allow the external data source’s associated external objects to appear in Salesforce for iOS and Salesforce mobile web when used on iOS devices, select this option.
Custom Query Option for Salesforce Search Available only for the OData 2.0 adapter for Salesforce Connect. If the OData producer has implemented and exposed a free-text-search custom query option, enter the name of that query string parameter.
Learn more about OData custom query options and other URI conventions at www.odata.org.
This field has no effect when Enable Search is deselected or when the OData producer isn’t set up to correctly handle the custom query option.
Use Free-Text Search Expressions Available for the OData 4.0 and 4.01 adapters for Salesforce Connect. To use the
$searchsystem query option instead of$filterin search requests that are sent to the external system, select this option. Make sure that the OData producer is set up to support the$searchsystem query option.This field has no effect when Enable Search is deselected.
Format The format that the OData producer uses to represent resources, such as collections of data.
Make sure that the OData producer is set up to support the selected format. Learn more about representation formats and operations at www.odata.org.
If your external data source uses the OData 4.0 adapter and JSON format, make sure that the OData producer accepts headers that contain the
odata.metadata=fullformat parameter. Other variations, includingodata.metadata=minimal, aren’t supported for the OData 4.0 adapter.Special Compatibility Select Socrata only if the URL specifies a Socrata open data endpoint. See Socrata™ Considerations for Salesforce Connect—OData 2.0 and 4.0 Adapters. Display Server Errors Specify whether to display error messages from an external system in the user interface. Eligible for External Change Data Capture Select to track changes to external data. See Use External Change Data Capture to Track Data Changes on External Objects. CSRF Protection If the external system requires Cross-Site Request Forgery (CSRF) protection in requests to create, edit or delete its data, select this option. If you do so, your org obtains an anti-CSRF token and cookie from the external system and includes them in each create, edit, and delete request. See CSRF Considerations for Salesforce Connect—OData 2.0 and 4.0 Adapters.
Available only when Writable External Objects is selected.
Anti-CSRF Token Name HTTP header field that contains the anti-CSRF token. The external system determines the field name. Default: X-CSRF-Token
Available only when CSRF Protection is selected.
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. 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.
Select Anonymous only if the external system doesn’t require authentication.
-
Select the authentication protocol.
- If you select Password Authentication, enter the username and password for accessing the external system.
- If you select OAuth 2.0, complete these fields.
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.
- Click Save.
- Click Validate and Sync, and confirm that the connection is successful.
-
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.
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.Note Before you sync, make sure that you understand the considerations that are described in these topics.
Optionally, you can associate custom HTTP headers to the external data source to retrieve or request additional data.
