Metadata API Developer Guide
jNewer Version Available
ExternalDataSource
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.
Special Access Rules
As of Spring ’20 and later, only authenticated internal and external users can access this type.
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. |
| customHttpHeaders | CustomHttpHeaders[] | 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. |
| externalDataSrcDescriptors | ExternalDataSrcDescriptors[] | Represents schema descriptors for an external data source used with Salesforce Connect adapter for Amazon DynamoDB (available in API version 55.0 or later) or Amazon Athena (available in API version 56.0 or later). |
| 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. |
| namedCredential | string | Represents the definition of the referenced named credential for an external data source of the type Amazon DynamoDB or Amazon Athena. |
| 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:
|
| protocol | AuthenticationProtocol (enumeration of type string) | The authentication protocol that’s required to access the external system. The
valid values are:
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) | Required. For Salesforce Connect, specifies the adapter that connects to the
external system. The valid values are:
For Files Connect, specifies the data source type. The valid values are:
If Chatter is enabled, you can also specify SimpleURL to access data hosted on a web server that doesn’t require authentication. 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. |
CustomHttpHeaders
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 | A text description of the header field’s purpose. |
| headerFieldName | string | Required. Name of the header field. The name must contain at least one alphanumeric character or underscore. It can also include: ! # $ % & ' * + - . ^ _ ` | ~ |
| headerFieldValue | string | Required. A formula that resolves to the value for the header. The values in the formula must evaluate to a string. If the formula resolves to null and an empty string, the header isn’t sent. |
| isActive | boolean | Indicates whether the custom HTTP header is available to use (true) or unavailable (false). |
customConfiguration for Salesforce Connect—Cross-Org Adapter
1{"apiVersion":"32.0","environment":"CUSTOM",
2"searchEnabled":"true","timeout":"120"}- apiVersion—API Version
- environment—Connect to
- searchEnabled—Enable Search
- timeout—Connection Timeout
customConfiguration for Salesforce Connect—OData 2.0 or 4.0 Adapter
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"}- 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
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>customConfiguration for Salesforce Connect—Custom Adapter
1{"noIdMapping":"false"}The noIdMapping parameter corresponds to the High Data Volume field in the user interface.
ExternalDataSrcDescriptors for Salesforce Connect Adapter for Amazon DynamoDB and for Amazon Athena
Represents schema descriptors for an external data source used with Salesforce Connect adapter for Amazon DynamoDB (available in API version 55.0 or later) or Amazon Athena (available in API version 56.0 or later).
| Field Name | Field Type | Description |
|---|---|---|
| customObject | string | If set, the external object associated with the descriptor. |
| descriptor | string | Required. The descriptor document that contains the metadata information. |
| descriptorVersion | string | If the external system supports schema versioning for the data source, the optional descriptor document version tracks the external system's schema version. Several descriptors with different document versions may be active. |
| developerName | string | Required. The unique name of the child-level setup entity. |
| externalDataSource | string | Required. The name of the external data source associated with the descriptor. |
| subtype | ExternalDataSrcDescSubtype (enumeration of type string) | Required. The subtype of the descriptor. Values are:
|
| systemVersion | int | Required. The version that defines the descriptor format and allows compatibility with descriptor formats between Salesforce releases. |
| type | ExternalDataSrcDescType (enumeration of type string) | Required. The type of the descriptor. Valid value:
|
The following is an example of an external data source for the Salesforce Connect adapter for Amazon DynamoDB that uses ExternalDataSrcDescriptor component.
1<?xml version="1.0" encoding="UTF-8"?>
2<ExternalDataSource xmlns="http://soap.sforce.com/2006/04/metadata">
3 <customConfiguration>{"timeout":"120"}</customConfiguration>
4 <externalDataSrcDescriptors>
5 <fullName>MyQualifierName</fullName>
6 <customObject>MyExternalObject__x</customObject>
7 <descriptor>
8 {
9 "tableName": "MyDynamoDBTable",
10 "columns": {
11 "MyField": {"presence": "exists"}
12 }
13 }
14 </descriptor>
15 <developerName>MyQualifierName</developerName>
16 <externalDataSource>MyDataSource</externalDataSource>
17 <subtype>SchemaTableQualifiers</subtype>
18 <systemVersion>0</systemVersion>
19 <type>Schema</type>
20 </externalDataSrcDescriptors>
21 <isWritable>true</isWritable>
22 <label>MyDataSource</label>
23 <namedCredential>MyNamedCredential</namedCredential>
24 <principalType>Anonymous</principalType>
25 <protocol>NoAuthentication</protocol>
26 <type>AmazonDynamoDb</type>
27</ExternalDataSource>The following is an example of an external data source for the Salesforce Connect adapter for Amazon Athena that uses ExternalDataSrcDescriptor component.
1<?xml version="1.0" encoding="UTF-8"?>
2<ExternalDataSource xmlns="http://soap.sforce.com/2006/04/metadata">
3 <customConfiguration>
4 {
5 "DataCatalog": "AwsDataCatalog",
6 "timeout": "120"
7 }
8 </customConfiguration>
9 <externalDataSrcDescriptors>
10 <fullName>MyAthenaQualifierName</fullName>
11 <customObject>MyAthenaExternalObject__x</customObject>
12 <descriptor>
13 {
14 "tableName": "myathenadatabase.myathenatable",
15 "extendedQualifiers": {"workgroup": "primary"},
16 "keyColumns": ["ExternalIdComponent", "OtherExternalIdComponent"]
17 }
18 </descriptor>
19 <developerName>MyAthenaQualifierName</developerName>
20 <externalDataSource>MyAthenaDataSource</externalDataSource>
21 <subtype>SchemaTableQualifiers</subtype>
22 <systemVersion>0</systemVersion>
23 <type>Schema</type>
24 </externalDataSrcDescriptors>
25 <isWritable>false</isWritable>
26 <label>MyAthenaDataSource</label>
27 <namedCredential>MyAthenaNamedCredential</namedCredential>
28 <principalType>Anonymous</principalType>
29 <protocol>NoAuthentication</protocol>
30 <type>AmazonAthena</type>
31</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.