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.
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
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
- SAP Managed Tags:
9 Comments
| User | Count |
|---|---|
| 4 | |
| 3 | |
| 2 | |
| 2 | |
| 2 | |
| 2 | |
| 2 | |
| 2 | |
| 2 | |
| 2 |
