Data Federation API Developer Guide - Salesforce

Data Federation API DeveloperGuide

Version 54.0, Spring ’22

@salesforcedocsLast updated: February 24, 2022

https://twitter.com/salesforcedocs

© Copyright 2000–2022 salesforce.com, inc. All rights reserved. Salesforce is a registered trademark of salesforce.com, inc.,as are other names and marks. Other marks appearing herein may be trademarks of their respective owners.

CONTENTS

Chapter 1: Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Data Federation API FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Call the DFS Named Credential . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Chapter 2: Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Metadata Repository Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Query Dialects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Queryable Schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 3: Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Request Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Request Case Data for User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Chapter 4: Status Codes and Error Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Chapter 5: Troubleshooting Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

CHAPTER 1 Quick Start

Get started with the Data Federation API.In this chapter ...Use the quick start section to understand the configuration necessary to try examples.• Prerequisites1. Make sure that your Customer 360 Data Manager administrator and Salesforce Org administrators

have completed the appropriate configuration for your component or app.• Data Federation API

FAQ

2. Identify the DF external data source or DF named credential configuration you want to use to issueyour queries.

• Call the DFS NamedCredential

3. Discover the available objects and fields that you can query using the Service resource.

4. Use the Version, Metadata Repository Version, Queryable Schemas, and Query Dialect resources todetermine valid values for the Query Resource.

5. Use the Query resource to issue queries across clouds.

1

Prerequisites

Complete these prerequisites before you begin the quick start.

You must have an org that has Customer 360 Data Manager provisioned to be able to use the API. The API is not available in free DeveloperEdition orgs.

In Customer 360 Data Manager:

• The data sources you want to query must be connected to Customer 360 Data Manager.

• The entities and attributes you want to query must be mapped in both the data source querying for information and the data sourcebeing queried.

In the Salesforce orgs you connect:

• The integration managed permission set must be enabled and the objects you want to query must allow access.

Become familiar with:

• SOQL, which is the query language used in the API.

• JavaScript Object Notation (JSON), which is the data format returned in the query response.

• EDMX, which is the schema notation returned in the metadata response.

• OData, which is a REST API open standard implemented by the Data Federation Service API (DFS API).

Data Federation API FAQ

Learn the answers to frequently asked questions about the Data Federation API.

What Is the Data Federation API (DF API)?The Data Federation API is an OData REST API that enables clients to execute federated queries against queryable data models. The DFAPI reduces the complexity of retrieving data across clouds and orgs, as one query can return data from all of your data sources. DataFederation API queries are written against the Cloud Information Model (CIM) that all data sources are mapped to.

What Do I Use the Data Federation API For?Use the DF API to build reports and components with easy access to data across multiple data sources in a single federated query.

What Do I Need to Do to Make a Data Federation API Query?Create the DFS named credential and call it using an Apex callout. Consult your Customer 360 Admin to make sure they have completedthe other tasks required for the integration experience you want to enable. These include connecting data sources and mapping entities.See the Multi-Org Checklist and the examples on page 18 for more information.

How Do I Discover Valid Query Parameter Values?The DF API has multiple resources to help you discover valid values for URI parameters. Basic query operations are documented in theQuery resource. Any OData syntax not documented is not supported.

2

PrerequisitesQuick Start

https://help.salesforce.com/articleView?id=c360exp_multi_org_checklist.htm&type=5&language=en_US

How Do I Filter on Query Parameters and What Are the Limitations on QueryFilters?Basic OData 4.0 filters are supported for any data source. Some data sources allow nested $expand query filters.

What Information Does Data Federation API Retrieve?It returns 25 records from the full data set, in undetermined order. If you have many results, Salesforce recommends querying on globalprofile ID, as it significantly filters and improves the quality of results.

Do I Have to Use the Global Party ID in My Query?When you want to query across relationships, both entities in the relationship need a global profile ID. If you are directly querying anentity, then a global profile ID is not required for a query to be successful.

How Do I Control How the Query Results Are Returned and PaginateThrough Them?You can use the query parameters to sort or limit results. Since DF API returns a maximum of 25 records, pagination features are notneeded.

How Do I Query Across Objects?If you use the Global Party ID (GPID) as a filter parameter, DF API queries account, contact, and lead objects mapped to the Individualentity.

Does DF API Provide Canonical IDsThe DF API automatically prefixes the data source ID to the primary key of any records that are returned from a Salesforce Org.

No key is prefixed for records returned from B2C Commerce instances. Parse the primary key to remove the prefixed data source ID. Thendisplay the primary key for a record or use it to create a record in your org.

You can use the prefixed data source ID to display information about the origin of the record. Record origin can be useful if your orgsare separated geographically or by business unit.

If My External Object Validation Fails, Will My Queries Work?Yes! External objects that are associated with DFS external data sources can’t be validated via the standard external object validationprocess. Run a simple query to test it if you want to check that the objects are available to query.

SEE ALSO:

Query

3

Data Federation API FAQQuick Start

Call the DFS Named Credential

USER PERMISSIONS

API Enabled AND View All DataTo use the Developer Console:

View All DataTo view, retain, and delete debug logs:

Author ApexTo execute anonymous Apex:

API EnabledTo use code search and run SOQL or SOSL on the query tab:

Author ApexTo save changes to Apex classes and triggers:

Customize ApplicationTo save changes to Visualforce pages and components:

Customize ApplicationTo save changes to Lightning resources:

Quick example of how to call the DFS named credential as an Apex callout.

For this task to be successful:

• Both the org where you issue the query and the org or cloud that you want to query are connected to Customer 360 Data Manageras data sources.

• The C360 Data Manager Integration perm set is configured to allow access to any objects you want to query for all connectedSalesforce Orgs.

• You have accepted the default mappings for both data sources or mapped the same entities and attributes as the default mappings.

• You have configured the DFS Named Credential.

• You have connected a Commerce Cloud instance as a data source that has a working site with order data.

Note: Replace SiteGenesis in the example with the name of your site.

This is a simple way to get started with the DFS named credential, if you want a quick way to try out the API and haven’t developed withnamed credentials before.

1.Click the quick access menu ( ).

2. Click Developer Console.

3. Click Debug.

4. Click Open Execute Anonymous Window.

5. Check Open Log.

6. Enter the following code and click Execute.

Http http = new Http();HttpRequest request = new HttpRequest();String queryTest ='SalesOrder?$filter=OrderNumber%20eq%20%27SiteGenesis__00000202%27&$select=GrandTotalAmount,OrderNumber';request.setEndpoint('callout:DFS/'+queryTest);request.setMethod('GET');HttpResponse response = http.send(request);System.debug(response.getBody());

4

Call the DFS Named CredentialQuick Start

You can see what this returns in the log.

5

Call the DFS Named CredentialQuick Start

CHAPTER 2 Resources

Resources available for the Data Federation API.In this chapter ...Available resources:• Metadata

DescriptionResource• Metadata RepositoryVersion

/dfs/apiVersion/metadataRepository/repositoryVersion/$metadata

Returns an EDMX document for a data source, indicating all queryable entitiesand attributes.

Metadata on page7

• Query

• Query Dialects

• Queryable Schemas

• Service/dfs/apiVersion/metadataRepository/

Gets the available metadata versions.

MetadataRepository Versionon page 8

• Version

/dfs/api_version/metadataRepository/repositoryVersion/queryableSchema/queryDialect

Gets the available query dialects for a queryable schema.

Query Dialect onpage 12

/dfs/api_version/metadataRepository/repositoryVersion/queryableSchema/queryDialect/queryRequest

Executes a query.

Query on page 10

/dfs/api_version/metadataRepository/repositoryVersion/queryableSchema

Gets the available queryable schemas.

Queryable Schemason page 14

/dfs/apiVersion/metadataRepository/repositoryVersion/entity?$select=query

Returns a JSON document listing the queryable entities exposed by the DFS APIfor the metadata repository and repository version. The results are the top-levelentities that can be queried using the Query resource.

Service on page 15

/dfs/apiVersion

Executes a query.

Version on page 17

6

Metadata

Get a document that lists the entities and attributes that the DF API recognizes. DF API recognizes supported top-level CIM entities andentities that are accessible through an OData $expand expression.

Use the metadata resource to return an EDMX document that contains the entities and attributes that the DF API recognizes.

The Service document identifies entities that are mapped and therefore can be queried for a specific queryable schema. The differencebetween results from the Metadata resource and Service resource identifies areas where you can add mappings to query more entities.

SyntaxResource

v4.0

/dfs/apiVersion/MetadataRepository/repositoryVersion/queryableSchema/odata/$metadata

v2.0 and v3.0

/dfs/apiVersion/metadataRepository/repositoryVersion/$metadata

Availability2.0

FormatsODATA 4.0

HTTP methodsGET

Authentication

Provided by Salesforce via Cloud to Cloud authentication. The named credential cannot be called directly and must be called viaSalesforce. For example, via the developer console, an Apex resource, or a component.

Request parameters

DescriptionParameter

Required. Version of the DF API to use. The current version is v3.0. This value is takenfrom the named credential configuration.

apiVersion

For example: v3.0

Required. Contact Customer Support for this value. This parameter identifies therepository that stores the mappings for your environment. It is unique per Customer360 Data Manager environment.

metadataRepository

Mapping version activated in Customer 360 Data Manager. Salesforce recommendstaking the value from the configuration of the DFS external data source. Using the

repositoryVersion

metadata for the DFS external data source allows your code to use whatever versionthey have most recently configured.

For example: 1.2.0

7

MetadataResources

ExampleThis gets the queryable entities for a specific version of the mappings in your environment. The results are the same, but the requestsdiffer by the syntax of the API version.

v4.0 example

/dfs/v3.0/core%2fstmfpba44ice1%2f00DRM000000D1or2BC/1.2.0/org1connection/odata/$metadata

v2.0 and 3.0 example

/dfs/v3.0/core%2fstmfpba44ice1%2f00DRM000000D1or2BC/1.2.0/$metadata

Metadata Repository Version

Get the available metadata repository versions.

Use the Metadata Repository Version resource to return available versions of the metadata repository that you can query. The metadatarepository stores the mappings between schema for your Customer 360 Data Manager environment. Use this resource to identifyparameter values for your Query resource.

SyntaxResource

/dfs/apiVersion/metadataRepository

Available since releasev4.0

FormatsOData 4.0

HTTP methodsGET

Authentication

Provided by Salesforce via Cloud to Cloud authentication. This means that the named credential cannot be called directly and mustbe called via Salesforce. For example, via the developer console, an Apex resource, or component.

Request bodyN/A

Request parameters

DescriptionURI Parameter

Version of API syntax to use.apiVersion

For example: v4.0

Optional. Specify a condition to narrow the results returned. Only the EQ operator issupported. However, other operators might work depending on the type of data sourceyou are querying.

metadataRepository

8

Metadata Repository VersionResources


For example: core%2fstmfana44ice1%2f00DRM000000F1or2AC

ExampleThis example queries the available versions of the metadata repository.

Request

/dfs/v4.0/core%2fstmfana44ice1%2f00DRM000000F1or2AC

Response

{"releases": [{"id": "2019-08-26T22:33:03.515594Z","description": "Core Connector Service Org Release"

},{"id": "v2.1","description": "v2.1"

},{"id": "v2.2","description": "created xforms for Service cloud 2"

},{"id": "v2.3","description": "reverted sales order mapping back to default mapping"

},{"id": "v2.4","description": "v2.4 - revert to default order -> salesorder mapping"

},{"id": "v2.4.1","description": "v2.4.1"

},{"id": "v2.4.2","description": "v2.4.2"

}]

}

The query returns:

{"releases": [

{"id":"v1.0","description":"the first release"},{"id":"v1.1","description":"next major change"},{"id":"v2.0","description":"new schema version"}

9

Metadata Repository VersionResources

]}

Query

Get data from another cloud or org via a query.

Use the Query resource to return records from other clouds and orgs.

SyntaxResource

4.0

/dfs/api_version/metadataRepository/repositoryVersion/queryableSchema/queryDialect/queryRequest

3.0

/dfs/apiVersion/metadataRepository/repositoryVersion/entity?$select=query


FormatsOData 4.0

HTTP methodsGET

Authentication


Request bodyN/A

Request parameters



For example: v4.0


metadataRepository


The mapping version to use.repositoryVersion

For example: 2.0.1

10

QueryResources


The queryable schema to use. There are two possible values for queryableSchema: theschema of the org issuing the query or the Cloud Information Model (CIM). The value

queryableSchema

for the org issuing the query is the data source API name that was supplied when theorg was connected to Customer 360 Data Manager. The CIM value is automaticallycreated for your environment and must be retrieved through the Queryable Schemaresource.

For example: Org1Connection

The query dialect to issue the query in.queryDialect

For example: odata;

The query expression used to issue the query. The objects in the query are determinedby the queryable schema selected. The syntax is determined by the specified querydialect.

queryRequest

Query parameters

DescriptionQuery Parameter

Required. Selects data to return. The query selects entities and attributes in the CloudInformation Model (CIM). Data from all data sources that are mapped to those entitiesand attributes are returned.

$select

For example:$select=Id,ExternalRecordId,OrderNumber,GrandTotalAmount


$filter

For example: $filter=ExternalRecordId. The ExternalRecordID is used tofilter on the global party ID.

Optional. Orders returned results. This uses the ODATA orderby operators and syntax.$orderby

Note: If there are more than the maximum 25 results to return, this returns 25results and then orders them, rather than ordering the full data set and thenreturning 25 results.

For example: $orderby=OrderNumber asc

Limits the maximum number of records returned. This must be an integer over 0.$top

For example: $top=5

11

QueryResources

DescriptionQuery Parameter

Only $select is supported as a query parameter in an $expand query. The depthof a nested $expand query that is allowed depends on the data source you arequerying.

$expand

For example:$expand=BillToAddressId($select=AddressLine1,CityName,PostalCodeText,StateProvinceName),SalesOrderProducts($select=OrderedQuantity,Description,ListPriceAmount,LineAdjustmentSubTotalAmount,TotalTaxAmount,TotalLineAmount;

Query Dialects

Get a list of available query dialects for a queryable schema.

Use the Query Dialects resource to return the available query dialects.

SyntaxResource

/dfs/api_version/metadataRepository/repositoryVersion/queryableSchema/


FormatsOData 4.0

HTTP methodsGET

Authentication


Request bodyN/A

Request parameters



For example: v4.0


metadataRepository



For example: 2.0.1

12

Query DialectsResources



queryableSchema



Query parameters


Required. Selects data to return. The query selects entities and attributes in the CloudInformation Model (CIM). Data from all data sources that are mapped to those entitiesand attributes are returned.

$select

For example:$select=Id,ExternalRecordId,OrderNumber,GrandTotalAmount


$filter

For example: $filter=ExternalRecordId. The ExternalRecordID is used tofilter on the global party ID.

Optional. Orders returned results. This uses the ODATA orderby operators and syntax.$orderby

Note: If there are more than the maximum 25 results to return, this returns 25results and then orders them, rather than ordering the full data set and thenreturning 25 results.

For example: $orderby=OrderNumber asc

Limits the maximum number of records returned. This must be an integer over 0.$top

For example: $top=5

Only $select is supported as a query parameter in an $expand query. The depthof a nested $expand query that is allowed depends on the data source you arequerying.

$expand

For example:$expand=BillToAddressId($select=AddressLine1,CityName,PostalCodeText,StateProvinceName),SalesOrderProducts($select=OrderedQuantity,Description,ListPriceAmount,LineAdjustmentSubTotalAmount,TotalTaxAmount,TotalLineAmount;

13

Query DialectsResources

ExampleThis example queries the available query dialects.

Request

dfs/v4.0/core%2fstmfana44ice1%2f00DRM000000F1or2AC/v2.3/org1connection/

Response

{"dialects" : [ {"id" : "odata"

} ]}

Queryable Schemas

Get the queryable schemas available for a specific metadata repository version.

Use the Queryable Schemas resource to return the queryable schemas available for a specific mapping version. Use this resource toidentify values necessary for your Query resource.

SyntaxResource

/dfs/api_version/metadataRepository/repositoryVersion/


FormatsOData 4.0

HTTP methodsGET

Authentication


Request bodyN/A

Request parameters



For example: v4.0

14

Queryable SchemasResources



metadataRepository



For example: 2.0.1

ExampleThis example returns the available queryable schemas.

Request

/dfs/v4.0/core%2fstmfdna44ice1%2f00DRM000000F1or2AC/v2.3

Response

{"schemas" : [ {"id" : "Org1connection"

} ]}

Service

Get a document that lists the top-level entities that you can query.

Use the Service resource to request information about the top-level entities that can be queried. The resource returns an OData servicedocument listing the CIM entities that have mappings in your Customer 360 Data Manager environment.

Any attributes you want to query must be mapped in all connected data sources. Attributes that are not mapped are not returned bythe Metadata resource. If an entity or attribute you want to query is not available, ask your Customer 360 Data Manager admin to mapit.

SyntaxResource

v4.0

/dfs/apiVersion/MetadataRepository/repositoryVersion/queryableSchema/odata

v2.0 and v3.0

/dfs/apiVersion/MetadataRepository/repositoryVersion

Availability2.0

15

ServiceResources

https://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html#sec_ServiceDocument

https://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html#sec_ServiceDocument

FormatsODATA 4.0

HTTP methodsGET

Authentication

Provided by Salesforce via Cloud to Cloud authentication. This means that the named credential cannot be called directly and mustbe called via Salesforce. For example, via the developer console, an Apex resource, or a component.

Request bodyN/A

Request parameters



For example: v4.0


metadataRepository



For example: 2.0.1


queryableSchema



This is the only available query dialect in v4.0.odata

ExampleThis gets the queryable entities for a specific version of the mappings in your environment. The results are the same, but the requestsdiffer by the syntax of the API version.

v4.0 example

/dfs/v3.0/core%2fstmfpba44ice1%2f00DRM000000D1or2BC/1.2.0/org1connection/

v2.0 and 3.0 example

/dfs/v3.0/core%2fstmfpba44ice1%2f00DRM000000D1or2BC/1.2.0/

16

ServiceResources

UsageThis is used to identify if there are any entities you can query. If you don't see the entity you want to query, contact the Customer 360Data Manager and let them know they need to add mappings.

Version

Get the available versions of the Data Federation API.

Use the Version resource to return available versions of the Data Federation API. Use this resource to identify values necessary for yourQuery resource.

SyntaxResource

/dfs/


FormatsOData 4.0

HTTP methodsGET

Authentication

Provided by Salesforce via Cloud to Cloud authentication. The named credential cannot be called directly and must be called viaSalesforce. For example, via the developer console, an Apex resource, or component.

Request bodyN/A

Request parametersN/A

ExampleThis resource gets the available DF API versions.

/dfs/

The resource returns:

{"versions": [{"id":"v2.0"},{"id":"v3.0"},{"id":"v4.0"}

]}

17

VersionResources

CHAPTER 3 Examples

Examples of common ways to use the Data Federation API.In this chapter ...The examples include common ways of using the API for the integration experiences offered by Customer360 Data Manager.

SEE ALSO:

Request Metadata

Request Case Data for User

Troubleshooting Error Codes

• Request Metadata

• Request Case Datafor User

18

Request Metadata

Scenario: AnyFor this example to work as it’s described, C360 Data Manager must have these configurations.

• Data Sources: You must have connected the org you are developing in and the data source you want to query to Customer 360Data Manager.

• Mapping Version: You must have created a 1.0 mapping version.

• Mappings: You must have accepted the default mappings or mapped the equivalent fields.

For this example to work as it’s described, the org you are developing in must have these configurations.

• Named Credential The DFS Named credential must be configured.

ResourceAll

HTTP methodGET

Request path and parameters

dfs_api_version

DFS version 3.0

metadata_repository_key

Unique identifier for a data source mapping version. This example just uses a sample value that looks correct.Note: this value must be URL encoded.

metadata_version

Mapping version name. This doesn’t have to be unique.

Request exampleThis requests a metadata document for a data source. You can use this document to create queries.

base url/dfs/v3.0/mds%2Fstmpa%2FMDS05pBm3yQNwbz/v19r/$metadata

ReturnsReturns an EDMX document describing the queryable entities and attributes.

Request Case Data for User

Scenario: Service + CommerceFor this example to work as it’s described, C360 Data Manager must have these configurations.

• Data Sources: You must have connected the org you are developing in and the data source you want to query to Customer 360Data Manager.

• Mapping Version: You must have created a mapping version.

• Mappings: You must have accepted the default mappings for two orgs or mapped the equivalent fields used in the example.

For this example to work as it’s described, the org you’re developing in must have these configurations.

19

Request MetadataExamples

• Named Credential The DFS Named credential must be configured.

Resourcebaseurl/dfs/v3.0/mds%2Fstmfp%2FMDS05pBm3yQNwbz/v19/Case?$select=CaseNumber,ClosedDateTime,CreatedDate,Description,ExternalRecordId,Id,LastModifiedDate,Subject,SystemModstamp&$expand=CasePriorityId($select=CreatedDate,Id,LastModifiedDate,Name,SystemModstamp),CaseStatusId($select=CreatedDate,Id,LastModifiedDate,Name,SystemModstamp),CaseTypeId($select=CreatedDate,Id,LastModifiedDate,Name,SystemModstamp)&$filter=ExternalRecordIdeq 'GPID-002'&$orderby=CaseNumber

HTTP methodGET

Request parameters

dfs_api_version

DFS version 3.0

metadata_repository_key

Unique identifier for a data source mapping version.

metadata_version

Mapping version name. Replace this with your own mapping version in the example.

Code exampleThis returns the cases associated with an Individual across all mapped data sources.

public class CaseStatusId {public String LastModifiedDate;public String Id;public String SystemModstamp;public String CreatedDate;public String Name;

}

public class CimCase {public String CaseNumber;public String ClosedDateTime;public String CreatedDate;public String Description;public String ExternalRecordId;public String Id;public String LastModifiedDate;public String Subject;public String SystemModstamp;public CaseStatusId CaseStatusId;public CaseStatusId CaseTypeId;public CaseStatusId CasePriorityId;

}

Http http = new Http();HttpRequest request = new HttpRequest();String queryTest ='Case?$select=CaseNumber,ClosedDateTime,CreatedDate,Description,ExternalRecordId,Id,LastModifiedDate,Subject,SystemModstamp&$expand=CasePriorityId($select=CreatedDate,Id,LastModifiedDate,Name,SystemModstamp),CaseStatusId($select=CreatedDate,Id,LastModifiedDate,Name,SystemModstamp),CaseTypeId($select=CreatedDate,Id,LastModifiedDate,Name,SystemModstamp)&$filter=ExternalRecordId%20eq%20%27GPID-002%27&$orderby=CaseNumber';//String queryTest ='Case?$select=CaseNumber,ClosedDateTime,CreatedDate,Description,ExternalRecordId,Id,LastModifiedDate,Subject,SystemModstamp&$expand=CasePriorityId($select=CreatedDate,Id,LastModifiedDate,Name,SystemModstamp),CaseStatusId($select=CreatedDate,Id,LastModifiedDate,Name,SystemModstamp),CaseTypeId($select=CreatedDate,Id,LastModifiedDate,Name,SystemModstamp)&$orderby=CaseNumber';request.setEndpoint('callout:DFS/'+queryTest);request.setMethod('GET');HttpResponse response = http.send(request);System.debug(response.getBody());

20

Request Case Data for UserExamples

JSONParser parser = JSON.createParser(response.getBody());while (parser.nextToken() != null) {

// Start at the array of casesif (parser.getCurrentToken() == JSONToken.START_ARRAY) {

while (parser.nextToken() != null) {// Advance to the start object marker to find next case object.if (parser.getCurrentToken() == JSONToken.START_OBJECT) {

// Read entire invoice object, including its array of line items.CimCase cc = (CimCase)parser.readValueAs(CimCase.class);//System.debug(cc);

// For debugging purposes, serialize again to verify what was parsed.//String s = JSON.serializePretty(cc);//system.debug('Serialized case: ' + s);

System.debug('CASE RECORD:' +'\nGlobal Party Id: ' + cc.ExternalRecordId +'\nCase Id: ' + cc.Id +'\nCase Number: ' + cc.CaseNumber +'\nSubject: ' + cc.Subject +'\nCase Status: ' + cc.CaseStatusId.Name +'\nCase Type: ' + cc.CaseTypeId.Name +'\nCase Priority: ' + cc.CasePriorityId.Name +'\nDescription: ' + cc.Description +'\nCreated Date: ' + cc.CreatedDate +'\nClosed Date Time: ' + cc.ClosedDateTime +'\nLast Modified Date: ' + cc.LastModifiedDate +'\nSystem Modified Stamp: ' + cc.SystemModstamp + '\n');

// Skip the child start array and start object markers.parser.skipChildren();

}}

}}

ReturnsReturns the following data.

{"@odata.context": "<base url>/dfs/v3.0/mds%2Fstmpa%2FMDS05pBm3yQNwbz/v21/$metadata#Case

(http://dfs-lbdv.retail-dfs.prd-sam.prd.slb.sfdc.net:7024/dfs/v3.0/mds%2Fstmfa%2FMDS05pBm3yQNwbz/v21/$metadata#Case)",

"value": [{"CaseNumber": "00001003","CaseStatusId": {"LastModifiedDate": "2019-12-12T07:08:39.000Z","Id": "core__stmfana44ice1__00DRM000000FCN22AO___500RM000001xChXYAU","SystemModstamp": "2019-12-12T07:08:39.000Z","CreatedDate": "2019-10-18T23:06:47.000Z","Name": "New"

},

21


"LastModifiedDate": "2019-12-12T07:08:39.000Z","Description": "[NA Service Org] This is Ian's problem.","CaseTypeId": {"LastModifiedDate": "2019-12-12T07:08:39.000Z","Id": "core__stmfana44ice1__00DRM000000FCN22AO___500RM000001xChXYAU","SystemModstamp": "2019-12-12T07:08:39.000Z","CreatedDate": "2019-10-18T23:06:47.000Z","Name": "Problem"

},"ExternalRecordId": "GPID-002","Id": "core__stmfana44ice1__00DRM000000FCN22AO___500RM000001xChXYAU","CasePriorityId": {"LastModifiedDate": "2019-12-12T07:08:39.000Z","Id": "core__stmfana44ice1__00DRM000000FCN22AO___500RM000001xChXYAU","SystemModstamp": "2019-12-12T07:08:39.000Z","CreatedDate": "2019-10-18T23:06:47.000Z","Name": "Medium"

},"Subject": "[NA Service Org] Ian's got a problem!","SystemModstamp": "2019-12-12T07:08:39.000Z","CreatedDate": "2019-10-18T23:06:47.000Z"

},{"CaseNumber": "00001004","CaseStatusId": {"LastModifiedDate": "2019-12-12T06:41:56.000Z","Id": "core__stmfana44ice1__00DRM000000FCNU2A4___500RM000001xE8fYAE","SystemModstamp": "2019-12-12T06:41:57.000Z","CreatedDate": "2019-11-13T06:08:09.000Z","Name": "On Hold"

},"LastModifiedDate": "2019-12-12T06:41:56.000Z","Description": "[EMEA Service Org] This is a very detailed description of the

feature Ian wants because of his problem.","CaseTypeId": {"LastModifiedDate": "2019-12-12T06:41:56.000Z","Id": "core__stmfana44ice1__00DRM000000FCNU2A4___500RM000001xE8fYAE","SystemModstamp": "2019-12-12T06:41:57.000Z","CreatedDate": "2019-11-13T06:08:09.000Z","Name": "Feature Request"

},"ExternalRecordId": "GPID-002","Id": "core__stmfana44ice1__00DRM000000FCNU2A4___500RM000001xE8fYAE","CasePriorityId": {"LastModifiedDate": "2019-12-12T06:41:56.000Z","Id": "core__stmfana44ice1__00DRM000000FCNU2A4___500RM000001xE8fYAE","SystemModstamp": "2019-12-12T06:41:57.000Z","CreatedDate": "2019-11-13T06:08:09.000Z","Name": "High"

},"Subject": "[EMEA Service Org] Ian wants a new feature","SystemModstamp": "2019-12-12T06:41:57.000Z","CreatedDate": "2019-11-13T06:08:09.000Z"

},

22


{"CaseNumber": "00001004","CaseStatusId": {"LastModifiedDate": "2020-04-14T22:02:51.000Z","Id": "core__stmfana44ice1__00DRM000000FCN22AO___500RM000002i1lNYAQ","SystemModstamp": "2020-04-14T22:02:51.000Z","CreatedDate": "2020-04-14T22:02:51.000Z","Name": "New"

},"LastModifiedDate": "2020-04-14T22:02:51.000Z","CaseTypeId": {"LastModifiedDate": "2020-04-14T22:02:51.000Z","Id": "core__stmfana44ice1__00DRM000000FCN22AO___500RM000002i1lNYAQ","SystemModstamp": "2020-04-14T22:02:51.000Z","CreatedDate": "2020-04-14T22:02:51.000Z","Name": "Question"

},"ExternalRecordId": "GPID-002","Id": "core__stmfana44ice1__00DRM000000FCN22AO___500RM000002i1lNYAQ","CasePriorityId": {"LastModifiedDate": "2020-04-14T22:02:51.000Z","Id": "core__stmfana44ice1__00DRM000000FCN22AO___500RM000002i1lNYAQ","SystemModstamp": "2020-04-14T22:02:51.000Z","CreatedDate": "2020-04-14T22:02:51.000Z","Name": "Medium"

},"Subject": "[NA Service Org] Ian wants to know how to call Data Federation Service",

"SystemModstamp": "2020-04-14T22:02:51.000Z","CreatedDate": "2020-04-14T22:02:51.000Z"

},{"CaseNumber": "00001005","CaseStatusId": {"LastModifiedDate": "2020-04-14T22:12:25.000Z","Id": "core__stmfana44ice1__00DRM000000FCNU2A4___500RM000002i1lSYAQ","SystemModstamp": "2020-04-14T22:12:25.000Z","CreatedDate": "2020-04-14T22:12:25.000Z","Name": "On Hold"

},"LastModifiedDate": "2020-04-14T22:12:25.000Z","CaseTypeId": {"LastModifiedDate": "2020-04-14T22:12:25.000Z","Id": "core__stmfana44ice1__00DRM000000FCNU2A4___500RM000002i1lSYAQ","SystemModstamp": "2020-04-14T22:12:25.000Z","CreatedDate": "2020-04-14T22:12:25.000Z","Name": "Question"

},"ExternalRecordId": "GPID-002","Id": "core__stmfana44ice1__00DRM000000FCNU2A4___500RM000002i1lSYAQ","CasePriorityId": {"LastModifiedDate": "2020-04-14T22:12:25.000Z","Id": "core__stmfana44ice1__00DRM000000FCNU2A4___500RM000002i1lSYAQ","SystemModstamp": "2020-04-14T22:12:25.000Z",

23


"CreatedDate": "2020-04-14T22:12:25.000Z","Name": "Low"

},"Subject": "[EMEA Service Org] Ian wants to know how to change his language

preference","SystemModstamp": "2020-04-14T22:12:25.000Z","CreatedDate": "2020-04-14T22:12:25.000Z"

},{"CaseNumber": "00001005","CaseStatusId": {"LastModifiedDate": "2019-12-12T07:18:11.000Z","Id": "core__stmfana44ice1__00DRM000000FOWV2A4___500RM000002g8uuYAA","SystemModstamp": "2019-12-12T07:18:12.000Z","CreatedDate": "2019-11-13T06:13:38.000Z","Name": "Escalated"

},"LastModifiedDate": "2019-12-12T07:18:11.000Z","Description": "[APAC Service Org] Ian called asking when his feature to fix his

problem will be implemented.","CaseTypeId": {"LastModifiedDate": "2019-12-12T07:18:11.000Z","Id": "core__stmfana44ice1__00DRM000000FOWV2A4___500RM000002g8uuYAA","SystemModstamp": "2019-12-12T07:18:12.000Z","CreatedDate": "2019-11-13T06:13:38.000Z","Name": "Question"

},"ExternalRecordId": "GPID-002","Id": "core__stmfana44ice1__00DRM000000FOWV2A4___500RM000002g8uuYAA","CasePriorityId": {"LastModifiedDate": "2019-12-12T07:18:11.000Z","Id": "core__stmfana44ice1__00DRM000000FOWV2A4___500RM000002g8uuYAA","SystemModstamp": "2019-12-12T07:18:12.000Z","CreatedDate": "2019-11-13T06:13:38.000Z","Name": "Low"

},"Subject": "[APAC Service Org] Ian wants to know when his feature will be

implemented","SystemModstamp": "2019-12-12T07:18:12.000Z","CreatedDate": "2019-11-13T06:13:38.000Z"

},{"CaseNumber": "00001006","CaseStatusId": {"LastModifiedDate": "2020-04-14T22:15:56.000Z","Id": "core__stmfana44ice1__00DRM000000FOWV2A4___500RM000002mRLfYAM","SystemModstamp": "2020-04-14T22:15:56.000Z","CreatedDate": "2020-04-14T22:15:56.000Z","Name": "Escalated"

},"LastModifiedDate": "2020-04-14T22:15:56.000Z","CaseTypeId": {"LastModifiedDate": "2020-04-14T22:15:56.000Z","Id": "core__stmfana44ice1__00DRM000000FOWV2A4___500RM000002mRLfYAM",

24


"SystemModstamp": "2020-04-14T22:15:56.000Z","CreatedDate": "2020-04-14T22:15:56.000Z","Name": "Problem"

},"ExternalRecordId": "GPID-002","Id": "core__stmfana44ice1__00DRM000000FOWV2A4___500RM000002mRLfYAM","CasePriorityId": {"LastModifiedDate": "2020-04-14T22:15:56.000Z","Id": "core__stmfana44ice1__00DRM000000FOWV2A4___500RM000002mRLfYAM","SystemModstamp": "2020-04-14T22:15:56.000Z","CreatedDate": "2020-04-14T22:15:56.000Z","Name": "High"

},"Subject": "[APAC Service Org] Ian is experiencing slow UI responses","SystemModstamp": "2020-04-14T22:15:56.000Z","CreatedDate": "2020-04-14T22:15:56.000Z"

}]

}

25


CHAPTER 4 Status Codes and Error Responses

Each request returns a status code or error response to indicate whether the request was successful.Errors can have several causes.

When an error occurs or when a response is successful, the response header contains an HTTP code, andthe response body usually contains:

• The HTTP response code

• The message accompanying the HTTP response code

DescriptionHTTPresponsecode

Query successfully executed and response data returned.2xx

(BAD REQUEST) The argument or query you supplied in the request isn’t valid, andwe can't search based on your query. Confirm the accuracy of your query or contactSalesforce Customer Support.

400 on page 26

(FORBIDDEN) We can't authenticate your request, so try to confirm your configurationor, you don't have permission to view the requested data on the connected system.

403 on page 28

Update your credentials on the connected system or contact Salesforce CustomerSupport for help.

(NOT FOUND) We can’t find something necessary to satisfy your query. Confirm theaccuracy of your query or contact Salesforce Customer Support.

404 on page 28

(CONFLICT) We can't search based on your query. Confirm the accuracy of yourquery or contact Salesforce Customer Support.

409 on page 29

(TOO_MANY_REQUESTS) Looks like we're trying to process too many requests atonce. Try again in a moment or contact Salesforce Customer Support.

429 on page 30

400 (BAD_REQUEST)

Table 1: 400 (BAD_REQUEST) ILLEGAL OPERATION

SolutionCauseIssue

Check that the fields are valid and tryagain.

At least one of the argumentsprovided in the query is invalid,

Illegal Argument

such as an invalid field used forselection or filtering.

26

SolutionCauseIssue

Check that your mappings querythese connected systems and tryagain.

At least one of the connectedsystems with a specialized queryisn't queried. For example, nomappings to the connected

Hinted Connected Systemsnot queried

system that is specified in thequery.

Change or remove the invalid queryand try again.

A query is present but invalidbecause it uses incorrectarguments in an expand.

Invalid Query Routing

Make sure your metadata repositorykey is in the form

An unsupported metadatarepository key is specified. For

Invalid Metadata RepositoryKey

of:{cloud}/{environment}/{MRK}:example, the metadatarepository key isn’t (MRK = MetadataRepostioryKey) and

try again.URL-encoded and containsinvalid characters.

Remove and reconnect one of theduplicate connected systems so that

More than one connectedsystem has the same API name.

Multiple Matching ConnectedSystems

only one connected system ismapped to a single name. Then tryagain.

Check the ID values and try again.Multiple problems with IDs.Multiple Query IDs

Remove any invalid or duplicatequery parameters and try again.

Multiple query parameters havethe same key or name, so it'sunclear which value to use.

Repeated Query ParameterName

Remove any extraneous or invalidquery parameters and try again.

A query parameter can’t behandled.

Unexpected Query ParameterName

Table 2: 400 (BAD_REQUEST) UNSUPPORTED_OPERATION

SolutionCauseIssue

Remove query components relyingon unsupported features.

The query is valid but thefeature isn’t yet implemented.

Unsupported OperationException

Table 3: 400 (BAD_REQUEST) UNSUPPORTED_QUERY

SolutionCauseIssue

Fix the specified API version.Unsupported Data FederationAPI version specified in theBaseURL.

Invalid DF API Version

Change the dialect to OData and tryagain.

Unsupported dialects such asOData, GraphQL, or SOQL.

Invalid Dialect Query

27

Status Codes and Error Responses

SolutionCauseIssue

Include all of the necessary pathparameters for the query and tryagain.

There are too few arguments forthe API dispatcher to match therequest to an implementedrequest handler.

Not Acceptable Exception

Remove query components relyingon unsupported hierarchies and tryagain.

The query to DF isn’t valid, forexample, when querying a childentity of a connector thatdoesn’t support hierarchies.

Malformed Query

403 (FORBIDDEN)

Table 4: 403 (FORBIDDEN) UNAUTHORIZED

SolutionCauseIssue

Make sure the authorization headeris valid and try again.

Your authorization headerdoesn’t start with the requiredC2C prefix.

Malformed Header

Make sure the authorization headeris valid and try again.

You didn’t send an authorizationheader in your request.

Missing Header

Contact Salesforce Customer Support.Unexpected security error.Unexpected Security Error

Table 5: 403 (FORBIDDEN) DATASOURCE_UNAUTHORIZED

SolutionCauseIssue

Update credentials on the connectedsystem and try again.

A connector encounters anauthorization failure while tryingto communicate with theconnected system.

Connector Authorization Error

404 (NOT_FOUND)

Table 6: 404 (NOT_FOUND)

SolutionCauseIssue

Fix the invalid endpoint and try again.An invalid endpoint wasspecified.

Jersey Not Found

Specify a knownConnected SystemConnection name and try again.

A Connected SystemConnection name was specifiedthat didn’t correspond to a

No Matching ConnectedSystem Connection

known Connected SystemConnection

28


SolutionCauseIssue

Specify a valid connected systemname.

There’s a specified connectedsystem name that doesn’tcorrespond to a knownconnected system key.

No Matching ConnectedSystem

Add the missing trust relationship forthe necessary source tenant and tryagain.

A referenced source tenant froma transformation isn’t present.

No Matching ManagedTenant

Specify a valid transformationrepository and try again.

An unsupported metadatarepository key is specified in the

No Matching TransformationRepository

DF API URL. The requestedmetadata repository isn’t found.

Specify a valid transformationrepository schema version and tryagain.

An unsupported metadatarepository version is specified inthe DF API URL.

No Matching TransformationRepository Version

Specify a valid transformationrepository or schema, version, or

There are no transformationsfound for the target entity.

No Matching Transformations

target entity combination and tryagain.

Add the missing trust relationship sothat the necessary source tenant is in

A referenced source tenant froma transformation is not presentin the Connected System set.

No Matching ConnectedSystem

the Connected System set and tryagain.

Specify a target entity that is presentin the schema and try again.

Salesforce Connect does nothave the requested entitydefinition.

Salesforce Connect Error

409 (CONFLICT)

Table 7: 409 (CONFLICT) ILLEGAL_ARGUMENT

SolutionCauseIssue

Remove all but one mapping thatpoints to the target field in the faultytransformation and try again.

There are multiple mappings forthe same target field whentrying to convert the targetquery's filter to the source orintermediate query schema.

Multiple Field Mappings

29


SolutionCauseIssue

Add a mapping to the target field inthe faulty transformation and tryagain.

There are no mappings for thetarget field when trying toconvert the target query's filterto the source or intermediatequery schema.

Missing Field Mapping

429 (TOO_MANY_REQUESTS)

Table 8: 429 (TOO_MANY_REQUESTS)

SolutionCauseIssue

Wait for some of your outstandingrequests to be completed or increaseyour quota and try again.

The Connect Center rejects therequest when too many testsare added to the queue and therate limit is reached.

Rejected Execution

30


CHAPTER 5 Troubleshooting Error Codes

Troubleshoot error codes from the Data Federation API depending on how you’re using and configuringthe API.

Basic Troubleshooting Steps

Make sure:

• The DFS External Data Source and the DFS Named Credential are both configured correctly.

• The mapping version supports your query.

• The entities and attributes you want to query are mapped for the data source that makes the queryand the data source being queried.

31

Data Federation API Developer Guide - Salesforce

Documents

Transcript of Data Federation API Developer Guide - Salesforce