Skip to Content
Author's profile photo Former Member

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:

/wp-content/uploads/2013/08/img_blog_1_258261.png

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:


/wp-content/uploads/2013/08/image_blog_2_258263.png

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.

/wp-content/uploads/2013/08/image_blog_3_258264.png

Entities Related to Foundation Objects starts with prefix FO_

Here is one example:

/wp-content/uploads/2013/08/image_blog_4_258265.png

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.

/wp-content/uploads/2013/08/image_blog_6_258273.png

/wp-content/uploads/2013/08/image_blog_5_258272.png

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
/wp-content/uploads/2013/08/image_blog_7_258274.png

Response Message

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

/wp-content/uploads/2013/08/image_blog_8_258275.png

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

Assigned Tags

      24 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Luke Marson
      Luke Marson

      Hi Akhil,

      Great blog and very informative. I like that both standard and custom objects can be exposed via the API, particularly MDF objects. I think it's quite important from an integration perspective to be able to leverage these objects and when the SAP HANA Cloud Platform is more widely available it will offer greater benefits for extending the Employee Central system.

      Best regards,

      Luke

      Author's profile photo Former Member
      Former Member

      Thanks Luke :-). I 'll wait for August release for more details on Common Data/ MDF API. But yes OData is definitely a positive step, not just for integration but for custom development too. Let's see how it goes. 

      Author's profile photo Former Member
      Former Member

      Hi Luke. When I'm trying to create an MDF object, the first field (externalCode) with the data type Auto Number is not accepted as a business key field below & gives an error stating that "Invalid data type: AUTO_NUMBER for business key field".

      please give any hints on this issue

      Author's profile photo J. Pazahanick
      J. Pazahanick

      Great job Akhil and even more impressive given that is your first blog on SCN.  Look forward to your continued contributions as there is a lot of interest in Employee Central which I expect to grow by leaps and bounds given SAP/SF investment in the product and the leadership team involved.

      Author's profile photo Former Member
      Former Member

      Thank you Jarret for your positive feedback.

      Author's profile photo Former Member
      Former Member

      Great Blog Akhil. Very helpful to understand complex Entities & SF APIs.

      Author's profile photo Former Member
      Former Member

      Thanks Arpit 🙂

      Author's profile photo Former Member
      Former Member

      Hi Akhil,

      Great blog with fine details about SF EC. The way you have described the core details of EC was really good and provide clear overview of EC. For me personally it gave me a clear snapshot about how EC differs to SAP PA.

      Thanks once again for taking efforts to write the blog.

      Regards

      Author's profile photo Former Member
      Former Member

      Thanks Shashidher, glad it helped you!

      Author's profile photo Former Member
      Former Member

      Great Akhil, it gives a clear and succinct synopsis of the interfacing work you completed. Well done.

      Author's profile photo Former Member
      Former Member

      Thanks Nico 😏

      Author's profile photo Stephen Burr
      Stephen Burr

      Good job Akhil, I hope the positive responses encourage you to keep blogging.

      Author's profile photo Former Member
      Former Member

      Thanks Steve. I 'll try to be more active on SCN.

      Author's profile photo Former Member
      Former Member

      Hi Akhil,

      Excellent blog, thank you for all your hard work and time in putting this together. Clearly it was a much awaited blog.

      Cheers,

      Jyoti

      Author's profile photo Former Member
      Former Member

      Thanks Jyoti 😳

      Author's profile photo Former Member
      Former Member

      Thanks Akhil

      For posting such a wonderful doc ℹ . Surely It's rocking!!! Keep posting more such docs.

      Cheers 😉

      Pradyp

      Author's profile photo Former Member
      Former Member

      do you know where to get the information about EC odata entity individually , how each of them behave ?

      Author's profile photo Former Member
      Former Member

      Hi Akhil,

      Nice blog!! I have doubt here. Can we add operations to entity, like for entity ADHOC_HRIS I am getting error -

      <ns2:errorCode>UNSUPPORTED_OPERATION</ns2:errorCode>

                     <ns2:errorMessage>Entity type 'adhoc_hris' doesn't support QUERY operation!</ns2:errorMessage>

      Can we add operation here? I am trying to fetch data from this entity via SAP PI.

      Thanks & Regards,

      Rashmi Joshi

      Author's profile photo Former Member
      Former Member

      Hi Akhil,

      Very nice post, lot of helpful information here!


      I just have one question on which you may have the answer: by default when using SFAPI on compoundemployee, if there are records with the same start_date (on job_infirmation for example), SFAPI returns only the last record that was inserted. Do you know if there is a way to get all records back, even if they are on the same start_date?

      Thanks again for your post!


      Stephen

      Author's profile photo Nagesh Caparthy
      Nagesh Caparthy

      Hi Akhil Khandelwal

      Your blog helped me at lot. I am trying to take a look at the reference documents which you have shared, the URL seems to be not working. Can you please check and suggest.

      Regards,

      Nagesh

      Author's profile photo SAP HCM Consultant
      SAP HCM Consultant

      Great Akhil...!!!

      Author's profile photo Former Member
      Former Member

      Hi,

      Kindly help me to join two entity EmpEmployment and PerPersonal.

      I am using success factor soap query api and  below join like Sql which is not working

      SELECT e.user_id, e.person_id, e.start_date, e.end_date, e. originalStartDate

      p.first_name

      FROM EmpEmployment e join PerPersonal p on e.person_id=p.person_id

      and p.person_id =’XXXX’

      Author's profile photo Former Member
      Former Member

      Hi All,

      Kindly help me to join two entity EmpEmployment and PerPersonal.

      I am using success factor soap query api and  below join like Sql which is not working

      SELECT e.user_id, e.person_id, e.start_date, e.end_date, e. originalStartDate

      p.first_name

      FROM EmpEmployment e join PerPersonal p on e.person_id=p.person_id

      and p.person_id ='XXXX'

      Author's profile photo Jeremy Marmol
      Jeremy Marmol

      I have a question, how do you purge or remove specific Pay Component?

      PurgeType=full is working but it deletes previous history. Incremental Purge does not remove Annual, see the image attached:

      Â