Human Capital Management Blogs by SAP
Get insider info on SAP SuccessFactors HCM suite for core HR and payroll, time and attendance, talent management, employee experience management, and more in this SAP blog.
cancel
Showing results for 
Search instead for 
Did you mean: 
aditya_shelar
Participant
INTRODUCTION

In this blog post, you can learn how to create an employee in EC(Employee Central) SuccessFactors using ODATA $batch API. I want to share how to create an employee with the required entities and the corresponding mandatory fields of respective entities to keep it simple.

Information about $batch can be found here: OData $Batch Operation

If you need to update employee records in existing entities using a $batch request, please refer to my blog post on Update employee(s) records from different entities using ODATA $batch API in SAP SuccessFactors

For this example, I am using the Postman tool: an interactive tool for constructing and testing APIs and reading responses. You can download it from here: Download Postman.

Entity and fields required for employee creation

The below image outlines the different user entities needed for employee creation, along with the corresponding mandatory fields per entity, which are listed directly under the entity name. Some of those are mandatory by default, while others are a result of the specific configuration in this system.



The order: User -> PerPerson -> EmpEmployment -> EmpJob -> PerPersonal needs to be followed as listed in the graphic above and it is critical. Employee data can be successfully created while following this order as the creation of one entity depends on the earlier one.

Please follow the steps to create an employee using $batch API.

Step 1: Create a new request in Postman. Once created, the first step is to use basic authorization in the form of (“user@company: password”) for the request, where the user and company need to be specified for the purpose of authentication. Please refer below The 'Username' and 'Password' is Base 64 encoded and shown in the 'Headers' section of the request as highlighted below.



Step 2: Batch Request Header

POST https://apisalesdemo4.successfactors.com/odata/v2/$batch

Host: apisalesdemo4.successfactors.com

Content-Type: multipart/mixed; boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b

Before constructing the request body, I would like to explain the use of postman variables in the API request. These variables allow you to store and reuse the values in the requests and scripts so that you can use the variable when the value needs to be used in multiple places without having to enter the value repeatedly wherever you need it.

More information about Postman variables can be found here: Postman Variables.


I have used the Pre-request script to create environment variables that allow the creation of variables prior to the API call. Wherever the variables are referred to in the request, the value is used from these environment variables.



You can refer the variables in the request URL or body by using double curly brackets with the variable name in between.

For example. User can be referred by using {{User}} in the url/body of the request.

If you want to see the created variables, you can click on the eye button in the top right section of the postman tool as shown in the below image.



Step 3: Batch Request Body



The request body contains a single changeset containing 5 different requests for employee entities creation. This structure ensures that the employee is fully created or nothing is created in case any of the five requests fail due to some reason.

Step 3: Batch Response Body

Successful Response



The response above shows five HTTP responses with the status code as 200 OK one for each entity and editstatus as ‘INSERTED’ or ‘UPSERTED’, this behavior will remain the same for all the entities and the user is successfully created.

If you need to verify if the user is created or not, you can log in to the system and type the username of the employee you just created in the search field to verify.

Refer to the below image that shows the employee we created using $batch request.



This shows that the user is successfully created.

Failed Response

In this case, I tried to create a user where the ‘dateOfBirth’ record was provided with invalid data in order to test the failure condition.

The response gives an error with the status code of 500 (Internal Server Error) and no partial entities are created. Refer below image.



CONCLUSION

This blog post describes the creation of an employee using $batch which allows that an employee is created in the system at one go itself instead of creating five different requests, one for each entity and executing them one after another to ensure successful creation. Also, this API supports transactional(atomic) behavior, in other words, the employee is successfully created if the whole changeset executes without error and nothing is created in case of failure of any request in the whole changeset. To sum up, the partial creation of an employee is not supported.

Looking forward to your comments and questions.

 

Postman Collection(Github link): https://github.com/aditya710/Create-Employee-using-SuccessFactors-ODATA-batch-API.git

Best Regards.

Aditya Shelar
9 Comments
Smitha
Product and Topic Expert
Product and Topic Expert
That's quite a handy blog, Aditya. Thank you.
Sriprasadsbhat
Active Contributor
0 Kudos

Hello Aditya,

Nice Blog! Its very helpful if you could copy paste the XML ( may be you can use insert or edit code sample option in editor by masking some of the sensitive info) instead of screenshots as many of the community members tends to try out.

Regards,

Sriprasad Shivaram Bhat

 

ngautamr
Explorer
0 Kudos
Hello Aditya

Thanks for the detailed information on how to automate the creation of employee record. I have few queries regarding this approach.

  1. How does this work when the UserId generation in EC is set to auto generated Id? Should we leave the UserId field blank and process it ?

  2. When EC is Integrated with ERP via CPI , does the data which is created from this batch process gets triggered for replication?

  3. Can i run this on all available portlet (Custom & Standard) in EC?


Thanks in advance & Awaiting your response.

Regards

Gautham.
aditya_shelar
Participant
0 Kudos
You can find the postman collection on the below link in github.

https://github.com/aditya710/Create-Employee-using-SuccessFactors-ODATA-batch-API.git
aditya_shelar
Participant
0 Kudos

Hello Gautham.

  1. In this case, you may want to use the same logic as EC uses to generate the personID and the API to retrieve the person IDs. Please look at the article below. https://apps.support.sap.com/sap/support/knowledge/public/en/2355576 has to be used to generate them before the $BATCH is being called. Leaving the userId empty will not work since it is a required field for other portlets.

  2. Yes. Creating data like this will create audit records and last modified date entries in the same way as the UI and hence records will get picked up.

  3. As long as the portlet supports a write operation it should be possible to combine them, no matter if Standard EC or custom MDF object.

Thank You.

Kind Regards,

Aditya Shelar

ngauthamreddy
Explorer
0 Kudos
Thanks a lot Aditya for the detailed clarification provided.

Regards

Gautham.
ebsor
Participant
0 Kudos
Hi Aditya,

 

Thanks for article, I cannot find curl command for postman. Could you send the link or as email.

 

thanks,

 

ebsor
Berg
Participant
0 Kudos
A great blog. Introducing an such advanced method easily. Thanks.
manu_bhai
Explorer
0 Kudos

Hello Aditya, Can you please share github link again?? The link is probably deleted.