Consuming Employee Central OData Services with Java
Table of Contents
2. Getting Started
3. Setup Eclipse
4. Http Client
This article is the first in a three-part series that will show you how to consume (read only) an Employee Central (EC) OData Service with support of the Olingo library, the OData4j library or the http Client. We will demonstrate the use of common OData features such as $filter, $select, $expand using these libraries.
OData is an OASIS standard which enables the creation and consumption for RESTful APIs. For more information on OData, check out: http://www.odata.org/.
For the sandbox system, we will be using salesdemo4, an OData service for the HR Cloud offering of Successfactors, a SAP company, containing a suite of applications for your most demanding HR-processes.
Let’s understand how we can do this using a simple query using first name, last name, date of birth and, country of birth. To complete this example, there are certain steps that must be performed before executing the query. These are described in Sections 2 and 3.
In this three-part series, we will look at how you can consume Employee Central OData APIs in Java. This first part covers general information and the usage of HTTP Client, the second part will cover the OData4j library and the third part will cover the Olingo library.
This documentation includes snippets of source code that show you how to create a basic query. You can view the full source at: http://www.sdn.sap.com/irj/scn/index?rid=/library/uuid/a0b41a7b-8ddc-3210-5e81-f9c9cddc9ec1
Before starting consumption in Java, ensure your OData APIs can be consumed by a REST client. You can use a tool like the “Advanced REST Client” in Google Chrome
for details see:
2. Getting Started
This output template shows a query example. In the field personIdExternal field, you specify the external ID of an employee in Employee Central. Next, you choose the library to use. You can choose between Http Client, OData4j or Olingo as library to query. This example shows Olingo. Click the “GO!” Button to get your results for the two templates below. This example shows personal and biographical information of the user with the personIdExternal “cgrant1”.
This template shows the OData hierarchy of the example. For more information on the structure of EC OData APIs, check out: http://help.sap.com/hr_api/ and refer to the section Employee Central Entity Relationships.
To mimic logging in by the UI, the server needs information about username, company and password. You need to encode these three in the following format: <username>@<company>:<password> with Base64.
For example root@ACE:secret results in cm9vdEBBQ0U6c2VjcmV0.
Simple OData call
This example shows a simple OData call in Google Chrome Advanced Rest Client and its result.
This call filters the personIdExternal as “cgrant1” and selects the fields “firstName” and “lastName”.
The following snippet shows the result in JSON format.
The subsequent examples will illustrate how you can consume OData in Java. These examples show how you can use OData features like expand, filter and select to specify your query.
- Install Eclipse IDE for Java EE (e.g. Kepler):
- Install Java SDK :
- Download the OData4j library and extract the files:
- Download the Olingo library for OData2 and extract the files:
- Copy the folder <<program.zip>> to your workspace folder and import it via “Existing projects into Workspace”
- Add the downloaded OData4j Bundle and the downloaded Olingo Bundles to “Libraries” by right clicking on the project and selecting properties –> Java Build Path –> libraries
- If you work in a secured network it might be necessary to configure your proxy settings. Right click your project and select properties –> Run/Debug Settings –> select your project –> Edit –> Arguments –> enter the following VM arguments:
These arguments apply only for people on a SAP network.
- Configure your login details in the source code. You can find necessary Strings in the class QueryParams. You need to set the USER in the format <user@company> and save your password as the String PW.
Now you should be able to build the program and execute it!!
4. HTTP Client
The HTTP Client is probably the easiest way for simple OData APIs queries. The steps are as follows:
1. Define a connection
2. Send a call
3. Analyze the response xml file and parse it to the output
The HTTP Client works without using the metadata structure. This has several consequences. If you only want to query small amounts of data it’s faster than the other two presented possibilities because you don’t have to download the metadata first.
Another issue is that you have to know the exact XML structure to create the URL you want to query. So, it is pretty complicated because the XML structure is not equivalent to the OData structure.
This code snippet shows how to define the connection with the server.
This snippet shows how to send a call based on the prepared connection. The Response is in XML format, so you use its nodes to navigate through its structure to get the required information. If a non-existing personIdExternal is typed, the method throws an exception.
I hope this blog entry will help you to understand how to do the first steps to consume OData with Java.
I’m interested in your feedback on this functionality!
Best Regards Jonas