Salesforce Adapter Guide

For SAP Cloud Platform Integration

and the cloud integration capability for SAP Cloud
Platform Integration Suite subscription

Version 1.0.0 – December 2020

 Salesforce Adapter Guide

Contents
1 Introduction .............................................................................................................. 3
1.1 Coding Samples .............................................................................................................. 3
1.2 Internet Hyperlinks ......................................................................................................... 3
2 Salesforce Integration................................................................................................ 3
2.1 Introduction ................................................................................................................... 3
2.2 Salesforce Adapter ......................................................................................................... 4
2.2.1 Features ............................................................................................................................................4
2.3 Architecture Overview .................................................................................................... 5
3 Supported Operations and Versions ........................................................................... 7
3.1 REST API ......................................................................................................................... 7
3.2 REST Bulk API ................................................................................................................. 8
3.3 REST Place Order API ...................................................................................................... 8
4 Authentication .......................................................................................................... 9
5 Adapter Configuration ..............................................................................................10
5.1 Connection Tab ............................................................................................................ 10
5.2 Processing Tab.............................................................................................................. 11
5.2.1 REST API......................................................................................................................................... 12
5.2.2 Place Order API ............................................................................................................................. 17
5.2.3 Bulk API ......................................................................................................................................... 20

6 Payload and Dynamic Configuration .........................................................................23

6.1 Message Payloads ........................................................................................................ 24
6.2 Basic Dynamic Configuration Example ........................................................................... 24
7 Eclipse Plugin Configuration .....................................................................................25
7.1 SOQL Query Editor ........................................................................................................ 25
7.1.1 Objects and Fields ......................................................................................................................... 26
7.1.2 Query Options ............................................................................................................................... 27
7.1.3 Results ........................................................................................................................................... 29
7.2 SOSL Query Editor ........................................................................................................ 30
7.2.1 Objects and Fields ......................................................................................................................... 30
7.2.2 Search Options .............................................................................................................................. 31
7.2.3 Results ........................................................................................................................................... 32
7.3 XSD Generator.............................................................................................................. 33
7.4 XSD Generator Aggregation/Composite ........................................................................ 35
8 Support ....................................................................................................................36
8.1 SSLHandshakeException ............................................................................................... 37
8.2 No Artifact Descriptor Found ........................................................................................ 37
8.3 There Are 2 Parameters That Couldn’t Be Set On The Endpoint ...................................... 37

1
 Salesforce Adapter Guide

8.4 Cannot Produce Target Element .................................................................................... 37

9 Sample Scenario Explained .......................................................................................38
9.1 Initial Steps .................................................................................................................. 38
9.1.1 Create an Integration Package in SAP CPI ..................................................................................... 38
9.1.2 Create and Add a New Integration Flow in SAP CPI...................................................................... 39
9.2 Synchronize Data .......................................................................................................... 40
9.2.1 Assign Timer Instead of Sender and Start Message...................................................................... 40
9.2.2 Message Mapping Request ........................................................................................................... 42
9.2.3 Configure Receiver Salesforce Adapter in SAP CPI ....................................................................... 44
9.2.4 Message Mapping Response......................................................................................................... 45
9.2.5 Result of the IFlow ........................................................................................................................ 45
9.3 Query Data ................................................................................................................... 45
9.3.1 Assign Timer Instead of Sender and Start Message...................................................................... 45
9.3.2 Configure Salesforce Receiver Adapter ........................................................................................ 47
9.3.3 Create SOQL Query ....................................................................................................................... 48
9.3.4 Message Mapping Response......................................................................................................... 49
9.3.5 Result of the IFlow ........................................................................................................................ 49
9.4 Composite Call.............................................................................................................. 50
9.4.1 Assign Timer Instead of Sender and Start Message...................................................................... 50
9.4.2 Message Mapping Request ........................................................................................................... 52
9.4.3 Configure Receiver Salesforce Adapter in SAP CPI ....................................................................... 53
9.4.4 Result of the IFlow ........................................................................................................................ 54
9.5 Monitor and Test Integration Flow in SAP CPI with Salesforce ........................................ 55
9.5.1 Monitor Integration Flow in SAP CPI............................................................................................. 55
9.5.2 Monitor Message Processing in SAP CPI ....................................................................................... 56

10 References................................................................................................................57
10.1 Initialize OAuth 2.0 in Salesforce ................................................................................... 57
10.2 Composite Instructions Salesforce................................................................................. 61

2
 Salesforce Adapter Guide

1 Introduction
This is the official guide for the Salesforce Adapter for SAP Cloud Platform Integration (SAP
CPI). This guide covers all relevant information for integration developers to start working
with the Salesforce Adapter. The adapter supports an extensive set of operations
supported by the Salesforce API.

Please read this guide carefully before using the Salesforce adapter.

1.1 Coding Samples

Any software coding and/or code lines/strings ("Code") included in this documentation are
only examples and are not intended to be used in a productive system environment. The
Code is only intended to better explain and visualize the syntax and phrasing rules of
certain coding. We do not warrant the correctness and completeness of the Code given
herein.

1.2 Internet Hyperlinks

The documentation may contain hyperlinks to the Internet. These hyperlinks are intended
to serve as a hint about where to find related information. We do not warrant the
availability and the correctness of this related information or the ability of this information
to serve a particular purpose.

2 Salesforce Integration
2.1 Introduction

Salesforce is a SaaS Cloud solution that covers four main topics; Marketing, Sales, Orders,
and Support. Salesforce Cloud supports sales, marketing, and customer support in both
B2B and B2C contexts. It helps track customer information and interactions in one place,
automates complex business processes, keeps all information up to date, nurtures leads,
and tracks the effectiveness of marketing campaigns.

For most organizations, while streamlining processes, it is required to exchange different

types of data between Salesforce and any other systems. This adapter can help you
exchange data between Salesforce and these other systems. For illustration purposes,
some business scenarios that the adapter can be used for include:

• Synchronizing transactional and master data,

• Consolidate data for CRM migration,

• Retrieve data from reports and dashboards,

• Manage order flow to Salesforce from your SAP and non-SAP backend applications,

• Process batches for large data sets,

3
 Salesforce Adapter Guide

• Order fulfillment and campaign tracking in Marketing & Sales,

• Aggregate data for compliance or auditing purposes, and

• Invoice creation in SAP when opportunities are successful.

In the next sections, we will discuss the available options and the adapter features.

2.2 Salesforce Adapter

From a high-level perspective, the Salesforce adapter has a few key features that will be
discussed in the next sections.

2.2.1 Features

• Querying and searching: In addition to all the operations that the Salesforce
adapter offers, the adapter allows you to query data from your Salesforce system
using SOQL and SOSL queries.

• Secure authentication with OAuth 2.0: Every REST call between Salesforce and SAP
CPI is secured by the OAuth 2.0 industry-standard protocol for authorization.

• Dynamic configuration with headers and properties: The Salesforce adapter gives
you the freedom to assign dynamic values to its different properties. It allows you
to refer to dynamic parameters using SAP CPI exchange headers and properties.

• Salesforce operation: The adapter offers over 50 operations.

• Processing large sets of data: With Bulk support, the Salesforce adapter is
optimized for loading or deleting large sets of data. Using batches many records
can be processed asynchronously.

• Supports for XML & JSON: XML and JSON are fully incorporated throughout the
adapter, while the REST Bulk API supports CSV and ZIP files. Furthermore, the
Salesforce adapter also processes binary content from your Salesforce system,
more specifically the Document and Attachment object as part of the REST – Get
Blob operation.

• Pretty print: It is possible to “pretty print” the XML and JSON message payloads
returned by Salesforce to improve readability by formatting the data structure.

• Support for various Salesforce versions: Salesforce releases few versions of its API
every year. The Salesforce adapter lets you integrate with the Salesforce API
version of your choice. At the time of this publishing, the Salesforce adapter
supports up to Salesforce API Version 48.0.

• Query and XSD Eclipse plug-in: The Eclipse Query plug-in enables you to create
correct and specific SOQL and SOSL queries. The Eclipse XSD plug-in helps you
generate all necessary up-to-date messages XSD’s for your specific Salesforce
version and custom objects.

4
 Salesforce Adapter Guide

• Full integration support for Custom Objects and Fields: In addition to supporting all
the standard Salesforce objects, the adapter integrates with all the custom objects
in Salesforce.

• Support for latest API version: The adapter supports the latest Salesforce API
version (Version 48), which was released in Spring 2020.

• Support for creation/upsert of Aggregated Structures: The Salesforce adapter

supports composite Salesforce call where the request body can contain a
combination of different operations (like upsert and read) on multiple SObjects at
the same time.

• Support nested structures in the CRUD operations: This feature supports the
references that link nested SObjects to a main SObject in the XSD Generation plug-
in. This allows the user to map referenced SObjects in the structure. For example,
the Account XSD contains the referenced subobjects Account, ReportsTo, and
Owner.

2.3 Architecture Overview

From a technical perspective, the Salesforce adapter can be used as a receiver adapter
and the SAP Cloud Integration acts as the initiator of the calls. To schedule calls toward
Salesforce, the user can follow the Scheduler steps within the integration flow.

Figure 2.1 shows how the Salesforce adapter can be used in a simple request-reply
scenario and gives a high-level representation of how the adapter works. Various
operations can be used in the adapter – such as query data, delete, update, upsert, or
create an SObject, etc. The different adapter operations and their configuration are
explained in Section 5.

The Request-Reply Step can use the Salesforce adapter as show in Figure 2.1. This adapter
is responsible to connect and interact with Salesforce and invoke its different operations.

The Eclipse Plug-in, which is delivered together with the adapter, can also be used to help
the user generate the XSDs of the different entities or business objects that are part of
the Salesforce tenant.

The XSDs generated by the Eclipse Plug-in can be imported in an Integration Flow and
used in mappings. You can, for instance, use it in the mapping in front of the Request-
Reply Step. This way, you can create the correct XML request message to create or update
an SObject in Salesforce (see the Mapping Step on the left side of the Request-Reply
Step). Similarly, you can use the XSDs to create a mapping to handle the response
message sent by Salesforce.

5
 Salesforce Adapter Guide

Figure 2.1 Salesforce Adapter solutions for SAP CPI

Furthermore, the Eclipse Plugin has the following features:

• The XSD Generator helps you generate up-to-date XSDs for your Salesforce
SObjects for different operations (create, delete, update, etc.). This makes
mappings to other system’s message types a straightforward step. For the
Salesforce plug-in and XSD Generator configuration please refer to the Salesforce
Adapter and Plug-in Installation Guide.

• The Query Editor assists you in creating valid SOQL or SOSL queries. With these
queries, you can get the best out of the REST, and REST Bulk API. To read more
about the Salesforce Eclipse plug-in, refer to the document Salesforce Adapter and
Plug-in Installation Guide.

Figure 2.2 shows at which stage of the SAP CPI integration flow, the Salesforce adapter
can be used and where the XSD Generator and the SOSL or SOQL Query Editor are used.

Figure 2.2 The Salesforce Adapter, Eclipse Plug-in.

6
 Salesforce Adapter Guide

3 Supported Operations and Versions

The adapter supports the following main API categories:

• REST API

• REST Place Order API

• REST Bulk API

A short description of each one of these REST APIs are presented in the next sections.

3.1 REST API

The REST API is selected by default and lets you integrate with Salesforce using either
XML or JSON formats. The integration is done securely by utilizing the OAuth protocol for
authenticating your REST calls. The REST API enables you to access the full data model
of Salesforce and execute CRUD operations and many more. Note that these operations
generally handle single SObject records as input.

However, if you have many records to process, you can opt for the Bulk API (explained in
detail in Section 3.2) which is optimized for large sets of data. The following operations
are currently supported in the adapter’s REST API Category:

• Metadata – All

• Metadata – Basic

• Metadata – Comprehensive

• Other – Get REST API Versions

• Other – Get REST Resource Endpoints

• Salesforce Object – Create

• Salesforce Object – Delete

• Salesforce Object – Delete with External ID

• Salesforce Object – Get

• Salesforce Object – Get Blob Salesforce Object - Get with External ID

• Salesforce Object – Update

• Salesforce Object – Upsert with External ID

• Salesforce Objects – Composite

• SOQL – Execute Query

• SOQL – Execute Query for More Results

7
 Salesforce Adapter Guide

• SOSL – Search Resource

To get a description of the purpose of each of the above operations and how to configure
them, refer to Section 5.2.1.

3.2 REST Bulk API

The Bulk API is specifically designed to load or update large sets of data into a Salesforce
organization. With this API, it is possible to query, insert, update, upsert, or delete many
records asynchronously by submitting batches for Salesforce to process in the background.
The following operations are currently supported in the adapter:

• Batch – Create

• Batch – Get

• Batch – Get Request

• Batch – Get Results

• Batch Query – Create

• Batch Query – Get Result

• Batch Query – Get Result IDs

• Job – Abort

• Job – Close

• Job – Create

• Job – Get

• Job – Get All Batches

To get a description of the purpose of each of the above operations and how to configure
them, refer to Section 5.2.3.

3.3 REST Place Order API

The Place Order API lets you access your organization’s order and contract data
programmatically. This is a composite API that supports the creation of contract, order,
order product, and custom object records in a single call. The following operations are
currently supported in the adapter:

• Account – Add Contracts and Orders

• Account – Add Orders

• Contract – Add Orders

8
 Salesforce Adapter Guide

• Contract – Filter Details

• Contract – Get

• Order – Add Products

• Order – Filter Details

• Order – Get

Each of the above operations are discussed in Section 5.2.2.

4 Authentication
The Salesforce adapter supports OAuth 2.0. The adapter makes use of common security
artifacts in SAP Cloud Platform Integration. You are required to use Secure Parameter and
User Credentials to safely store OAuth tokens, user-password combinations, and secrets.
These security artifacts can then be accessed in the adapter using aliases.

The Salesforce adapter uses the OAuth 2.0 Salesforce Autonomous Client
type. The adapter uses a Basic Authentication flow which requires a Salesforce username
and password to connect to the Salesforce tenant data. In addition to the username and
password, you are also required to provide the so-called Salesforce app credentials.

These app credentials consist of a client id and client secret. The diagram in Figure
4.1 explains the process that is used in the background to connect to Salesforce. With the
access token that is returned from the authorization server, the Salesforce adapter can
make different requests to Salesforce resources.

Figure 4.1 SAP Cloud Platform Salesforce adapter authenticating as OAuth 2.0 Autonomous Client

In the next section, we discuss how to configure the adapter.

9
 Salesforce Adapter Guide

5 Adapter Configuration
This section describes the different parameters that can be configured for the Receiver
Adapter. This adapter has the Connection and Processing tabs. Each one of these will be
explained in the next sections.

5.1 Connection Tab

The Connection tab contains parameters that define how to connect to and how to
authenticate against Salesforce.

Figure 5.1 Connection tab of Salesforce adapter

As can be seen in Figure 5.1, the connection tab contains the following fields:

• Address: This specifies the recipient's endpoint URL. By default, the URL
[Link] is used. But you can change it based on your scenario.
For Salesforce production environments: [Link]
For Sandbox environments: [Link]

• Basic Credential Name: Specifies the name of the User Credentials artifact that
contains the credentials for basic authentication. This refers to the username-
password pair used to login in Salesforce. You need to create this as a Security
artifact of type User Credential. Then refer to it here in the adapter.
• Security Token Alias: Specifies the name of the Secure Parameter artifact that
contains the security token needed to connect to Salesforce. This property
enables the system to fetch the security token from Keystore for authentication.
This field can be omitted if your IP has been whitelisted on Salesforce.

• OAuth Credential Name: Specifies the name of the User Credentials artifact that
contains the Salesforce’s OAuth Consumer key-client secret pair. This
property enables the system to fetch the security token from Keystore for
authentication.

• Connection Timeout (in ms): Specifies the connection timeout in milliseconds. The
timeout allows you to control the wait time until the connection is established.

• Response Timeout (in ms): Specifies the response timeout in milliseconds. The
timeout allows you to control the wait time until the message is received.

10
 Salesforce Adapter Guide

• Lazy Authentication: The Lazy Authentication enables OAuth token retrieval or

generation until the first API call.

For more details on how to retrieve details of the Security token, Consumer key-client
secret pair, refer to Section 10.1.

5.2 Processing Tab

The Processing tab contains all the operation configurations for the selected Salesforce
API. An example configuration for the operation Salesforce Object – Create is shown in
Figure 5.2.

Figure 5.2 Adapter Specific tab of Salesforce adapter

The different properties of the adapter shown in Figure 5.2 are described below:

• Type: Specifies the category of the API to be used to interact with Salesforce.
Possible values include REST, REST Bulk, and REST Place Order. These different
API types were explained in Section 3.

• API Version: The API Version specifies the version of the Salesforce API. It ranges
from version 20.0 up to the latest Salesforce version supported by the adapter. At
the time of publishing this document, Version 48 is the latest one.

• Operation: To access and exchange data with Salesforce, you can choose one of
the provided operation options. Here you specify the type of action you want to
execute in Salesforce. Section 5.2.1 dives into all the different operations and assist
you in deciding what operation to use for your integration scenario.

• Payload Format: This field specifies the format of the request message to be sent
to and response to be returned from Salesforce. Possible values include
Application/XML and Application/JSON. Note that the default value is
Application/XML.

• Salesforce Object: Select the name of the object in Salesforce to operate on.
Example: accounts, Lead, Order, etc. You can select Custom in case any custom
SObject is involved.

• Pretty Print: Select the Pretty Print checkbox to nicely format the XML payload and
improve its readability.

11
 Salesforce Adapter Guide

5.2.1 REST API

The REST API supports 15 operations to retrieve or send data to Salesforce. These
operations are categorized into five groups known as Salesforce Object, Metadata, SOQL,
SOSL, and Others.

There are a set of common fields that are often used across different operations in the
salesforce adapter. These common fields are described below:

• Operation: To access and exchange data with Salesforce, you can choose one of
the operation options listed in the dropdown.

• Salesforce Object: Represents a business object or entity in Salesforce. Example

Salesforce Object (or SObject) include Account, Contact, Order, Product, etc. Each
Salesforce console tab represents one Salesforce Object. In case you want to use
a Custom Object name, simply select Custom Object from the list with Salesforce
objects and type the name of the Custom Object.

• Salesforce Object ID: Specifies an unique record of an SObject.

• External ID Name: Refers to the name of a custom field of the SObject which is
configured as an external ID. This is an alternative way to identify a Salesforce
Object record based on a unique identifier provided by an external system (other
than Salesforce).

• External ID Value: Refers to the value of the External ID Name field. For example,
in a scenario where an SAP ERP system needs to synchronize master data with
Salesforce, one might use SAPReferenceNumber in Salesforce (as External ID
Name) and 10005210032 as (External ID Value) to identify that record in
Salesforce based on the SAP identifier.

• SOQL Query: Specifies the SOQL Query to be executed in Salesforce. SOQL stands
for Salesforce Object Query Language and is an adaptation of the well-known SQL
query language. A simple SELECT ID, Name FROM Account will give you all the ID
and Name for all Account records in Salesforce. For more advanced queries use the
SOQL Query Editor showcased in detail in Section 7.1.

• SOSL Search: Specifies the SOSL Search to be executed in Salesforce. SOSL stands
for Salesforce Object Search Language and is used to construct text-based search
queries against the search index. You can search text, email, and phone fields for
multiple objects, including custom objects. An example SOSL is FIND {Bakery*}
RETURNING account (industry, ID, billingStreet, name). Section 7.2 explains how
to use the SOSL Search Editor to get the most out of your SOSL Salesforce
searches.

• Filter Fields: Specifies the fields of the SObject that needs to be returned as part
of the result of a query toward Salesforce. Without any field specified in this
property, all fields of the SObject will be returned. For example, instead of getting
back all the fields for a specific Salesforce Object, the operation Salesforce Object
– Get can be narrowed down by applying a filter for only ID, name, and industry.

In the next sections, we will explain each operation of the REST API and what they can
be used for.

12
 Salesforce Adapter Guide

[Link] Other – Get REST API Versions

This operation retrieves a list of information about each REST API version currently
available.

[Link] Other – Get REST Resource Endpoints

This operation retrieves a list of resources available for the specified API version.

[Link] Metadata – All

This operation retrieves a list of available objects for your Salesforce tenant. This operation
also returns the Salesforce org encoding, as well as the maximum batch size permitted in
queries.

[Link] Metadata – Basic

This operation retrieves metadata for a specified Salesforce object. The below table shows
an example configuration of this operation.

Example Configuration

API Version 48.0

Operation Metadata - Basic
Salesforce Object Account
Payload Format application/JSON or application/XML
Pretty Print X

[Link] Metadata – Comprehensive

This operation retrieves all the metadata for a specified Salesforce object.

[Link] Salesforce Object – Get

This operation retrieves a record in Salesforce and its properties. The below table shows
an example configuration of this operation. Also, note in this example the configuration of
specifying the names (ID, name) in the fields to be returned (in the property named List
of Fields).

13
 Salesforce Adapter Guide

Example Configuration

API Version 48.0

Operation Salesforce Object - Get
Payload Format application/JSON or application/XML
Salesforce Object Account
Salesforce Object ID 0013600000xU52T
Filter Fields X
List of Fields ID, name
Pretty Print X

[Link] Salesforce Object – Create

This operation creates a new record of a specified Salesforce Object. The request payload
provides the property and field values in the request data. The response body will contain
the unique identifier (ID) of the created record if the call is successful.

[Link] Salesforce Object – Update

This operation updates a Salesforce Object record. The request payload contains the
property values that are needed to update a record in Salesforce based on a specific record
ID. The below table shows an example configuration of this operation.

Example Configuration

API Version 48.0

Operation Salesforce Object - Update
Payload Format application/JSON or application/XML
Salesforce Object Case
Salesforce Object ID 5003600000Ag1YK
Pretty Print X

[Link] Salesforce Object – Delete

This operation deletes a Salesforce Object record. The operation requires the unique
identifier of the Salesforce record to be specified.

[Link] Salesforce Object – Get with External ID

This operation retrieves details of a Salesforce Object record using the value of a specified
external ID. This operation differs from Salesforce Object – Get because the External ID

14
 Salesforce Adapter Guide

should be specified instead of the Salesforce record ID. This is shown in the example
configuration below.

Example Configuration

API Version 48.0

Operation Salesforce Object - Get with External Id
Payload Format application/JSON or application/XML
Salesforce Object Account
External ID Name SAPReferenceNumber__c
External ID Value 1000521110
Fields ID, name, industry
Pretty Print X

[Link] Salesforce Object - Upsert with External ID

This operation creates or updates records in Salesforce depending on whether it already

exists or not. It uses the value of a specified External ID to determine whether to create
or update a record. If this value doesn't exist, a new record is created. If a record does
exist with that value, the field values specified in the request body are updated.

[Link] Salesforce Object - Delete with External ID

This operation deletes a record using the value of a specified External ID. Therefore, the
External ID should be specified instead of the Salesforce ID of the record.

[Link] SOQL - Execute Query

This operation allows you to execute powerful SOQL queries for retrieving Salesforce data.
When using this operation, it is possible to filter the records to be returned in the response
from Salesforce. For example, you could return the IDs and the names of all the Accounts
based in France with more than one billion yearly revenue. The SOQL query returns all the
records in a single response. It is however possible to return part of the remaining records
using an identifier. For more details on how to achieve this, please refer to the operation
SOQL Execute Query for More Results. Furthermore, you can use the SOQL Query Editor
(which is provided in the Eclipse Plugin) to build specific and complex queries. This is
specified in Section 7.1. The following table shows an example configuration.

15
 Salesforce Adapter Guide

Example Configuration

API Version 48.0

Operation Execute SOQL query
Payload Format application/JSON or application/XML
SOQL Query Select ID, name, industry FROM Account
Pretty Print X

[Link] SOQL - Execute Query for More Results

This operation retrieves the query results that were not returned in the original SOQL –
Execute Query response using a Next Records URL. SOQL - Execute Query for More Results
is therefore an extension of the previous operation. This operation exists because in some
cases the result of a query can generate a lot of data that can not all be returned within
one response payload. In such a case, a URL is returned in the SOQL - Execute Query.
This URL can then be used in the Execute Query for More Results operation. The table
below shows an example configuration.

Example Configuration

API Version 48.0

Operation SOQL - Execute Query for More Results
Payload Format application/JSON or application/XML
Next Records URL /services/data/v44.0/query/01g3600000XpvoNAAR-
1000
Pretty Print X

[Link] SOSL – Search Resource

This operation supports a SOSL query to search for useful information in Salesforce. The
Salesforce Object Search language lets users search using strings throughout the entire
Salesforce tenant and acts as an alternative for the SOQL query. Users can utilize the
SOSL Search Editor to build complex queries. For details on how to use the SOSL Search
editor in the Eclipse Plugin, see Section 7.2. The table below shows an example
configuration.

16
 Salesforce Adapter Guide

Data Insert

API Version 48.0

Operation SOSL - Search Resource
Payload Format application/JSON or application/XML
SOSL Search FIND {Bakery*} RETURNING account (industry, ID,
billingStreet, name)
Pretty Print X

[Link] Salesforce Objects – Composite

This operation allows you to create a composite call with a request body that contains
various individual calls like upsert and read actions on multiple SObjects. The Composite
operation supports the usage of multiple SObject records and multiple SObject types in
one operation. Imagine an integration scenario where you would like to create one account
and two contacts within the same call to Salesforce. In such a case the composite operation
can be used. A more detailed example scenario can be found in Section 9.4. The table
below shows an example configuration.

Example Configuration

API Version 48.0

Operation Salesforce Objects - Composite
Payload Format application/JSON or application/XML
Pretty Print X

5.2.2 Place Order API

The Place Order API supports 8 operations that retrieve or push data to Salesforce. These
operations are categorized into three groups known as Account, Contract, and Order. The
configuration for each operation can differ in terms of dynamic setting and whether the
API expects a request body or returns a response body.

There are a set of common fields that are often used across different operations in the
Place Order API. These common fields are described below:

• Order ID: The unique identifier (ID) of the Order that is being processed. Similar
to Salesforce Object ID, this is the unique identifier that can be found in the last
part of the URL in the Order record view in the Salesforce Console.

• Contract ID: The unique identifier (ID) of the Contract that is being processed.
Within the context of the place order API, Contracts act as the parent Salesforce
Object and Orders as the child Salesforce Object.

17
 Salesforce Adapter Guide

• Filter Name: Contains the name of the child object field to be used for filtering
purposes. For illustration, imagine that you would like to filter all orders that below
to a contract and that have a particular statuscode.

• Filter Value: Contains the value of the child object field to be used for filtering
purposes. Together, the Filter Name and Filter Value can help to retrieve specific
fields of an Order or Contract. An example is provided in Section [Link].

Each one of the 8 operations are explained in the next sections.

[Link] Account – Add Contracts and Orders

This operation creates contract-based orders in Salesforce. The table below shows an
example configuration.

Example Configuration

API Version 48.0

Operation Account - Add Contracts and Orders
Payload Format application/JSON or application/XML
Pretty Print X

[Link] Account – Add Orders

This operation can create multiple orders with their order items (also known as order
products) for an existing account.

[Link] Contract - Add Orders

This operation creates an order with order products for an existing contract. The table
below shows an example configuration.

Example Configuration

API Version 48.0

Operation Contract - Add Orders
Payload Format application/JSON or application/XML
Contract ID 80036000000dq8E
Pretty Print X

18
 Salesforce Adapter Guide

[Link] Contract - Filter Details

This operation queries a contract based on a filter criteria specified in the Contract ID,
Filter Name, and Filter Value field. The table below shows an example configuration.

In this example, we are filtering orders that have the StatusCode equal to “Activated” with
the contract with ID “80036000000dq8E”.

Example Configuration

API Version 48.0

Operation Contract - Filter Details
Payload Format application/JSON or application/XML
Contract ID 80036000000dq8E
Filter Name [Link]
Filter Value ‘Activated’
Pretty Print X

[Link] Contract – Get

This operation retrieves the details of a Contract record in Salesforce based on its ID. Note
that it also returns its child orders, order products, and custom objects.

[Link] Order – Add Products

This operation adds order products to an existing order. It is required to specify the order
ID.

[Link] Order – Filter Details

This operation queries orders based on filter criteria. The table below shows an example
configuration.

Example Configuration

API Version 48.0

Operation Order - Filter Details
Payload Format application/JSON or application/XML
Contract ID 80036000000dq8E
Filter Name [Link]
Filter Value 2013-08-05
Pretty Print X

19
 Salesforce Adapter Guide

[Link] Order - Get

This operation retrieves the details of an order record in Salesforce based on its ID. Note
that it also returns its order products and child custom objects.

5.2.3 Bulk API

The Bulk API supports 12 operations to retrieve or push large sets of data. It uses the
concepts of jobs and batches. A job works as a container that holds one or more batches.
Each batch can contain 10.000 records. Note that the inserted batches need to conform
to the settings of the job.

Figure 5.3 depicts the relationship between a Job, Batches, and the processing of data.
After the batches are added to a specific job, the included records will be processed in
Salesforce. Besides being able to create, abort, close, retrieve jobs, it is also possible to
retrieve the status and the results with specific operations that this adapter provides.

Figure 5.3 Bulk API – schematic overview of jobs and batches

There are a set of common fields that are often used across different operations in the
Bulk API. These common fields are described below:

• Content Type: Specifies the file content of the batches. You can select from CSV,
JSON, XML, ZIP CSV, ZIP JSON and ZIP XML. This implies that a batch can be
created in CSV, JSON, XML, and its ZIP equivalent.

• Job ID: The unique identifier of the Job being processed.

• Batch ID: The unique identifier of the Batch being processed.

• Result ID: represents the unique identifier for the Result in the response to the
batch result list request. For Bulk API Query operations, you can use this Result ID
to retrieve the results of a Bulk Query.

Each one of the operations of the Bulk API is explained in the next sections.

[Link] Job – Create

This operation creates a REST Bulk Job. In the request message, you can specify the
properties of the job, which acts as a specification for future attached Batches. The table
below shows an example configuration.

20
 Salesforce Adapter Guide

Example Configuration

API Version 48.0

Operation Job – Create
Payload Format application/JSON or application/XML
Pretty Print X

[Link] Job – Get

This operation retrieves all details for an existing job. The table below shows an example
configuration.

Example Configuration

API Version 48.0

Operation Job – Get
Job ID 75036000006MDYb
Payload Format application/JSON or application/XML
Pretty Print X

[Link] Job – Abort

This operation aborts an existing job. When a job is identified and aborted, no more
records are processed. If changes to data have already been committed, they aren’t rolled
back.

[Link] Job – Close

This operation closes the job after it has finished processing. When a job is identified and
closed, no more batches can be added to it.

[Link] Job – Get all Batches

Get information about all batches in a specific job by executing this operation.

[Link] Batch – Create

This operation adds a new batch to an existing job. The request body contains a list of
records to be processed. The table below shows an example configuration.

21
 Salesforce Adapter Guide

Data Insert

API Version 48.0

Operation Batch - Create
Content Type XML/ZIP CSV/ZIP JSON/ZIP XML
Job ID 75036000006MDYb
Pretty Print X

[Link] Batch – Get

This operation retrieves information on existing batch.

Data Insert

API Version 48.0

Operation Batch - Get
Payload Format application/JSON or application/XML
Job ID 75036000006MDYb
Batch ID 75136000005kbnC
Pretty Print X

[Link] Batch – Get Request

This operation retrieves a batch request. It is also possible to retrieve the original request
which was used to initiate the Batch.

[Link] Batch – Get Result

This operation retrieves the results for a specific Batch. Because Batches are processed
asynchronously, you need this operation to see the results after Batch processing has been
completed. Note that the content type of the result matches the one of the request. This
means that in case the batch is a CSV file, the response will also be in CSV format.
Alternatively, you can monitor a Bulk API batch in the Salesforce console.

[Link] Batch Query – Create

This operation adds a batch query to a bulk query job.

22
 Salesforce Adapter Guide

Example Configuration

API Version 48.0

Operation Batch Query - Create
Payload Format application/JSON or application/XML
Job ID 75036000006MDYb
SOQL Query SELECT Id, Name FROM Account
Pretty Print X

[Link] Batch Query - Get Result

When a batch query has completed processing records you can retrieve the results with
this operation, using the Result ID that you get back from the operation Batch Query –
Get Result IDs. Alternatively, you can monitor a Bulk API batch in Salesforce.

Example Configuration

API Version 48.0

Operation Batch Query - Get Result
Payload Format application/JSON or application/XML
Job ID 75036000006MDYb
Batch ID 75136000005kbnC
Result ID 752360000033TwU
Pretty Print X

[Link] Batch Query - Get Result IDs

This operation retrieves a list of Result IDs. These Result IDs can then be used in the Batch
Query – Get Result operation to retrieve the actual results. Alternatively, you can view the
Result IDs in the Salesforce console.

6 Payload and Dynamic Configuration

The Salesforce adapter support different message formats. It also supports dynamic
configuration of its properties using both the header and property features of the SAP CPI
exchange. Both header and property features of the exchange can be used in the majority
of Salesforce Adapter properties.

23
 Salesforce Adapter Guide

6.1 Message Payloads

The majority of operations require a Message as input to be sent to Salesforce. As an

example, we will look at Salesforce Object – Create. To create an object in Salesforce, in
the message body you need to specify the fields and values to be inserted in Salesforce.
To achieve that, we first need to specify the Salesforce Object type in the
Salesforce Adapter. An example payload to create an Account Salesforce Object can be
seen in Figure 6.1.

Figure 6.1 Create an Account Salesforce Object payload

The XSD Generator (configuration details in Section 7.3) helps in two ways. First, it
generates the XSDs that you might want to use in mappings in your integration scenario.
Following our example, the XSD will include elements/properties of the SObjects.

Assuming that you are performing a Create operation in Salesforce, using the correct
request XSD as the target of the mapping before the request-reply will help you create a
valid input message (payload) towards Salesforce.

The XSDs obtained from the Eclipse Plugin can help to provide a good understanding of
the request message that the various Salesforce operations expect as well as the response
messages that you can expect from Salesforce.

6.2 Basic Dynamic Configuration Example

This section illustrates the use of dynamic values in the adapter property. It depicts a
simple Salesforce Object – Get operation configuration using a dynamic header reference.

1. You need to use a content modifier before the Request-Reply step in your
Integration flow, and this content Modifier should create a Message Header. The
name of the Message Header is the name you need to refer to in the Salesforce
Adapter. Any name is allowed here. Note that it is also possible to use properties
instead of a header to achieve the same. In this example, we use the Constant
type and fill in the Salesforce Object ID as a value.

24
 Salesforce Adapter Guide

Figure 6.2 Message Header in Content Modifier

2. The Salesforce Receiver adapter (which is linked to the Request-Reply step) needs
to refer to this header by using ${[Link]}. To refer to a property, a syntax
similar to ${[Link]} should be used. In our example, we can refer to the
AccountID header using the syntax ${[Link]}, as can be seen in
Figure 6.3. The Salesforce Adapter will automatically replace this reference with
the ID 0013600000xU52T.

Figure 6.3 Adapter Specific tab for Salesforce Object - Get operation

7 Eclipse Plugin Configuration

7.1 SOQL Query Editor

The SOQL Query Editor helps build and test well-formatted queries in the Salesforce Object
Query Language. It supports the building of queries for the Rest and Bulk API. Depending
on the selected API, different functionality is supported according to the Salesforce
documentation. The offset functionality, for example, can be used in the Rest API, but not
in the Bulk API. The Query Editor is limited to queries within one object since relationships
and joins have not been implemented. The SOQL Query Editor is the first tab in the
Salesforce CPI Adapter Tool perspective, see Figure 7.1.

The following steps show how to create a query with the SOQL Query Editor and describe
the sections and elements of the editor.

25
 Salesforce Adapter Guide

Figure 7.1 SOQL Query Editor

7.1.1 Objects and Fields

Objects and their subsequent fields can be selected in the left component of the SOQL
Query Editor, as shown in Figure 7.2. At the bottom of the component is the progress bar
that runs when data is retrieved from salesforce and prepared for display.

Figure 7.2 Objects and field overview

26
 Salesforce Adapter Guide

1. Select the API version in the Version dropdown. The version is synchronized
between the different tabs. If a version is selected in another tab, this will be
automatically selected here.

2. Select the API for which you want to create a query. Choices are Rest or Bulk.

3. Optional: Search for the object you want to create a query for, using the
Search SObject… field.

4. For example, type “acc” and the list below will only show objects with that letter
combination such as “account” or “access”.

5. Click on the arrow in front of an object to load all the fields of the object.
Alternatively, the box in front of the object can be selected, this will load and select
all fields of that object.

6. Select the objects or specific fields you want to create a query for. The selected
fields will be visible in the SELECT section.

7.1.2 Query Options

The component on the top right of the SOQL Query Editor enables you to set different
query options. The different syntax elements have their own section, labeled accordingly;
see Figure 7.3.

Figure 7.3 Query options component

27
 Salesforce Adapter Guide

• The SELECT section displays the selected fields.

o In the table, you can choose to format fields to local settings by selecting
the box. If a field is formatted, it is possible to give it an alias.

o In the aggregate functions column, the desired function can be selected.

Click the arrow to show a dropdown with available functions (e.g. AGV,
COUNT, SUM). Available options depend on the data type of the field: AVG
and SUM are available for numbers, but not for text fields.

o Date functions are available for date/DateTime fields. This column enables
formatting the field, for example, a calendar year or month. Click on the
arrow to show the dropdown with available options and select.

o The Other column holds other functions such as ”ConvertCurrency”. This

dropdown is available when there is a function available.

• The FROM section shows which Salesforce Object is selected. This cannot be
changed in this section; it is changed dynamically by selecting fields from a
different object in the Objects and Fields component.

• In the USING SCOPE section, the scope of the query can be set. The default scope
is “everything”, without this being indicated in the query.

• In the WHERE section, the field and operator can be selected for the statement.
Depending on the selected field, the input changes accordingly.

o Text fields facilitate free text input.

o For picklists fields, the input is a dropdown with all available options.

o Numeric fields allow only numbers.

o For DateTime fields, the input will split up into two parts: the first part being
a calendar to select the date from; the second an input field for a time.
Alternatively, you can choose to use time literals by ticking the box. The
input will change into a dropdown with time literals.

Select the NULL box if you want a query for records without value.

Additional WHERE statements can be added by pressing the plus sign on the right.
This will add a new row to create an extra statement. New rows will be preceded
with a dropdown to select AND/OR. To remove a row, click the minus sign on the
right of the row.

See
Figure 7.4 Overview of the WHERE section

for an overview of the WHERE section.

• The GROUP BY section enables grouping query results. A field can be selected to
group by. Optionally you can choose to group by rollup or group by cube, to include
subtotals in the query.

28
 Salesforce Adapter Guide

HAVING is a sub-section of GROUP BY. Here you can select a having statement
for the grouping. This section functions in the same way as the WHERE section
described above.

Figure 7.4 Overview of the WHERE section

• In the ORDER BY section, the field to sort on can be selected. The default order is
ascending, selecting the DESC box puts the query results descending order.
Additionally, records without an entry for the selected fields can be placed at the
bottom of the query result by selecting the box NULLS LAST.

• The LIMIT section allows setting the limit of query results returned from a query.
This is only available for the REST and Bulk API.

• In the OFFSET section, it is possible to set the starting row of the returned result
set. This is only available for the REST API.

7.1.3 Results

The component located at the bottom right allows you to test the created query. See
Figure 7.5 for an overview of the component.

Figure 7.5 Overview of result component

• The text field on the left shows the created query. This query cannot be edited
manually; it can only be changed by the settings in the other components.

29
 Salesforce Adapter Guide

• Press Run Query to test the query and see if the results are as expected. It will
take some time to process this request, the button will indicate that the query is
running, and return to the original state when the query is finished.

• The Query Result tab on the right will display the results in a table.

• If the query is not valid, the Syntax Check tab on the right can be consulted. This
displays additional information: the message and error code of the response.

• If the results are satisfactory, the query can be copied for use in the
Salesforce CPI Adapter. You can either press the “Copy Query” button that copies
the query to the clipboard, or select the query and copy it manually.

• An XSD for the query result can be generated by pressing the “Generate XSD”
button. The generated XSD will pop up on a new screen. Here you can choose to
either cancel or save the XSD. The generated XSD can be used to map the query
results in an integration scenario.

7.2 SOSL Query Editor

The SOSL Query Editor helps build and test well-formatted searches in the Salesforce
Object Search Language. It supports the building of searches for the Rest API. In a search
query, you can look for data in multiple objects, for example in both account and contact.

The SOSL Query Editor is the second tab in the Salesforce CPI Adapter Tool perspective,
as shown in Figure 7.6. The following steps show how to create a query with the SOSL
Query Editor and describe the sections and elements of the editor.

Figure 7.6 SOSL Query Editor

7.2.1 Objects and Fields

Objects and fields of objects can be selected in the left component of the SOSL Query
Editor. At the bottom of the component, there is a progress bar that will run when data is
retrieved from salesforce and prepared for display. This component is identical to the one
in the SOQL Query Editor described above.

30
 Salesforce Adapter Guide

1. Select the API version in the “Version” dropdown. The version is synchronized
between the different tabs. If a version is selected in another tab, this will be
automatically selected here.

2. The selection of an API is disabled, SOSL can only be used for the Rest API.

3. Optional: Search for the object you want to create a query for using the “Search
SObject…” field.

4. For example Type “acc” and the list below will only show objects with that letter
combination such as those with “account” or “access” in the name.

5. Click on the arrow in front of an object to load all the fields of the object.
Alternatively, the box in front of the object can be selected, this will load and select
all fields of that object.

6. Select the objects or specific fields you want to create a search for.

7.2.2 Search Options

The component on the top right of the SOSL Query Editor enables you to set different
search options. The different syntax elements have their own section, labeled accordingly.
See Figure 7.7.

Figure 7.7 Search Options Component

• In the FIND section, the user can type what they are looking for such as name,
number, or partial string. An entry is required for a search query.

• The IN section shows which fields are used for the search. The default setting
is “ALL FIELDS”. The dropdown allows for the selection of other options such as
“NAME” and “EMAIL FIELDS”.

31
 Salesforce Adapter Guide

• The RETURNING section is the largest of the component. It shows a subsection

for each selected Salesforce Object, for example, Account or Contact, and each
object has multiple query options. Which data to return can be set per object, the
following five points describe all options.

• The fields table displays the selected fields of an object.

o In the table, you can choose to format fields to local settings by ticking the
box. If a field is formatted it is possible to give it an alias.

o Select toLabel to translate the search result into the user’s language.

• In the ORDER BY section, the field to sort on can be selected. Default order is
ascending, selecting the DESC box puts the query results descending order.
Additionally, records without entry for the selected field can be placed at the bottom
of the query result by ticking the box NULLS LAST.

• The LIMIT section allows setting the limit of the search result set that is returned.

• In the OFFSET section, it is possible to set the starting row of the returned result
set.

• In the WHERE section, the field and operator can be selected for the statement.
Depending on the selected field, the input changes accordingly.

o Text fields facilitate free text input.

o For picklists fields, the input is a dropdown with all available options.

o Numeric fields allow only numbers.

o For DateTime fields, the input will split up into two parts: the first a calendar
to select the date from; the second an input field for a time. Alternatively,
you can choose to use time literals by ticking the box. The input will change
into a dropdown with time literals.

Select the NULL box if you want a query for records without value.

Additional WHERE statements can be added by pressing the plus sign on the right.
This will add a new row to create an extra statement. New rows will be preceded
with a dropdown to select AND/OR. To remove a row, click the minus sign on the
right of the row.

7.2.3 Results

The component located at the bottom right allows you to test the created query.
See Figure 32 for an overview of the component.

32
 Salesforce Adapter Guide

Figure 7.8 SOSL Result Component

• The text field on the left shows the created query. This query cannot be edited
manually; it can only be changed by the settings in the other components.

• Press Run Query to test the query and see if the results are as expected. It will
take some time to process this request, the button will indicate that the query is
running, and return to the original state when the query is finished.

• The Query Result tab on the right will be display the results in a table.

• If the query is not valid, the Syntax Check tab on the right can be consulted. This
displays additional information: the message and error code of the response.

• If the results are satisfactory, the query can be copied for use in the
Salesforce CPI Adapter. You can either press the “Copy Query” button that copies
the query to the clipboard, or select the query and copy it yourself.

An XSD for the query result can be generated by pressing the “Generate XSD” button. The
generated XSD will pop up in a new screen. Here choose to either cancel or save the XSD.
The generated XSD can be used to map the query results in an integration scenario.

7.3 XSD Generator

The XSD Generator is developed to support mapping operations in integration scenarios.

It generates request and response XSDs for multiple APIs that are specific for the
Salesforce instance: all custom objects are available in the list of Salesforce objects, and
all custom fields are included in all objects. The REST, Bulk, and Place Order APIs are
implemented. Available versions depend on the API. Apart from the query and search
operations that have been implemented in query builders, all operations that require a
payload are implemented. The left side of the view enables the selection of the version,
API, operation, and Salesforce object (if required). The right side of the view contains a
request and response tab that will show the resulting XSD (Figure 7.9). In case, not all
required fields have been selected, it will indicate which selection is needed. If an operation
has no XSD for a request or response, it will indicate this, Figure 7.9 gives an overview of
the different XSDs that can be generated.

33
 Salesforce Adapter Guide

Figure 7.9 XSD Generator overview with the request XSD as output

1. Select the API version in the Version dropdown.

2. Select the API in the API dropdown.

3. Select the operation in the “Operation” dropdown.

4. Only for Bulk API, Batch - Create: Select the operation of the Job in the
Job Operation dropdown.

5. Select a Salesforce Object if applicable. The Search SObject… field can be used
to filter the list of SObjects in the list below.

6. Click Save XSD to save the displayed XSD. Switch tabs to save the corresponding
response/request.

REST API

Operation Object specific Request Response

Metadata - All X
Metadata - Basic X X
Metadata - Comprehensive X X
Other - Get REST API Versions X
Other - Get REST Resource Endpoints X
Salesforce Object - Create X X X
Salesforce Object - Delete X
Salesforce Object - Delete with External ID X
Salesforce Object - Get X X
Salesforce Object - Get with External ID X X
Salesforce Object - Update X X X

34
 Salesforce Adapter Guide

Salesforce Object - Upsert with External ID X X X

Bulk API

Operation Object specific Request Response

Batch - Create - delete X X
Batch - Create - hard delete X X
Batch - Create - insert X X X
Batch - Create - query X X
Batch - Create - update X X
Batch - Create - upsert X X X
Batch - Get X
Batch - Get Request X X
Batch - Get Results X
Batch Query - Get Result X X
Batch Query - Get Result IDs X
Job - Abort X X
Job - Close X X
Job - Create X X
Job - Get X
Job - Get All Batches X

Place Order API

Operation Object specific Request Response

Account - Add Contracts and Orders X X
Account - Add Orders X X
Contract - Add Orders X X
Contract - Filter Details X
Contract - Get X
Order - Add Products X X
Order - Filter Details X
Order - Get X
Table 1 Overview of all operations, if they are specific for a Salesforce object and the XSDs that are generated

7.4 XSD Generator Aggregation/Composite

The XSD Generator Aggregation/Composite is developed to execute a series of REST API

requests in a single call. You can use the output of one request as the input to a subsequent
request. The response bodies and HTTP statuses of the requests are returned in a single
response body. The entire series of requests count as a single call toward your API limits.

35
 Salesforce Adapter Guide

The requests in a composite call are called subrequests. All subrequests are executed in
the context of the same user. In a subrequest’s body, you specify a reference ID that
maps to the subrequest’s response. You can then refer to the ID in the URL or body fields
of later subrequests by using a JavaScript-like reference notation.

You can specify whether an error in a subrequest causes the whole composite request to
roll back or just the subrequests that depend on it. You can also specify headers for each
subrequest.

1. Select the API version in the Version dropdown.

2. Click on Get SObjects to retrieve a list of SObjects for the specific Salesforce tenant.

3. Select the SObjects to be included in your Aggregation/Composite operation, for

example, Account and Contact.

4. Click Generate XSD to create the respective request XSD.

5. Click Save XSD to save the displayed XSD. Switch tabs to save the corresponding
response/request.

This component works with Salesforce API version 43.0 and later. Please find a detailed
explanation of the Aggregation/Composite operation in Section 9.4.

Figure 7.10 XSD Generator Aggregation/Composite overview with part of the selection on the left and resulting request XSD
on the right side

8 Support

In case of issues or errors, change the Log level of your integration flow to Traces. This
can be done in Cloud Platform Integration via the Monitor > Manage Integration Content
page. An example of such a configuration can be seen in Figure 8.1.

36
 Salesforce Adapter Guide

Figure 8.1 Activating Traces

The Trace Log level enables the collection of more traces that can be used to effectively
understand the problem. These traces can also be used in a ticket.

The next section discusses few issues that you might encounter and possible solutions for
them.

8.1 SSLHandshakeException

Error Message:

[Link]: [Link]:
PKIX path building failed:
[Link]: unable to find valid
certification path to requested target, cause:
[Link]: unable to find valid
certification path to requested target.

Possible Solution: This error generally means that in the Keystore of SAP CPI, an entry for
the root certificate of Salesforce is missing. At the time this document is published,
Salesforce expects a DigiCert Global Root certificate.

8.2 No Artifact Descriptor Found

Error Message:

[CAMEL][IFLOW][CAUSE]: Cause: [Link]:

[CONTENT][CONTENT_DEPLOY][NoArtifactDecriptorFoundForArtifactName]:No
artifact descriptor found for artifactName SalesforceOauth.

Possible Solution: This error generally indicates that one of the security artifacts used in
the Connection tab in the adapter does not exists. Ensure that the artifact used in the
connection tab exists as a Security Material.

37
 Salesforce Adapter Guide

8.3 There Are 2 Parameters That Couldn’t Be Set On The Endpoint

Error Message:

[CAMEL][IFLOW][CAUSE]: Cause: There are 2 parameters that couldn't be set on

the endpoint. Check the uri if the parameters are spelt correctly and that they are
properties of the endpoint. Unknown parameters=…

Possible Solution: This error generally indicates that the SOQL or SOSL Query format is
wrong. The Plugin can help format the Query. Possible solutions include replacing the ‘&’
sign to connect queries with _and_, or putting your query inside of the following text:
RAW({advanced query}).

8.4 Cannot Produce Target Element

Error Message:

[Link]:
[Link]: Cannot produce target
element /request/entry/name. Queue has not enough values in context. Target
xsd requires a value for this element, but target field mapping does not produce
one. Probably the xml-instance is not valid to the source xsd, or the target field
mapping does not fulfill the requirement of the target xsd., cause:
[Link].tf7

Possible Solution: This error generally indicates that the mapping requires a missing
mandatory value in the message body you are sending when creating or updating an
instance of an entity in Salesforce.

9 Sample Scenario Explained

In this section, three commonly used scenarios will be explained to show the use of the
adapter and the Eclipse Plug-in.

Requirements:

• SAP Cloud Platform Integration tenant

• Salesforce tenant

• Salesforce adapter

9.1 Initial Steps

All these scenarios start with the creation of an Integration Package and adding a new
Integration Flow. Find these initial steps below.

38
 Salesforce Adapter Guide

9.1.1 Create an Integration Package in SAP CPI

1. Launch SAP CPI Web application by accessing the URL provided by SAP.
2. If you are a new user, choose Signup.
3. If you have user credentials, choose Login.

Figure 9.1 SAP CPI – Home

4. Select and choose the Design tab.

5. Choose Create and insert the required data to create a new Integration Package.

Data Insert

Name New Integration Package

Version <Version>
Owned by <Owned By>
Description <Description>

Figure 9.2 SAP CPI - New Integration Package

39
 Salesforce Adapter Guide

9.1.2 Create and Add a New Integration Flow in SAP CPI

1. Choose Artifacts, select Add and select Integration Flow to add a new
integration flow as an artifact.
2. Select Create and enter the required data.

Data Insert

Create X
Name Test Process Integration
Description <Description>
Sender Sender
Receiver Receiver

Figure 9.3 SAP CPI - Add Process Integration Artifact

3. Choose OK to add the process integration artifact.

4. Choose Save to keep the integration package.

9.2 Synchronize Data

This scenario explains the synchronization of data via the Upsert capability in Salesforce.
It replicates a message coming from a sender system via a Timer component and a
Content Modified component and will either create or update respective records in receiver
system Salesforce.

9.2.1 Assign Timer Instead of Sender and Start Message

1. Click on the integration flow artifact name and choose Edit.

40
 Salesforce Adapter Guide

Figure 9.4 SAP CPI - Configuration Integration Flow

2. Select Sender and click Delete.

3. Select Start Message and click Delete.

Figure 9.5 SAP CPI – Select Events

4. Click on Events, and select the Timer, connect Timer and End Message.

Figure 9.6 SAP CPI – Start Timer

5. Add a Content Modifier and connect it to the Start Message.

41
 Salesforce Adapter Guide

Figure 9.7 SAP CPI - Add Content Modifier

6. Add a message containing Account data to the Content Modifier to replicate the
message coming from the sender. In this case, the message has the XML format.

7. Add an exchange property with the reference ID value (ID used for correlation of
the record between the two systems), for example ReferenceID.

Figure 9.8 Content Modifier – Exchange Property

9.2.2 Message Mapping Request

1. Subsequently add a Message Mapping element in order to map this incoming

message to the expected target message structure for Salesforce.

Figure 9.8 SAP CPI - Add Message Mapping

2. In Eclipse, select the XSD Generator, select the REST API, and then select the
Salesforce Object – Upsert with External ID Operation. Select Account under
the Salesforce Objects, and save the corresponding Request XSD file.

42
 Salesforce Adapter Guide

Figure 9.9 XSD Generator

3. Select the Message Mapping in the integration flow, and then select Create and
create a name.

Figure 9.10 Select Create

4. Upload the XSD Request file as the Target Message. The Source Message should
be configured with the XSD of the message of the sender.

Figure 9.11 Salesforce Object – Upsert with External ID – Account as Target XSD in message mapping

43
 Salesforce Adapter Guide

5. Map the two message structures from Source to Target using the Message Mapping
element.

9.2.3 Configure Receiver Salesforce Adapter in SAP CPI

1. Add a Request Reply to the integration flow after the Message Mapping.

Figure 9.12 Add Request Reply

2. Select Request Reply and choose the arrow to drag the pointer to Receiver.
Then, select the Salesforce Adapter.

Figure 9.13 Add the Salesforce Adapter

3. Select REST as the Type in the Processing tab of the Salesforce Adapter. Select
Salesforce Object – Upsert with Exernal ID as the Operation, and Account
as the Salesforce Object. Specify ${[Link]} in the External ID
Value field, and ReferenceID__c in the External ID Name field.

Figure 9.14 Salesforce Adapter Processing Tab

44
 Salesforce Adapter Guide

4. Select the Connection tab in the Salesforce Adapter and enter the required data
into fields Basic Credential Name and OAuth Credential Name. Next to this
provide the Security Token by referring to a secure parameter.

Figure 9.15 Salesforce Adapter Connection Tab

9.2.4 Message Mapping Response

1. Add another Message Mapping after the Salesforce Receiver Adapter and
connect them. In Eclipse, save the corresponding Response XSD (as generated
before together with the Request XSD) and add it as the Target Message and
click OK.
2. Select Message Mapping and then select the arrow to drag it to the End
Message.

9.2.5 Result of the IFlow

1. Save the IFlow as version and deploy the IFlow.

2. Depending on whether the ReferenceID exists or not, the Account will be updated
or created in Salesforce with the data present in the XML request message.

9.3 Query Data

9.3.1 Assign Timer Instead of Sender and Start Message

1. Click on the integration flow artifact name and choose Edit.

45
 Salesforce Adapter Guide

Figure 9.16 SAP CPI - Configuration Integration Flow

2. Select Sender and click Delete.

3. Select Start Message and click Delete.

Figure 9.17 SAP CPI – Select Events

4. Click on Events, and select the Timer, connect Timer and End Message.

Figure 9.18 SAP CPI – Start Timer

46
 Salesforce Adapter Guide

9.3.2 Configure Salesforce Receiver Adapter

1. Add a Request Reply to the integration flow after the Message Mapping.

Figure 9.19 Add Request Reply

2. Select Request Reply and choose the arrow to drag the pointer to Receiver.
Then, select the Salesforce Adapter.

Figure 9.20 Add the Salesforce Adapter

3. Select the Connection tab in the Salesforce Adapter and enter the required data
into fields Basic Credential Name and OAuth Credential Name. Next to this
provide the Security Token by referring to a secure parameter.

Figure 9.21 Salesforce Adapter Connection Tab

47
 Salesforce Adapter Guide

4. In the Processing tab select for operation SOQL – Execute Query and Payload
Format: Application/XML.

Figure 9.22 Salesforce Adapter Processing Tab – SOQL – Execute Query

9.3.3 Create SOQL Query

1. In Eclipse, select the SOQL Query Editor, select the REST API. Select Account
under the Salesforce Objects, and click on Copy Query.

Figure 9.23 SOQL Query Editor

2. Copy the query into the SOQL Query field in the Salesforce Adapter.

Figure 9.24 SOQL Query

48
 Salesforce Adapter Guide

9.3.4 Message Mapping Response

1. In Eclipse, click on Generate XSD and Save XSD to create and save the XSD for
the response mapping for the create SOQL query.
2. Add a Message Mapping.

Figure 9.25 SAP CPI - Add Message Mapping

3. Use the generated XSD as Source Message (and for test purposes also as Target
Message) and click OK.

Figure 9.26 SAP CPI – Add XSD as Source Structure

4. Select Message Mapping and then select the arrow to drag it to the End
Message.

9.3.5 Result of the IFlow

1. Save the IFlow as version and deploy the IFlow.

2. The IFlow will return the data output matching the result of the query in Salesforce
on the exchange body. This body can be used as input in the next step in the IFlow
to complete the scenario.

49
 Salesforce Adapter Guide

9.4 Composite Call

The Composite operation supports using multiple SObject records and multiple SObject
types in one operation. It is applicable in an integration scenario where you would like to
create one account and two contacts within the same message to Salesforce.

9.4.1 Assign Timer Instead of Sender and Start Message

1. Click on the integration flow artifact name and choose Edit.

Figure 9.27 SAP CPI - Configuration Integration Flow

2. Select Sender and click Delete.

3. Select Start Message and click Delete.

Figure 9.28 SAP CPI – Select Events

4. Click on Events, and select the Timer, connect Timer and End Message.

50
 Salesforce Adapter Guide

Figure 9.29 SAP CPI – Start Timer

5. Add a Content Modifier and connect it to the Start Message.

Figure 9.30 SAP CPI - Add Content Modifier

6. Add a message containing Composite data to the Content Modifier, to replicate this
message coming from the sender. In this case, the message has the XML format.
Find an example of a start of a composite message below.

Figure 9.31 Content Modifier – Composite body

7. To have an overview of how the message structure for a Composite message is

organized, use the XSD Generator Aggregation/Composite tool or refer to the
Composite Instructions Salesforce.

51
 Salesforce Adapter Guide

9.4.2 Message Mapping Request

1. Add a Message Mapping.

Figure 9.32 SAP CPI - Add Message Mapping

2. In Eclipse, select the XSD Generator Aggregation/Composite, Select Account

and Contacts under the Salesforce Objects, and save the corresponding Request
XSD file.

Figure 9.33 XSD Generator

3. Select the Message Mapping in the integration flow, and then select Create and
create a name.

52
 Salesforce Adapter Guide

Figure 9.34 Select Create

4. Upload the XSD Request file as the Target Message (and for test purposes also
as the Source Messge).
5. Map the two messages structures from Source to Target using the Message
Mapping element.

9.4.3 Configure Receiver Salesforce Adapter in SAP CPI

1. Add a Request Reply to the integration flow after the Message Mapping.

Figure 9.35 Add Request Reply

53
 Salesforce Adapter Guide

2. Select Request Reply and choose the arrow to drag the pointer to Receiver.
Then, select the Salesforce Adapter.

Figure 9.36 Add the Salesforce Adapter

3. Select REST as the Type in the Processing tab of the Salesforce Adapter. Select
Salesforce Object – Composite as the Operation.

Figure 9.37 Salesforce Adapter Processing Tab

4. Select the Connection tab in the Salesforce Adapter and enter the required data
into fields Basic Credential Name and OAuth Credential Name. Next to this,
provide the Security Token by referring to a secure parameter.

Figure 9.38 Salesforce Adapter Connection Tab

9.4.4 Result of the IFlow

1. Save the IFlow as version and deploy the IFlow.

54
 Salesforce Adapter Guide

2. Depending on whether the external IDs mentioned in the individual calls exist or
not, the Account and/or Contact SObjects will be updated or created in Salesforce
with the data present in the request message.

9.5 Monitor and Test Integration Flow in SAP CPI with Salesforce

9.5.1 Monitor Integration Flow in SAP CPI

1. After deploying an integration flow select and choose the Monitor tab to see
whether the integration flow started successfully.

Figure 9.39 SAP CPI – Monitor

2. Select the started integration flow in Manage Integration Content to see details.
This provides an overview of all the messages and IFlows that successfully started
or gave an error.

Figure 9.40 SAP CPI - Integration Content

3. You can add a Groovy Script after to log the body payload in the Message Monitor.
Select the Groovy Script, click Create and add the following script:

import [Link];
import [Link];

def Message processData(Message message) {

def body = [Link]([Link]) as String;

def messageLog = [Link](message);

if(messageLog != null){
[Link]("Salesforce Payload Response:", body, "application/xml");

}
return message;
}

55
 Salesforce Adapter Guide

Figure 9.41 Groovy Script

9.5.2 Monitor Message Processing in SAP CPI

1. After deploying an integration flow select and choose the Monitor tab to see
whether the integration flow started successfully.

Figure 9.42 SAP CPI – Monitor

2. Filter on the started integration flow in Manage Message Processing to see

message details. This provides an overview of all the messages for the selected
IFlow.

Figure 9.43 SAP CPI - Message Processing

3. Here the message status, properties, logs and attachment will be visible.

56
 Salesforce Adapter Guide

Figure 9.44 SAP CPI Message Monitor – Message processing details

10 References
10.1 Initialize OAuth 2.0 in Salesforce

1. The Login URL is the login URL that is used by the authorization server of
Salesforce. In the online documentation of Salesforce this URL is specified as
[Link] This link directs the Salesforce adapter to the login
page of Salesforce to authorize.
2. The Basic Credential Name refers to an alias of a Username and Password
combination stored in the SAP Cloud Platform Integration Secure Store. This is the
exact Username and Password you use to login at the Salesforce console.
3. Open Monitor tab in SAP Cloud Platform.
4. Select Security Material in the section Manage Security Material.

Figure 10.1 SAP Cloud Platform Integration - Security Material

5. Select Add, select User Credentials and enter a Name which should be the same
as the Basic Credential Name you configure in the Salesforce adapter
Authentication tab. In User and Password fields fill in the username and password
you use to log in to the Salesforce console. Select Deploy.

57
 Salesforce Adapter Guide

Figure 10.2 Add User Credentials for Basic Authentication

6. For the Security Token and OAuth Credentials an app needs to be create in the
Salesforce tenant. Login to your Salesforce console and select Setup.
7. On the left panel in the Build overview, select Create, select Apps and select New
for the Connected Apps section.

Figure 10.3 Create Salesforce App

8. In the next screen fill in basic details such as App Name, API Name and Contact
Email. In the API (Enable OAuth Settings) select Enable OAuth Settings.
9. Select Enable OAuth Settings.
10. Unselect Enable for Device Flow.
11. Fill in a Callback URL.
12. Select Use digital signatures.
13. Set Selected OAuth Scopes to Full access (full).
14. Select Require Secret for Web Server Flow.
15. Unselect Include ID Token.
16. Unselect Enable Asset Tokens.
17. Select Save to complete the creation of the app.

58
 Salesforce Adapter Guide

Figure 10.4 Salesforce API Enable OAuth Settings

18. In the next overview and when you select the specific connect app, you can find
the Client ID and Client Secret, in the respective Consumer Key and Consumer
Secret fields.

Figure 10.5 OAuth Setting of the app

19. Deploy this Client ID and Client Secret as User Credentials similarly as done in
step 2 of Section 10.1. Create a new Credential Name and fill in Client ID as
User and Client Secret as Password.
20. In case the IP address of SAP Cloud Platform Integration is not whitelisted in the
settings of Salesforce you need a Security Token. In case you have not received
the security token via email yet, you can direct to My Settings select Personal
and select Reset My Security Token to receive a new security token.

59
 Salesforce Adapter Guide

Figure 10.6 Obtaining the Security Token

21. To deploy the Security Token, select Security Material in the section Manage
Security Material. Select Add and then select Secure Parameter.
22. Fill in the Secure Parameter Name which should match the Security Token
Name used in the Salesforce adapter. Fill in the Security Token in the Secure
Parameter field and select Deploy.

Figure 10.7 Deploy Security Token as a Secure Parameter

23. Every required security detail is successfully deployed for a secure OAuth 2.0
Autonomous Client connection for the Salesforce adapter. It is important that the
names configured for Basic Credential Name, Security Token and OAuth
Credential Name match the names of the deployed artefacts in the SAP secure
stores as described in the steps above. Now the authentication part is completed,
the Salesforce adapter can be configured for every specific Salesforce integration
scenario.

60
 Salesforce Adapter Guide

10.2 Composite Instructions Salesforce

Executes a series of REST API requests in a single call. You can use the output of one
request as the input to a subsequent request. The response bodies and HTTP statuses of
the requests are returned in a single response body. The entire series of requests counts
as a single call toward your API limits.

The requests in a composite call are called subrequests. All subrequests are executed in
the context of the same user. In a subrequest’s body, you specify a reference ID that
maps to the subrequest’s response. You can then refer to the ID in the url or body fields
of later subrequests by using a JavaScript-like reference notation.

For example, the following composite request body includes two subrequests. The first
creates an account and designates the output as refAccount. The second creates a contact
parented under the new account by referencing refAccount in the subrequest body.

1. {
2. "compositeRequest" : [{
3. "method" : "POST",
4. "url" : "/services/data/v50.0/sobjects/Account",
5. "referenceId" : "refAccount",
6. "body" : { "Name" : "Sample Account" }
7. },{
8. "method" : "POST",
9. "url" : "/services/data/v50.0/sobjects/Contact",
10. "referenceId" : "refContact",
11. "body" : {
12. "LastName" : "Sample Contact",
13. "AccountId" : "@{[Link]}"
14. }
15. }]
16. }

You can specify whether an error in a subrequest causes the whole composite request to
roll back or just the subrequests that depend on it. You can also specify headers for each
subrequest.

Composite is supported for the following resources.

• All sObject resources (vXX.X/sobjects/), including sObject Rows by External ID

• The Query resource (vXX.X/query/?q=soql)
• The QueryAll resource (vXX.X/queryAll/?q=soql)
• The SObject Collections resource (vXX.X/composite/sobjects). Available in API
version 43.0 and later.

You can have up to 25 subrequests in a single call. Up to 5 of these subrequests can be

sObject Collections or query operations, including Query and QueryAll requests.

61