INTRODUCTION
In this blog post, I want to share how to combine multiple requests in a single OData $batch request to upsert different entity records for single/multiple employees in SAP SuccessFactors using Postman, while supporting the transactional(atomic) behavior that ensures the records are fully updated or none in case of failure, that is partial changes are not done.
OData APIs
The Open Data Protocol (OData) is a standardized protocol for creating and consuming data APIs. SAP SuccessFactors use ODATA(2.0) APIs for integration and data replication. This API provides methods for CRUD operations (Create, Read, Update and Delete).
SAP SuccessFactors Documentation on OData APIs can be found in these three sources below:
Information about ODATA v2.0 can be found here: ODATA v2.0
Upsert in OData.
SAP SuccessFactors OData service supports a custom OData function called UPSERT. The UPSERT operation takes care of creating or updating the records so that you do not have to do this explicitly. The UPSERT operation also allows the operation on single or multiple records at the same time. The examples of Upsert can be found in $Batch section explained in this blog post.
Upsert is similar to POST with specifying x-http-method = MERGE in the headers of the request. MERGE allows specifying the fields which you would like to change and merge. You need to specify only the field(s) in the payload which is/are needed to be updated. Refer to the below example for MERGE.
The below image highlights the payload data where only the ‘firstName’ of employee(‘cgrante’) is changed and merged with a successful response(200).
$Batch Operation in ODATA
The OData protocol introduced the batch operation that can combine multiple requests into a single request. Batch requests are submitted as a single POST request to the /odata/v2/$batch URI. The maximum number of request count allowed in a batch request is 180. Multiple requests in a batch are processed independently of each other. All request operations in the same changeset follow the everything or nothing rule i.e. failure of a single operation causes the whole $batch to fail. Partial changes are not done.
You need to use the basic authorization in the form of (“user@company: password”) for all the example requests, where the user and company depend on the user. Please refer below.
The image below describes an example of a $batch request with 3 same changesets used to upsert records in different entities highlighted in red boxes.
However, this is not the case when different boundary changesets are used for multiple requests in a single $batch call, that is the failure of a single request operation does not cause the whole $batch to fail as shown in example 2.
More information about $batch can be found here: OData $Batch Operation
The image below provides a graphical glimpse of four examples tried using $batch in this blog post.
Refer below for detailed examples
Example 1: $Batch request to update record(s) in three different entities of a particular employee using the same changeset.
The below $batch request upserts a single record of three different entities (PaymentInformationDetailV3, PerPersonal, and User) of a particular employee. All the requests are separated by the same changeset defined in the Content-Type of a body, that is the same changeset is used to differentiate between requests and update the records.
In the below request, the changesets are the same for all the requests, so they are not closed for each request and closed once at the end of the body.
POST https://apisalesdemo4.successfactors.com/odata/v2/$batch
Host: apisalesdemo4.successfactors.com
Content-Type: multipart/mixed; boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b
The result body contains a response for each changeset request query that makes up the $batch request. The order of responses matches the order of requests. Each response includes a response httpcode, status, editstatus and others separated by response changesets in a similar order as the request body changesets.
If one of the requests fails due to any reason, a single failed response is returned with the error details, as the boundary for all the requests is the same.
Successful Response:
Failed Response:
However, this isn’t the case when we use separate boundary maker changesets for all the requests in a $batch API call.
The example is shown below:
Example 2: $Batch request to update record(s) in three different entities of a particular employee using different changesets.
The below $batch request upserts a single record of three different entities (PaymentInformationDetailV3, PerPersonal, and User) of a particular employee. All the requests are separated by a distinct changeset defined in the Content-Type of a batch in the request body, in other words, a different changeset is used to differentiate between each request and update the records.
In the below request, the changesets are not unique, so they are closed for each request in the body, thus defining a separate boundary for each request.
POST https://apisalesdemo4.successfactors.com/odata/v2/$batch
Host: apisalesdemo4.successfactors.com
Content-Type: multipart/mixed; boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b
The body of a batch response contains a response for each changeset request query that makes up the batch request. The order of responses matches the order of requests. The order of responses matches the order of requests. Each response includes a response httpcode, status, editstatus and others separated by response changesets in a similar order as the request body changesets.
In this case, we have used different changesets i.e. if one of the requests fails due to any reason, a single failed response is returned with the error details while the other two responses are successful. This is due to the use of different changeset values used for single batch operation and the failure of one doesn’t affect the others.
Successful Response:
Failed Response:
The below image shows the response for a request with different changesets. The highlighted box in red describes a failed response for 1st changeset while the other 2 highlighted in green show the successful response.
The failed response was due to the illegal value given to a field to be upserted in the first request.
Below are the $batch examples for updating of records for two employees in a single $batch request.
Example 3: $Batch request to change record(s) in three different entities for two employees(cgrante & 80300) using the same changeset for both.
POST https://apisalesdemo4.successfactors.com/odata/v2/$batch
Host: apisalesdemo4.successfactors.com
Content-Type: multipart/mixed; boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b
The body of a batch response contains a response for each changeset request query that makes up the batch request. The order of responses matches the order of requests. The first three changeset responses correspond to the upsertion of records for the employee(cgrante) and the other three correspond to the employee(80300(cdixon)).
If one of the requests fails due to any reason, a single failed response is returned with the error details, as the boundary for all the requests is the same.
Successful Response:
Failed Response:
The error response was returned failed as an illegal value was entered for the ‘accountNumber’ field in the PaymentInformationDetailV3 object for the employee(80300). Refer to the below graphic.
Example 4: $Batch request to change record(s) in three different entities for two employee(cgrante & 80300) using different changeset for both employees, one changeset(changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621) for employee(cgrante) and another changeset(changeset_77162fcd-b8da-41ac-a9f8-9357efbbd622) for the other employee(80300)
POST https://apisalesdemo4.successfactors.com/odata/v2/$batch
Host: apisalesdemo4.successfactors.com
Content-Type: multipart/mixed; boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b
The body of a batch response contains a response for each changeset request query that makes up the batch request. The order of responses matches the order of requests. Each response includes a response httpcode, status, editstatus, and others separated by the changesets similar in the request body.
In this case, we have used different changesets for both employees. In other words, one changeset for three entity requests of one user and another changeset for three entity requests of another employee. This signifies that if one request fails in any of the changesets, the whole changeset results in failure. So, if one employee's records are not upserted due to failure, the other is successful as we have used separate changesets for both users and failure of one doesn’t affect the others.
Successful Response:
Failed Response:
In this case, the first changeset with the upsertion of records for the employee(cgrante) fails as an illegal value was entered for the ‘bank’ field in the PaymentInformationDetailV3 object.
The above graphic shows where an invalid value was tried to be upserted for the first employee, but the changeset fails(marked in a red block below) and other employee records are upserted successfully(green blocks below).
CONCLUSION
This blog post concludes that the use of $batch is efficient for updating employee records from different cross entities in SAP SuccessFactors. It also supports the transactional behavior, in other words, the $batch changeset defines a boundary and success/failure within a boundary affects the whole response as described in four examples representing different scenarios. However, transactional behavior also comes with some limitations. While using a $batch is fine for process integration, it has a certain constraint in a data migration/data integration scenario.
Looking forward to your questions and feedback in the comments section.
Postman Collection(Github link): https://github.com/aditya710/Update-Employee-using-SuccessFactors-ODATA-batch-API.git
Best Regards.
Aditya Shelar
In this blog post, I want to share how to combine multiple requests in a single OData $batch request to upsert different entity records for single/multiple employees in SAP SuccessFactors using Postman, while supporting the transactional(atomic) behavior that ensures the records are fully updated or none in case of failure, that is partial changes are not done.
OData APIs
The Open Data Protocol (OData) is a standardized protocol for creating and consuming data APIs. SAP SuccessFactors use ODATA(2.0) APIs for integration and data replication. This API provides methods for CRUD operations (Create, Read, Update and Delete).
SAP SuccessFactors Documentation on OData APIs can be found in these three sources below:
- SAP SuccessFactors HXM Suite OData API: Reference Guide
- SAP SuccessFactors Employee Central OData API: Reference Guide
- SAP SuccessFactors HXM Suite OData API: Developer Guide
Information about ODATA v2.0 can be found here: ODATA v2.0
Upsert in OData.
SAP SuccessFactors OData service supports a custom OData function called UPSERT. The UPSERT operation takes care of creating or updating the records so that you do not have to do this explicitly. The UPSERT operation also allows the operation on single or multiple records at the same time. The examples of Upsert can be found in $Batch section explained in this blog post.
Upsert is similar to POST with specifying x-http-method = MERGE in the headers of the request. MERGE allows specifying the fields which you would like to change and merge. You need to specify only the field(s) in the payload which is/are needed to be updated. Refer to the below example for MERGE.
The below image highlights the payload data where only the ‘firstName’ of employee(‘cgrante’) is changed and merged with a successful response(200).
$Batch Operation in ODATA
The OData protocol introduced the batch operation that can combine multiple requests into a single request. Batch requests are submitted as a single POST request to the /odata/v2/$batch URI. The maximum number of request count allowed in a batch request is 180. Multiple requests in a batch are processed independently of each other. All request operations in the same changeset follow the everything or nothing rule i.e. failure of a single operation causes the whole $batch to fail. Partial changes are not done.
You need to use the basic authorization in the form of (“user@company: password”) for all the example requests, where the user and company depend on the user. Please refer below.
The image below describes an example of a $batch request with 3 same changesets used to upsert records in different entities highlighted in red boxes.
However, this is not the case when different boundary changesets are used for multiple requests in a single $batch call, that is the failure of a single request operation does not cause the whole $batch to fail as shown in example 2.
More information about $batch can be found here: OData $Batch Operation
The image below provides a graphical glimpse of four examples tried using $batch in this blog post.
Refer below for detailed examples
Example 1: $Batch request to update record(s) in three different entities of a particular employee using the same changeset.
The below $batch request upserts a single record of three different entities (PaymentInformationDetailV3, PerPersonal, and User) of a particular employee. All the requests are separated by the same changeset defined in the Content-Type of a body, that is the same changeset is used to differentiate between requests and update the records.
In the below request, the changesets are the same for all the requests, so they are not closed for each request and closed once at the end of the body.
- 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
- Batch Request Body
- Response Observation/Results
The result body contains a response for each changeset request query that makes up the $batch request. The order of responses matches the order of requests. Each response includes a response httpcode, status, editstatus and others separated by response changesets in a similar order as the request body changesets.
If one of the requests fails due to any reason, a single failed response is returned with the error details, as the boundary for all the requests is the same.
Successful Response:
Failed Response:
However, this isn’t the case when we use separate boundary maker changesets for all the requests in a $batch API call.
The example is shown below:
Example 2: $Batch request to update record(s) in three different entities of a particular employee using different changesets.
The below $batch request upserts a single record of three different entities (PaymentInformationDetailV3, PerPersonal, and User) of a particular employee. All the requests are separated by a distinct changeset defined in the Content-Type of a batch in the request body, in other words, a different changeset is used to differentiate between each request and update the records.
In the below request, the changesets are not unique, so they are closed for each request in the body, thus defining a separate boundary for each request.
- 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
- Batch Request Body
- Response Observation/Results
The body of a batch response contains a response for each changeset request query that makes up the batch request. The order of responses matches the order of requests. The order of responses matches the order of requests. Each response includes a response httpcode, status, editstatus and others separated by response changesets in a similar order as the request body changesets.
In this case, we have used different changesets i.e. if one of the requests fails due to any reason, a single failed response is returned with the error details while the other two responses are successful. This is due to the use of different changeset values used for single batch operation and the failure of one doesn’t affect the others.
Successful Response:
Failed Response:
The below image shows the response for a request with different changesets. The highlighted box in red describes a failed response for 1st changeset while the other 2 highlighted in green show the successful response.
The failed response was due to the illegal value given to a field to be upserted in the first request.
Below are the $batch examples for updating of records for two employees in a single $batch request.
Example 3: $Batch request to change record(s) in three different entities for two employees(cgrante & 80300) using the same changeset for both.
- 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
- Batch Request Body
- Response Observation/Results
The body of a batch response contains a response for each changeset request query that makes up the batch request. The order of responses matches the order of requests. The first three changeset responses correspond to the upsertion of records for the employee(cgrante) and the other three correspond to the employee(80300(cdixon)).
If one of the requests fails due to any reason, a single failed response is returned with the error details, as the boundary for all the requests is the same.
Successful Response:
Failed Response:
The error response was returned failed as an illegal value was entered for the ‘accountNumber’ field in the PaymentInformationDetailV3 object for the employee(80300). Refer to the below graphic.
Example 4: $Batch request to change record(s) in three different entities for two employee(cgrante & 80300) using different changeset for both employees, one changeset(changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621) for employee(cgrante) and another changeset(changeset_77162fcd-b8da-41ac-a9f8-9357efbbd622) for the other employee(80300)
- 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
- Batch Request Body
- Response Observation/Results
The body of a batch response contains a response for each changeset request query that makes up the batch request. The order of responses matches the order of requests. Each response includes a response httpcode, status, editstatus, and others separated by the changesets similar in the request body.
In this case, we have used different changesets for both employees. In other words, one changeset for three entity requests of one user and another changeset for three entity requests of another employee. This signifies that if one request fails in any of the changesets, the whole changeset results in failure. So, if one employee's records are not upserted due to failure, the other is successful as we have used separate changesets for both users and failure of one doesn’t affect the others.
Successful Response:
Failed Response:
In this case, the first changeset with the upsertion of records for the employee(cgrante) fails as an illegal value was entered for the ‘bank’ field in the PaymentInformationDetailV3 object.
The above graphic shows where an invalid value was tried to be upserted for the first employee, but the changeset fails(marked in a red block below) and other employee records are upserted successfully(green blocks below).
CONCLUSION
This blog post concludes that the use of $batch is efficient for updating employee records from different cross entities in SAP SuccessFactors. It also supports the transactional behavior, in other words, the $batch changeset defines a boundary and success/failure within a boundary affects the whole response as described in four examples representing different scenarios. However, transactional behavior also comes with some limitations. While using a $batch is fine for process integration, it has a certain constraint in a data migration/data integration scenario.
Looking forward to your questions and feedback in the comments section.
Postman Collection(Github link): https://github.com/aditya710/Update-Employee-using-SuccessFactors-ODATA-batch-API.git
Best Regards.
Aditya Shelar
- SAP Managed Tags:
10 Comments
| User | Count |
|---|---|
| 5 | |
| 4 | |
| 3 | |
| 2 | |
| 2 | |
| 1 | |
| 1 | |
| 1 | |
| 1 | |
| 1 |
