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.

Prerequisites:

  1. Enable Odata API in Provisioning.
  2. Create SFAPI user in Provisioning.
  3. Provide Role Based Permission (RBP) authorization to the SFAPI user. If you are not using RBP, you may use User based permission.
  4. Postman or any other REST client.

SuccessFactors URL:

SuccessFactors URLs or endpoints are specific to data centers. You should always use the URL specific to your data center.

https://salesdemo4.successfactors.com/odata/v2 Or

https://<data center>.successfactors.com/odata/v2

OData Authentication

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.


Postman Configuraiton

  1. The first step is to configure add the URL and the Basic Authentication header. Use the ‘Normal’ tab to enter the URL.

O1.jpg

  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.

O2.jpg

  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.

O3.jpg

  4. The list of entities to access data can be retrieved using $metadata operation.

https://<data center>.successfactors.com/odata/v2/$metadata

O4.jpg


Examples and Tips

  • To retrieve a specific entity, use the following link:

          https://<data center>.successfactors.com/odata/v2/EntitySetName

  • e.g. to retrieve Positions, which is one of the most sought after EntitySet for integration with SuccessFactors, use the following link.

          https://<data center>.successfactors.com/odata/v2/Postion

  • 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.

O5.jpg

        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

O6.jpg

  • 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:

O7.jpg

Also see: Hands-On – Testing Integration with SuccessFactors SFAPI

To report this post you need to login first.

4 Comments

You must be Logged on to comment or reply to a post.

  1. Sunit Save

    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

    (0) 
  2. Manu Bhutani

    Hi Prateek,

    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.

     

    Regards

    (0) 
  3. North McCormick

    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?

    (0) 

Leave a Reply