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
Entity Guide – User Object
SFAPI
Metadata Framework (MDF)
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
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.
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
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.
Thank you Jarret for your positive feedback.
Great Blog Akhil. Very helpful to understand complex Entities & SF APIs.
Thanks Arpit 🙂
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
Thanks Shashidher, glad it helped you!
Great Akhil, it gives a clear and succinct synopsis of the interfacing work you completed. Well done.
Thanks Nico 😏
Good job Akhil, I hope the positive responses encourage you to keep blogging.
Thanks Steve. I 'll try to be more active on SCN.
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
Thanks Jyoti 😳
Thanks Akhil
For posting such a wonderful doc ℹ . Surely It's rocking!!! Keep posting more such docs.
Cheers 😉
Pradyp
do you know where to get the information about EC odata entity individually , how each of them behave ?
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
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
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
Great Akhil...!!!
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’
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'
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:
Â