Hands-On – Testing Integration with SuccessFactors OData API
For those looking for light-weight connection option with SuccessFactors, OData API is the answer. OData (Open Data Protocol) is built on protocols like HTTP following the REST methodologies for data transfer. With OData API, SuccessFactors is leading the league in providing Rest-ful integration services for your HR data in cloud. SuccessFactors uses OData for extracting most data entities. However, there is still some crucial sets of data accessible only through SFAPI for which OData API is still not an option.
This document will walk you through the process of testing OData API using a rest client. For testing purposes, I am using Postman – a free REST client available as a Chrome Browser extension. You may access Postman here.
Note: The authorization available to OData API user is pretty extensive and therefore this demo can help the tester to extract a lot of critical employee data. Please restrict the OData access and use it wisely.
- Enable Odata API in Provisioning.
- Create SFAPI user in Provisioning.
- Provide Role Based Permission (RBP) authorization to the SFAPI user. If you are not using RBP, you may use User based permission.
- Postman or any other REST client.
SuccessFactors URLs or endpoints are specific to data centers. You should always use the URL specific to your data center.
One of the authentication methods OData uses to access data is HTTP Basic Authentication. HTTP Basic Authentication requires the authorization header organized in a certain way:
“Username@CompanyID:Password”. The Company ID is your unique Company ID which you use to log into your SuccessFactors instance. Once the header is created, it is encoded in Base64 before being sent over.
1. The first step is to configure add the URL and the Basic Authentication header. Use the ‘Normal’ tab to enter the URL.
2. Use the ‘Basic Auth’ tab to enter the credentials. Once done, click on Refresh Headers which adds the Base64 format of header to your request. Note that as mentioned in the ‘OData Authentication’ section above, you don’t need to put an explicit colon between CompanyID and Password for Postman client. This client automatically adds a colon before converting the entire header to Base64.
3. Once the Basic Auth details are entered, the configuration is complete to request the first set of data. The removed section in Red below is the Base64 format of the authentication header.
4. The list of entities to access data can be retrieved using $metadata operation.
Examples and Tips
- To retrieve a specific entity, use the following link:
- e.g. to retrieve Positions, which is one of the most sought after EntitySet for integration with SuccessFactors, use the following link.
- It is important to restrict the amount of data retrieved by each OData call. A browser based client like Postman may also hang due to big data sets. Therefore $filter is an important keyword. This allows to query a subset of data based on certain condition. You may use operator like eq (equals), lt (less than), Gt (greater than), Ge, Le, And, Or and so on. For extracting Position data for a specific Position code, you may use this:
https://<data center>.successfactors.com/odata/v2/Position?$filter=code eq ‘xxxxxx’
- One of the very handy keyword you will be using for your real life projects will be the use of $expand keyword. When you extract data using OData API, you will quickly realize that data is missing in some of the fields. Sticking to Postion data example, parentPosition field when retrieved will appear blank as shown below. This is by design as these missing fields are actually linked to Position and $expand allows inline retrieval of this data.
The usage of $expand shown below has the output as displayed:
https://<data center>.successfactors.com/odata/v2/Position?$filter=code eq ‘xxxxxx’&$expand=parentPosition
- Multiple such fields separated by comma can be used for $expand. e.g. $expand=parenPosition,jobLevel etc.
The OData call can be monitored in SuccessFactors instance -> Admin Tools -> OData API Audit Log:
Also see: Hands-On – Testing Integration with SuccessFactors SFAPI
Hi Prateek, thanks for tutorial, I could able to get data with mentioned steps.
Is there a way to find request odata/xml envelop as I’m trying to add this in application to pull data.
--Thanks got this working with curl
I just started working on HCI and was wondering how to get the the wsdl for custom integration scenarios, what i understood from this blog is for odata we can get the wsdl from https://<data center>.successfactors.com/odata/v2/$metadata, and when we login with our customer instance so we will obviously get the wsdl of our particular system. Am i right.
And can you please suggest how to get wsdl for SFAPI, this link https://api4.successfactors.com/sfapi/v1/soap?wsdl does not asks for login credentials so how can we get wsdl(including custom fields) of our customer instance.
I was checking this blog for updates. Using wsdl (i.e SF APIs with SOAP ) you will have to send login details as a request. You can refer below link which has reference for wsdl
if you are using this for application interfacing, you will have to use login function which provides a session ID. This ID will be required to make any further successful requests.
I am curious, with the ODataAPI is there a way to filter what you receive? We as a company don't want to be liable to see a lot of the data, just some pieces. What would you advise?
Yes you can mention the filters with '$filter' parameter while requesting for the data. Please find below sample Odata URI with filter.
https://api10.successfactors.com/odata/v2/Attachment?$filter="attachment_id eq 12345L"
Option for filtering with key field.
You will have to refer Odata structure to know which fields are defined to be filtered.
You can make it effective with option to select limited columns using $select.
Another way is to add user based access control. Provide limited access.
Hope this helps !