ExternalDataSource | Metadata API Developer Guide

This type extends the Metadata metadata type and inherits its fullName field.

File Suffix and Directory Location

ExternalDataSource components are stored in the dataSources directory of the corresponding package directory. ExternalDataSource components have the suffix .dataSource, and the prefix is the name of the external data source.

Version

ExternalDataSource components are available in API version 28.0 and later.

Fields

Field Name	Field Type	Description
authProvider	string	The authentication provider represented by the AuthProvider component.
certificate	string	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.
customConfiguration	string	A string of configuration parameters that are specific to the external data source’s type. customConfiguration for Salesforce Connect—Cross-Org Adapter customConfiguration for Salesforce Connect—OData 2.0 or 4.0 Adapter customConfiguration for Salesforce Connect—Custom Adapter
customHttpHeader	CustomHttpHeader[]	Represents custom HTTP headers used with OData 2.0 or OData 4.0 connectors. Available in API version 43.0 or later.
endpoint	string	The URL of the external system, or if that URL is defined in a named credential, the named credential URL. Corresponds to URL in the user interface. 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`.
isWritable	boolean	Lets the Lightning platform and users in this org 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. Corresponds to Writable External Objects in the user interface. Available in API version 35.0 and later. However, with the cross-org adapter for Salesforce Connect, you can set this field to `true` only in API version 39.0 and later.
label	string	A user-friendly name for the external data source. The label is displayed in the Salesforce user interface, such as in list views. Examples include Acme Team Marketing Site, or Acme SharePoint.
oauthRefreshToken	string	The OAuth refresh token. Used to obtain a new access token for an end user when a token expires.
oauthScope	string	Specifies the scope of permissions to request for the access token. Corresponds to Scope in the user interface.
oauthToken	string	The access token issued by the external system.
password	string	The password to be used by your org to access the external system. Ensure that the credentials you use have adequate privileges to access the external system, perform searches, return data, and return information about the external system’s metadata.
principalType	`ExternalPrincipalType` (enumeration of type string)	Determines whether you're using one set or multiple sets of credentials to access the external system. Corresponds to Identity Type in the user interface. The valid values are: `Anonymous` `PerUser` `NamedUser`
protocol	`AuthenticationProtocol` (enumeration of type string)	The authentication protocol that’s required to access the external system. The valid values are: `NoAuthentication` `Oauth` `Password` For cloud-based Files Connect external systems, select Oauth 2.0. For on-premises systems, select Password Authentication. For Simple URL data sources, select No Authentication.
repository	string	Used for SharePoint Online. If metadata is not accessible, use this field to create tables and default table fields.
type	`ExternalDataSourceType` (enumeration of type string)	For Salesforce Connect, specifies the adapter that connects to the external system. The valid values are: `OData`—OData 2.0 adapter `OData4`—OData 4.0 adapter `SfdcOrg`—cross-org adapter `ApexClassId`—`DataSource.Provider` class that defines the custom adapter created via the Apex Connector Framework For Files Connect, specifies the data source type. The valid values are: `ContentHubSharepoint`—SharePoint 2010 or 2013 `ContentHubSharepointOffice365`—SharePoint Online `ContentHubSharepointOneDrive`—OneDrive for Business `ContentHubGDrive`—Google Drive If Chatter is enabled, you can also specify `SimpleURL` to access data hosted on a web server that doesn’t require authentication. `outgoingemail`—A data source used for sending an email through a quick action. The `Identity` and `Wrapper` types are reserved for future use. For the federated search external data source type, the valid value is `OpenSearch`.
username	string	The username to be used by your org to access the external system. Ensure that the credentials you use have adequate privileges to access the external system, perform searches, return data, and return information about the external system’s metadata.
version	string	Reserved for future use.

CustomHttpHeader

Represents a custom HTTP header used with OData 2.0 or OData 4.0 connectors. Available in API version 43.0 or later.

Field Name	Field Type	Description
description	string	Description of the custom HTTP header.
headerFieldName	string	Required. Name of the custom HTTP header field.
headerFieldValue	string	Required. Value of the custom HTTP header field derived from a formula.
isActive	boolean	Specifies whether the custom HTTP header field is active (`true`) or inactive (`false`).

customConfiguration for Salesforce Connect—Cross-Org Adapter

The following sample JSON-encoded configuration string defines parameters that apply when the external data source’s type is set to SfdcOrg.

1{"apiVersion":"32.0","environment":"CUSTOM",
2"searchEnabled":"true","timeout":"120"}

The parameters correspond to these fields in the user interface:

apiVersion—API Version
environment—Connect to
searchEnabled—Enable Search
timeout—Connection Timeout

customConfiguration for Salesforce Connect—OData 2.0 or 4.0 Adapter

The following JSON-encoded configuration string defines parameters that apply when the external data source’s type is set to OData or OData4.

1{"inlineCountEnabled":"true","csrfTokenName":"X-CSRF-Token",
2"requestCompression":"false","pagination":"CLIENT",
3"noIdMapping":"false","format":"ATOM",
4"searchFunc":"","compatibility":"DEFAULT",
5"csrfTokenEnabled":"true","timeout":"120",
6"searchEnabled":"true"}

The parameters correspond to these fields in the user interface.

compatibility—Special Compatibility
csrfTokenEnabled—CSRF Protection
csrfTokenName—Anti-CSRF Token Name
format—Format
inlineCountEnabled—Request Row Counts
noIdMapping—High Data Volume
pagination—Server Driven Pagination
requestCompression—Compress Requests
searchEnabled—Enable Search
searchFunc—Custom Query Option for Salesforce Search
timeout—Connection Timeout

customConfiguration for Salesforce Connect—Custom Adapter

The following sample JSON-encoded configuration string defines the parameter that applies when the external data source’s type is set to the ID of a DataSource.Provider class.

1{"noIdMapping":"false"}

The noIdMapping parameter corresponds to the High Data Volume field in the user interface.

Declarative Metadata Sample Definition

The following is the definition of an external data source for Salesforce Connect—OData 2.0 or 4.0 adapter.

1<?xml version="1.0" encoding="UTF-8"?>
2<ExternalDataSource xmlns="http://soap.sforce.com/2006/04/metadata">
3    <authProvider>FacebookAuth</authProvider>
4    <customConfiguration>{"compatibility":"DEFAULT",
5    "noIdMapping":"false","inlineCountEnabled":"true",
6    "searchEnabled":"true","format":"ATOM",
7    "requestCompression":"false","pagination":"SERVER",
8    "timeout":"120"}</customConfiguration>
9    <customHttpHeaders>
10        <headerFieldName>X-User</headerFieldName>
11        <headerFieldValue>$User.Username</headerFieldValue>
12    </customHttpHeaders>
13    <endpoint>http://myappname.herokuapp.com/DataHub.svc</endpoint>   
14    <label>DataHub</label>
15    <principalType>NamedUser</principalType>
16    <protocol>Oauth</protocol>
17    <type>OData</type>
18</ExternalDataSource>

Wildcard Support in the Manifest File

This metadata type supports the wildcard character * (asterisk) in the package.xml manifest file. For information about using the manifest file, see Deploying and Retrieving Metadata with the Zip File.