What to use when? - Let’s explore SuccessFactors APIs

[kc_kristris]

Introduction

In this blog we will try to explore the types of APIs in SAP SuccessFactors (Employee Central [EC] module), i.e. SFAPI and OData API (V2). What are the capabilities these APIs have? What to use when and some project-based recommendations.  

Please note, this blog is written based on my experience and learnings during my project engagement. The challenges I saw during project implementations and support I will be highlighting. Feel free to contribute 😊.

Both the APIs has own sets of capabilities.

Different types of APIs

Compound Employee API	OData V2
Used to extract employee data out of EC. It replicates employee master data from EC to SAP systems, payroll systems, and benefits systems.	It's intended to enable access to SAP SuccessFactors data in the system.
Protocol – SOAP	Protocol - OData
Operations – Used for query only	Operations – CRUD (Create, Read, Update and Delete) operations
Endpoint – https://{api-server}/sfapi/v1	Endpoint – https://{api-server}/odata/v2

Spoiler

Link to explore SuccessFactors EC APIs - Business Accelerator Hub

Capabilities of using CompoundEmployee API

• Fetches requested data of an employee in a single call, with a hierarchal structure response in XML.
• Replicates only data that has been approved in EC.
• Response compares all time slices of all entities specified in the request.
• Considering the performance aspect, only those fields which are needed during the replication process are fetched by the APIs.
• *In standard SAP integrations CompoundEmployee is used – e.g. [Replicate employee master data and organizational data from SAP SuccessFactors Employee Central to SAP ERP or SAP S/4HANA].
• Different query operations fetch data based on different time slices – back dated, effective dated and future dated records.
• *In single API response current and changed records can be fetched based on query parameters.

Challenge – API returns all the fields of the portlet; doesn’t support to select specific fields while querying (e.g. “job_information” portlet will return all the fields. Specific fields can’t be queried).

Below is the response snippet of “personal_information”, “employment_information, and  “job_information” portlets – action and changed values.

Spoiler

Link to SAP SuccessFactors HCM Suite SFAPI: Developer Guide

Capabilities of using SuccessFactors OData APIs (V2)

• Support methods for create, read, update and delete operations.
• Lightweight output – supports JSON format apart from XML format.
• Supports back dated, effective dated, and future dated query output.
• API query supports selective fields to fetch ($select)
• Supports Navigation ($expand). Recommendation – Avoid Large $expand Statements (using $expand to join a large number of tables can lead to poor performance).

Challenge - If there is a need to fetch the previous value of a field (e.g. Previous cost centre), then this is not possible in the same API call. We have to implement additional logic to fetch that (run a loop and compare relevant field change).

Spoiler

Link to SAP SuccessFactors API Reference Guide (OData V2) - Developer Guide

What is deprecated? 

Spoiler

Please Note - SFAPI is deprecated as of August 1, 2018. Please use OData for new development and consider moving your legacy applications and integrations to OData

Does this mean, CompoundEmployee is deprecated? No, this is the only SFAPI which is not deprecated and there is no plan date for the same as well as this is widely used in SAP standard contents. Means, we can still use this API based on case-to-case basis.

Probable scenarios for using CompoundEmployee

• While designing global payroll integrations – where bank is expecting current and change records of an employee based on period delta.
• While replicating employees of org data from SuccessFactors to HCM based on delta changes.
• Replicating employee and position data between two SuccessFactors.
• SuccessFactors integration with Ceridian Dayforce.

*Above are some of the project cases where I have considered CompoundEmployee API over OData API (V2).

Conclusion

• CompoundEmployee can be considered for employee replication scenarios where a single API can fetch most of the data in a hierarchically structured response.
• OData API (V2) can be considered where limited set of fields are expected from a an API.
• In case of update records into SuccessFactors, OData API (V2) to be considered as CompoundEmployee API supports only query operations.