The second edition of the SAP PRESS book SAP SuccessFactors Employee Central: The Comprehensive Guide was released in November 2017 and again was co-authored between SAP’s long-time Employee Central product owner Murali Mazhavenchery, fellow Employee Central expert Becky Murray, and of course, myself. The book is not just updated, but has new content and a refined chapter structure. The guide should form an essential part of any user, administrator, consultant, aspiring consultant, or product expert’s learning material to get a better understanding of how Employee Central works.
In Chapter 22 we covered the topic of integration and below you can find an excerpt from chapter 22, section 3.
As with previous blogs, I hope the content provided was useful and educational. Please don’t hesitate to reach out if there is a specific topic you’d like me to write a blog about.
In Chapter 22 we covered the topic of integration and below you can find an excerpt from chapter 22, section 3.
API’s
SAP SuccessFactors contains two APIs that can be used for integrating Employee Central with other systems. The purpose of the integration and the platform used determine which of the following two APIs to use:
- OData API
- Compound Employee API (CE API)
You can use APIs when custom integrations need to be created. They typically aren’t used for data migration. Below highlights which API to choose based on your needs.
- OData API
- Access all Employee Central data, including historical data
- Custom and extension applications
- Update Employee Central data
- Consume MDF data
- Access a wide range of employee and talent data
- CE API
- Employee master data only
- Field-level delta
- Snapshot of data
- Modified employees only
- Read-only (no write capabilities)
- No OData capabilities
- Returns data in hierarchically structured XML format
We’ll now take a look at both APIs and their use cases.
1 OData API
The OData API is the core API provided to integrate Employee Central with other systems. The packaged integrations provided by SAP leverage this API, and it contains deep functionality for querying, updating, and purging data in Employee Central. The OData API is built on the Open Data (OData) Protocol v2.0, a standardized protocol for creating and consuming data.
The OData API supports most of the entities in Employee Central, plus Generic Objects and Platform entities, such as users, permissions (RBPs), and To Do list items. The latest list of entities that are exposed to the OData API can be found in the following handbooks located at http://help.sap.com/cloud4hr:
- SAP SuccessFactors Employee Central OData API: Reference Guide
- SAP SuccessFactors HCM Suite OData API: Reference Guide
API calls to the OData API are made via a HTTP call, which can be triggered from a middleware platform or any other application that supports the OData protocol and can make OData calls. Multiple operations are available for each entity:
- Create, query, or update data
- Select, order, filter, skip, top, format, or expand queries
- Create, update, or delete links between entities
- Navigate between related entities
The latter option enables you to use navigation properties to reach related entities. For example, the National ID Information entity (PerNationalID) and Job Information entity (EmpJob) can be queried through the person entity (PerPerson). This means that you can build a query to retrieve a complete dataset of employee data and related object data, including Foundation Object, Generic Object, and Picklist data. Let’s take a look at an example query to help us understand how this might work in practice.
In the PerPerson query shown in the listing below, a dataset for employee Carla Grant is being queried from Employee Central. The query includes data such as national ID, first name and last name, email address, hire date, pay group, all pay components, location, person ID, and date of birth.
PerPerson?$filter=personIdExternal+eq+'cgrant1'&$select=nationalIdNav/cardType,nationalIdNav/nationalId,personalInfoNav/firstName,personalInfoNav/lastName,emailNav/emailType,emailNav/emailAddress,employmentNav/startDate,employmentNav/compInfoNav/payGroup,employmentNav/compInfoNav/empPayCompRecurringNav/payComponent,employmentNav/compInfoNav/empPayCompRecurringNav/paycompvalue,employmentNav/jobInfoNav/location,personIdExternal,dateofBirth&$expand=nationalIdNav,personalInfoNav,emailNav,employmentNav,employmentNav/compInfoNav,employmentNav/compInfoNav/empPayCompRecurringNav,employmentNav/jobInfoNav
The OData API can be audited and managed within Admin Center, once the features have been permissioned as per the HCM Suite OData API handbook. There are the following four options available in Admin Center under Company Settings:
- API Audit Log: Captures payload details for the last 10,000 API calls.
- Manage API Option Profile: Manages settings for creating new users.
- OData API Dictionary: Provides information on all entities exposed to the OData API.
- OData API Metadata Refresh and Export: Enables all OData entities to be refreshed after configuration changes are made.
For more details on how to use the OData API, refer to the SAP SuccessFactors HCM Suite OData API: Reference Guide and SAP SuccessFactors HCM Suite OData API: Developer Guide at http://help.sap.com/cloud4hr.
2 Compound Employee API
The CE API is a web services-based API that uses the SOAP protocol to extract employee data from Employee Central. It is read-only and therefore cannot be used to update data within Employee Central. The primary use case of the CE API is to replicate a snapshot or delta of employee data from Employee Central to payroll and/or benefits systems. As a result, the CE API does not read historical or future-dated records, although it does read changes to employee data within the time period being extracted. It can read multiple changes made in one day.
The CE API is used by packaged integrations to replicate employee master data to SAP ERP and Employee Central Payroll and to third-party benefits, time and attendance, and payroll systems. The Employee Delta Export also uses the CE API.
Most Employee Central entities are supported by the CE API. The latest list of entities that are exposed to the CE API can be found in the Compound Employee API – Supported Fields (Reference) zip file located at http://service.sap.com/ec-ondemand.
The CE API uses a subset of traditional SQL to extract data. It uses the following SQL statement format to extract data:
SELECT <fields> FROM <entity> WHERE <conditions> ORDER BY <fields>
Unlike traditional SQL, no joins, subselect queries, or calculations are possible. In most cases, the FROM clause is FROM CompoundEmployee, but for the user entity it will be FROM user. The WHERE clause supports the following operators:
- AND and OR logic operators
- =, >, >=, <=,
- IS NULL/IS NOT NULL
- LIKE/NOT LIKE
- IN/NOT IN
The listing below provides an example statement to extract Person Information and Job Information for employees whose company is SAP and whose data was modified after January 1, 2016.
SELECT person, job_information
FROM CompoundEmployee
WHERE company='SAP'
AND last_modified_on > to_datetime ('2016-01-01','YYYY-MM-DD')
The CE API can be audited and monitored within Admin Center, once the features Access to SFAPI Audit Log and Access to SFAPI Metering Details have been permissioned for the user under the Manage Integration Tools permission category. Like the OData API, the CE API uses the API Audit Log that can be found in Admin Center via Company Settings > API Audit Log. In addition, the API Metering Details option found in Admin Center via Company Settings > API Metering Details provides analytics on API usage over the last 30 days.
For more details on the CE API, refer to the Implementing the Employee Central Compound Employee API handbook and Compound Employee API – Delta Transmission at http://help.sap.com/hr_ec.
As with previous blogs, I hope the content provided was useful and educational. Please don’t hesitate to reach out if there is a specific topic you’d like me to write a blog about.
- SAP Managed Tags:
