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.
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:
- 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 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.
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.
https://<data center>.successfactors.com/odata/v2/$metadata
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.
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:
