SAP Cloud Platform Integration with OData API

Document History
Version No. Date Revision Description

0.1 31-Oct-2021 Draft

0.2 3-Nov-2021 Review

1.0 8-Nov-2021 Final version

Document Asset Team

Name Email

Abhijeet Routray abhijeet.routray@accenture.com

Madhuri Duggirala madhuri.duggirala@accenture.com

Vishwajeet Ahluwalia Vishwajeet.ahluwalia@accenture.com

Amit Kumar Jain amit.c.kumar.jain@accenture.com

Machindra Patade machindra.patade@accenture.com

Abhijeet Routray
Contents
1. Introduction ...................................................................................................................................... 2
2. Overview ........................................................................................................................................... 2
3. OData Operations ............................................................................................................................. 3
4. Composing the OData URI ................................................................................................................ 4
5. Querying with key predicate and system query options .................................................................. 5
6. Configuring SuccessFactors Adapter using message protocol OData V2 ......................................... 6
7. OData API Dictionary ...................................................................................................................... 13
8. Conclusion ....................................................................................................................................... 13
9. References ...................................................................................................................................... 13

pg. 1 Copyright © Accenture 2018 All Rights Reserved

 1. Introduction
With the help of this document, you'll get to know what is OData API, see some sample queries as well
as use cases, and other information.
OData (Open Data Protocol) defines a set of best practices for building and consuming RESTful APIs.
OData helps you focus on your business logic while building RESTful APIs without having to worry
about the various approaches to define request and response headers, status codes, HTTP methods,
URL conventions, media types, payload formats, query options, etc. We are proud to serve on the
OData Technical Committee

2. Overview
Open Data Protocol (OData) is a standardized protocol for creating and consuming data APIs. OData
builds on core protocols like HTTP, and commonly accepted methodologies like REST. The result is a
uniform way to expose full-featured data APIs. OData provides both a standard for how to represent
your data and a metadata method to describe the structure of your data, and the operations available
in your API. SuccessFactors OData API service is based on OData V2.0.

What is the need of OData API?

As APIs continue to explode, each organization exposes its own unique REST/SOAP/Bulk APIs for
consuming their data. And some of them also come up with their own unique query language such as
ROQL (Oracle Service Cloud), SOQL (Salesforce), etc. This makes it difficult for an enterprise and its
development team to be able to learn and code against all these different APIs.

This is where OData is very useful. OData advocates a standard way of implementing REST APIs that
allows for SQL-like querying capabilities using these RESTful APIs. OData is essentially SQL for the web
built on top of standard protocols – HTTP, JSON & ATOM – while leveraging the REST architecture
style.

API Endpoint URL:

Your endpoint URLs for accessing the OData APIs depend on the data center hosting your SAP
SuccessFactors instance. Your SAP SuccessFactors support representative can tell you the data center
location to use for your instance.

Below is an example of a list of data centers with location and time zone information:

Environment Location Time Zone UTC API Server

DC2 Production Amsterdam, The CEST UTC+0200 https://api2.succe
Netherlands ssfactors.eu/
DC2 SalesDemo Amsterdam, The CEST UTC+0200 https://apisalesde
Netherlands mo2.successfacto
rs.eu/
DC2 Preview Amsterdam, The CEST UTC+0200 https://api2previ
Netherlands ew.sapsf.eu/

pg. 2 Copyright © Accenture 2018 All Rights Reserved

DC4 Production Chandler, EDT UTC-0400 https://api4.succe
Arizona, US ssfactors.com/
DC4 SalesDemo Chandler, EDT UTC+0000 https://apisalesde
Arizona, US mo4.successfacto
rs.com/

Authentication for OData API

The OData API provides the following two types of authentication:

• HTTP Basic Authentication (Basic Auth)

Basic Auth requires users to have admin access to the OData API and have valid accounts with
usernames and passwords. OAuth 2.0 lets all users log in regardless of whether they are SSO
users, so long as they have a valid token, and the OAuth client is registered.

To log in with Basic Auth, you must have the Allow Admin to Access OData API through Basic
Authentication permission.

The authorization header of Basic Auth is constructed in the following way:

1. Username, company ID, and password are combined into a string as such:
username@company ID:password
2. The resulting string literal is then encoded using Base64.
3. The authentication method ("Basic") followed by a space is then put before the encoded
string. For example, Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
• Authentication using OAuth 2.0
OAuth 2.0 lets all users log in regardless of whether they’re SSO users. If you’re planning to use
OAuth 2.0 for authentication, you must set up the required permissions and then register your
OAuth client application.
To be able to register your OAuth2 client application, you must have the Manage OAuth2 Client
Applications permission under Manage Integration Tools in Role-Based Permissions.
After you're granted the permission, you can use the Manage OAuth2 Client Applications tool to
register and manage client applications. The tool is available under Admin CenterAPI Center.

3. OData Operations
The OData API is a standardized protocol for accessing a database. The Entities in the API are described
in the metadata document. Accessing the Entities is as simple as knowing the entity name, and then
referencing the entity through an HTTP call. For example, all SuccessFactors HCM Suite solutions have
a User Entity that represents a user account. To query all the users in a system, you type the URL
https://<hostname>/odata/v2/User

A query can be more complex by including filtering, paging, sorting, and joining of entities (known as
expanding in OData).

pg. 3 Copyright © Accenture 2018 All Rights Reserved

 OData protocol allows the service provider to decide which operations are supported. In SAP
SuccessFactors HCM Suite, the supported operations vary by entity. For example, the system does not
allow user accounts to be deleted. User accounts can be removed from use only by setting them as
inactive. Therefore, the User entity does not support the delete operation.

4. Composing the OData URI

In OData, a URI has the following structure:
http://<hostname>/odata/v2/EntitySet[(KeyPredicate)][/NavPropSingle][/NavPropCollection][/C
omplex Type][/Property]

• EntitySet: Name of the OData API entity. An entity set represents the resource exposed by the
OData API.
• KeyPredicate: A predicate that identifies the key property of the entity. If an entity has a single
key property, the key predicate may only include the value of the property. If the entity has a
composite key, that is, the entity has multiple key properties, the key predicate must include the
key/value pairs to identify an entry. For more information, see Querying with Key Predicate
[page 40].
Note that when a key predicate is present in a URI, the $filter query option will be disregarded.
• navPropSingle: The name of a navigation property defined by the entry associated with the
prior path segment. The navPropSingle must identify a single entity (that is, have a "to 1"
relationship).
• NavPropCollection: Same as NavPropSingle except it must identify a collection of entries (that is,
have a "to many" relationship).
• ComplexType: The name of a property of the entity or complex type associated with the prior
path segment.
• Property: The name of a property of the entity or complex type associated with the prior path
segment.

The following table contains examples of a URI and a description of its composition:

Sample URI Description

http://<hostname>/odata/v2/User
• Identifies a User Collection.

http://<hostname>/odata/v2/User('1')
• Identifies a single User entry with key
value 1.

http://<hostname>/odata/v2/User('1')/usernam
e • Identifies the username property of the
User entry with key value 1.

http://<hostname>/odata/v2/User('1’)/proxy('1’ Same as the URI above but identifies the raw

)/hr/username/$value value of the username property.

pg. 4 Copyright © Accenture 2018 All Rights Reserved

 5. Querying with key predicate and system query options
A URI with key predicate identifies only one entry from the specified OData resource. Therefore, when a
key predicate is present in a URI, the following system query options will be disregarded:

• $filter
• $top
• $skip
• $orderby

$filter:
You can use the $filter system query option in the URI to limit the number of results returned in an
OData API query. For example, the following URI filters the status field in the User entity to return all
active users:

https://<API-Server>/odata/v2/User?$filter=status eq 't'

$orderby:
Below is an example of the $orderby system query option used in a URI.

EXAMPLE URI DESCRIPTION

https://<API- All User Entries are returned in ascending order
Server>/odata/v2/User?$orderby=username or when sorted by the username Property.
https://<API-
Server>/odata/v2/User?$orderby=username asc

https://<API- Same as the URI above, except the set of User

Server>/odata/v2/User?$orderby=username,hr/ Entities is subsequently sorted in descending
username desc order by the username property of the related
hr entry.
$top:

Below is an example of the $top system query option used in a URI.

EXAMPLE URI DESCRIPTION

https://<API-Server>/odata/v2/User?$top=5 The first 5 User entries are returned, and the
entries are sorted using a schema determined
by the OData service.
https://<API- The first 5 User entries are returned in
Server>/odata/v2/User?$top=5&$orderby=user descending order and sorted by the username
name desc property.

$skip:

pg. 5 Copyright © Accenture 2018 All Rights Reserved

Below is an example of the $skip system query option used in a URI.

EXAMPLE URI DESCRIPTION

https://<API- The set of proxy Entries (associated with the
Server>/odata/v2/User(1)/proxy?$skip=2 User Entry identified by key value 1) starting
with the third User.

https://<API- The third and fourth User Entries from the

Server>/odata/v2/User?$skip=2&$top=2&$orde collection of all User entities when the
rby=username collection is sorted by username in ascending
order.

6. Configuring SuccessFactors Adapter using message protocol OData V2

The below Iflow demonstrates the use of SuccessFactors adapter to fetch data using OData API. There
are several operations permitted using this adapter, Operation Query(GET) has been explored using the
below iflow.

1. Start Timer: Timer start event is used for triggering the iflow without using any sender at the
start.

pg. 6 Copyright © Accenture 2018 All Rights Reserved

 2. Request Reply: Data is fetched from SuccessFactors system using SuccessFactors Adapter with
OData V2 message protocol.
3. Receiver: This is the receiver system for connecting to SuccessFactors.
4. Content Modifier: used to store the data received from the previous step.

Adapter Configurations:

Address: URL of the SuccessFactors data center that you're connecting to. You can browse and select a
SuccessFactors data center URL by using the Select option.

Address Suffix: The field is auto populated with /odata/v2. Don't edit the field.

Proxy Type: Use Proxy Type as Internet, other options are irrelevant for this adapter.

In this iflow we are fetching data from SuccessFactors, hence operation ‘Query’ has been configured.

Query option(OData query) is auto populated once step 2 is complete in the pop up.

pg. 7 Copyright © Accenture 2018 All Rights Reserved

Upon clicking on Select button of Resource Path, the new query wizard will pop-up

You could observe that the Address field has been pre-populated by reading the Address value of
adapter specific details. All other configurations will also get auto populated.

Once the connection is successful, entity selection step will be displayed.

You can select or type the entity name, e.g.perPersonal. Let the operation be Query(GET). Furthermore,
you are required to select the required fields from the particular entity.

Based upon your selected fields, query will be automatically generated in the query table as shown
below.

pg. 8 Copyright © Accenture 2018 All Rights Reserved

Functionalities of ‘Top’ and ‘Skip’ are already explained above. Please find some examples below.

Once done, you can move on to step 3 for configuring filter and sorting functionalities of which are
explained above. Please find below example.

pg. 9 Copyright © Accenture 2018 All Rights Reserved

Based upon you filter and sort criteria your final query will be as below.

Once done, click on finish to continue with further processing and configuring with the below
parameters of the adapter.

Parameter Description

Operation Details Operation that you want to perform on the SuccessFactors

OData V2 service. Supported operations are:

Query (GET)

Create (POST)

pg. 10 Copyright © Accenture 2018 All Rights Reserved

 Update (PUT)

Read (GET)

Delete

Upsert (POST)

To leverage all operations, always use the latest version of the

adapter.

Resource Path Path of the resource (entity) that you want to perform the
operation

Fields(only for PUT and The fields in the entity that you want to modify.
POST operations)

Query Options Additional options that you want to add to the query
like $top or how to order the results using orderby. You can
(only for GET operations)
add this using the Model Operation Wizard.

Enable Batch Processing Select to perform multiple operations in one request to the
OData V2 service in the $batch mode.
(only for POST – UPSERT
operation)

Custom Query Options Query options that are specific to the SuccessFactors OData V2
service like purge.

Content Type(only Select one of the following content options:

for PUT and POST operat
Atom
ions)
JSON

Content Type Encoding Select one of the options. You can either encode the content
using UTF-8 or not encode the content.
(only
for PUT and POST operat None
ions)

pg. 11 Copyright © Accenture 2018 All Rights Reserved

 UTF-8

Pagination Allows you to set the type of pagination for your query results.

(only for GET – QUERY By default, the value is set to Server Snapshot-Based which is
operation) the recommended value for integration scenarios. The other
values are:

Client: For UI Application-based Integrations.

Server Cursor-Based

Page Size Maximum number of records in one page of results fetched

from the service. If set to Zero or empty, it fetches the default
(only for GET operation)
page size.

The value is set to Empty by default.

Note

It's recommended to leave the value Empty.

Retry on Failure This option enables you to mitigate intermittent network

issues. If there are network issues, you enable the integration
flow to retry connecting to the SuccessFactors OData V2
service. The system retries connection every 3 minutes for a
maximum of 5 times. The retry happens for the following
scenarios:

Upsert: For 412 inner error code along with HTTP response
code 200

Query Operations: Retry happens for 502, 503, 504 HTTP

response codes corresponding to Create, Update, and Delete
operations respectively.

Process in Pages The message is processed in pages of size defined in the Page
Size field.
(only for GET – QUERY
operation)

pg. 12 Copyright © Accenture 2018 All Rights Reserved

 Timeout (in min) Maximum time the system waits for a response before
terminating the connection.

Output Payload:

7. OData API Dictionary

The OData API dictionary contains all the entities available in your instance, it lists the allowed
operations, the field (property name), the label as well as telling you which fields are required or not. To
view the OData dictionary, you.

1. Navigate to the SuccessFactors Admin Center and search for the OData API Data Dictionary.
2. The OData API Data Dictionary is displayed.

8. Conclusion
The document provides an overview on how data can be fetched using OData API in SAP cloud
Integration.

9. References
• https://help.sap.com/viewer/368c481cd6954bdfa5d0435479fd4eaf/Cloud/en-
US/d16dd12c5c5649e99c8939879a77f9c0.html
• https://help.sap.com/doc/a7c08a422cc14e1eaaffee83610a981d/2111/en-
US/SF_HCM_OData_API_DEV.pdf
• https://blogs.sap.com/2019/08/12/odata-service-in-cpi-for-beginners/
• https://help.sap.com/doc/74597e67f54d4f448252bad4c2b601c9/2111/en-
US/SF_HCM_OData_API_REF_en.pdf

pg. 13 Copyright © Accenture 2018 All Rights Reserved