Employee Central Entities and Interfacing

Through this blog I intend to cover some of the basic concepts for SuccessFactors Employee Central integration, such as entities and objects, API, load type processing parameter and other features. I won’t touch on strategy for Integration i.e. Platforms (Dell Boomi, SAP PI et al) as Integration Strategy is dependent on System landscape and it’s more of the customer IT team’s prerogative, although I hope this blog will help customers in decision-making.

What is Employee Central?

As the SuccessFactors website says it’s the next-generation core HR system (HRIS) is designed for the global enterprise workforce delivered over Cloud.

At an Object level, Employee Central broadly maintains two kind of information:

• Organization, Pay and Job Structure Details – in Successfactors terminology this is called Foundation Objects
• Employee Details – This covers Personal and Employment Details for Employees, known as Personal and Employment Objects respectively

There is another category of Objects, which were added recently to provide flexibility in a scenario where standard delivered Foundation Objects are not sufficient to meet customer requirements. These are known as Generic or Custom Foundation Objects, e.g. Positions for Position Management. As per their current status, generic objects are not “Integration ready” i.e. it’s not possible to import or export generic objects in an automatic manner

Update – as per the Metadata Framework (MDF) Configuration guide, MDF Objects (Generic Objects are part of MDF) are exposed through REST Based Common Object OData API. However, at this time, there is not sufficient documentation available to add details and provide reference about this feature. Never the less it shows SAP’s commitment towards making their products more open and extensible to developer community. More information on Metadata Framework can be found at Luke Marson’s blog – http://scn.sap.com/community/erp/hcm/blog/2013/06/25/overview-of-the-successfactors-metadata-framework

What is an Entity in Employee Central?

EC stores data in multiple table structures, which are commonly known as EC Entities. There are various entities for Foundation as well as Personal/Employment Objects. The concept of entities can be best understood by relating them to SAP HCM Infotypes.

Common Foundation Objects Entities Available for Integration – Company/ Legal Entity, Business Unit, Location Group, Geozone, Location, Division, Department, CostCenter, JobCode, JobFunction, PayGroup, PayGrade, PayRange, PayComponent, PayComponentGroup, PayCalendar, EventReason, and Frequency.

Here is an example of Legal Entity Object:

Common Personal and Employment Objects Available for Integration – User, PerAddress, PerDirectDeposit, PerEmail, PerEmergencyContacts, PerNationalId, PerPerson, PerPersonal, PerPhone, PerSocialAccount, EmpCompensation, EmpEmployment, EmpEmploymentTermination, EmpJob, EmpJobRelationships, EmpPayCompNonRecurring, and EmpPayCompRecurring.

An example of EmpJob or JobInformation Object:

Properties of Entities

Effective Date and Effective Sequence – Those with some ERP experience would already be familiar with this concept. A majority of the Employee Central entities are effective dated. Effective date is a date when a given record becomes effective. It helps Employee Central track historical data accurately. Similarly there might be a scenario where multiple events are required to be recorded on same effective date for e.g. Transfer and Promotion. There is a field called Sequence Number, available in Job and Compensation Entities, which is used to identify such changes. Sequence Number should always by greater than 0

Business Keys – Each entity identifies its record uniquely by business key, which is a composite key or combination of various fields of that entity. For more details about this concept, refer Employee Central Configuration guide and Employee Central Entity Guide on the SuccessFactors Partner Portal

Purge Type – Employee Central supports two types of load: FULL and INCREMENTAL. When purgeType is set to ‘FULL’ during entity record update, Employee Central overwrites historical data for that record and inserts a new record. For ‘INCREMENTAL’ purge type, only those records that have same Effective Date and Sequence Numbers are overwritten

What is Employee Central API?

The Employee Central API is library of Employee Central entity structures exposed to the outside world. The Employee Central API covers Foundation Objects and Personal and Employment Objects. Those who don’t have programming background, a quick glance on wiki page about API would be useful – http://en.wikipedia.org/wiki/Application_programming_interface. The Employee Central API allows various data manipulation and query operation on Employee Central entities.

Supported Operations – Each entity supports some or all of the following Data Manipulation and Retrieval operations through API:

• Insert (insert) – Insert the record for specified Entity Type
• Update (update) – Update the record for specified Entity Type
• Upsert (upsert) – First try to update record, if record doesn’t exists (identified by Business Keys) then Insert record
• Query (query) – Retrieve records based on Successfactors query language (SFQL). For details about SFQL refer SFAPI documentation. For now just assume that SFQL is weaker cousin of SQL
• QueryMore (queryMore) – Query can support retrieval of only fixed number of records as specified in batchSize parameter. If there are more records then QueryMore has to be used (following Query operation).
• Delete (delete) – Deletes the record identified by Entity Type and Business Keys

If you have access to a SuccessFactors instance with necessary permissions, precise details can be found by going to Admin Tools -> API Dictionary. Personally I feel the API dictionary is great way to learn not just about integration, but about Employee Central in general.

Entities Related to Foundation Objects starts with prefix FO_

Here is one example:

As explained above, each Entity has a set of supported operations. Each field in an entity also has different set of properties. One more point worth noting is that custom fields added to the configuration are also visible and can be used by supported operations.

Similarly Personal and Employment Objects can be accessed through API. Person Entities start with the Per prefix and Employment Entities start with the Emp prefix. Examples of these can be seen below.

In the API dictionary you would also find API(s) for Picklists, Background Objects, Adhoc Reports and a few other general objects that are part of Employee Central and the SuccessFactors BizX suite as a whole.

Let’s see one example now –

Let’s try to retrieve Personal Details (PerPersonal API Entity) for Carla Grant. For simplicity I am using soapUI to trigger the request.

Request Message. Check the SFQL, where we are retrieving fields in PerPersonal entity, filtered by “where” clause on person_id_external

Response Message

Here we have SOAP response with Personal Details about Carla Grant.

A quick note, here we see only those fields, which were in SFQL query. Your (custom) application can consume this response as needed.

Summary

As mentioned in prologue, the weblog covered some of the basic concepts about Employee Central. The Entities forms core of EC, knowing about entities would also be useful in adhoc reports, advanced reporting and other tools.

I hope this blog is helpful for consultants and customers trying to understand, integrate and extend Employee Central.

REFERENCES

Entity Type Guide

https://confluence.successfactors.com/download/attachments/29131019/EC_Entity+Type+Guide.docx?version=1&modificationDate=1362174001750

Entity Guide – User Object

https://confluence.successfactors.com/download/attachments/61358344/SFAPI_Entity_Guide_User.pdf?version=2&modificationDate=1370419657808

SFAPI

https://confluence.successfactors.com/download/attachments/59446592/SFAPI_Functional_Guide_1210.pdf?version=1&modificationDate=1368146371531

Metadata Framework (MDF)

https://confluence.successfactors.com/download/attachments/29131019/MDF+Implementation+Handbookv3.0.pdf