Tell us what you think

We want to create the best possible experience for our learners. Your feedback helps us to improve the experience for everyone.

Performing Batch Operations in Service Layer API

Objective

After completing this lesson, you will be able to perform multiple operations using single request

Batch Operations

Batch requests allow you to group multiple individual requests into a single HTTP request payload.

Typically, a batch request is composed of the following.

A list of Batch Operation components, including Batch Request Method and URI, Batch Request Headers, Batch Request Body, and Batch Response.

Batch Request Method and URI

Batch requests are submitted as a single HTTP POST request to the batch endpoint of a service. They are located at the URL $batch relative to the service root.

Code Snippet

1
POST https://localhost:50000/b1s/v2/$batch

Batch Request Headers

The batch request needs a Content-Type header set to "multipart/mixed", with a boundary specification as follows:

Code Snippet

1
Content-Type: multipart/mixed;boundary=<Batch Boundary>

The boundary attribute <Batch Boundary> is a GUID (Globally Unique Identifier) string value. You can form your own value based on the allowed characters mentioned in the MIME (Multipurpose Internet Mail Extensions) document. This boundary attribute is used in the Batch Request Body.

Batch Request Body

The body of a batch request is composed of a series of individual sub-requests, or a series of individual sub-requests enclosed in a change set, represented as a distinct MIME part and separated by the boundary defined in the Content-Type header.

A change set is an atomic unit of works. It means that any failed sub-request in a change set causes the whole change set to be rolled back. Change sets must not contain any GET requests or other change sets.

Change set operations allow you to send multiple HTTP requests in a single payload to fulfill use cases which require rollback on failure.

General Format

Code Snippet

123456789101112
--<Batch Boundary> 
 <subrequest-1> 
 --<Batch Boundary> 
 <subrequest-2> 
 --<Batch Boundary> 
 Content-Type: multipart/mixed;boundary=<Changeset Boundary> 
--<Changeset boundary> 
 <subchangeset-request-1> 
 --<Changeset boundary> 
 <subchangeset-request-2> 
 --<Changeset boundary>-- 
 --<Batch Boundary>--

Batch Response

The response body that is returned to the client depends on the request execute result.

The batch will stop executing once a sub request fails. When there is a failure in the change set, only one response returns for this change set, no matter how many sub requests exist in this change set.

If the request format is not valid, the service returns an HTTP error code: 400 Bad Request, with error info in the body.

If the request format is valid, the service returns an HTTP code: 200 OK (OData Version 4) with the response content. Each sub-request will have a corresponding sub-response in the response body.

General Format

Code Snippet

12345678910
--<batchresponse> 
<response content> 
--<batchresponse> 
<response content> 
--<changesetresponse1> 
<Changesetcontent> 
--<changesetresponse2> 
<Changesetcontent> 
--<changesetresponse>-- 
--<batchresponse>--

Note

You can find more information about the MIME definition on the RFC Editor website.

How to Use Batch Request Methods

In this video, you learn how to perform batch operations using a change set.

Create and Update Items in a Single Batch

In this exercise, you will practice batch operations with change set option.

Before starting this exercise, make sure that you:

Install a REST API client tool, such as Postman.
Download the Demo UK International database from SAP Business One Localized Demo Databases
Complete a login request so that you have a session ready to use.

Steps

To create the batch request, amend the following HTTP sample request and send:

Sample request

Code Snippet

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950
POST https://localhost:50000/b1s/v2/$batch 
Content-Type : multipart/mixed;boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b 

--batch_36522ad7-fc75-4b56-8c71-56071383e77b  
Content-Type: multipart/mixed; boundary=changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621  

--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621 
Content-Type: application/http  
Content-Transfer-Encoding: binary  
Content-ID: 1 

POST Orders 

{ 
    "CardCode": "C20000", 
    "DocDueDate": "2024-11-04", 
    "PartialSupply": "tYES", 
    "DocumentLines": [ 
        { 
            "ItemCode": "A00001", 
            "Quantity": "2", 
            "TaxCode": "A2", 
            "UnitPrice": "300" 
        } 
    ] 
} 

--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621 
Content-Type: application/http  
Content-Transfer-Encoding: binary  
Content-ID: 2 

POST Invoices 

{  
    "CardCode": "C20000",  
    "DocDueDate": "2024-11-04",  
    "PartialSupply": "tYES",  
    "DocumentLines": [  
        {  
            "BaseType": 17,  
            "BaseEntry": $1,  
            "BaseLine": 0, 
            "Quantity": "1" 
        }  
    ]  
} 

--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621-- 
--batch_36522ad7-fc75-4b56-8c71-56071383e77b--

Check the response:
1. Check the response code - it should be 200 - OK if the HTTP request is successful.
2. Check the response content - it should contain the information on newly created sales order and sales invoice.
3. You can also verify the newly created document in the SAP Business One Desktop Client or SAP Business One, Web client.
To create a batch request with unsuccessful sub-request, amend the following HTTP sample request and send to check how the change set rollback works:

Sample request

Code Snippet

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162
POST https://localhost:50000/b1s/v2/$batch 
Content-Type : multipart/mixed;boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b 

--batch_36522ad7-fc75-4b56-8c71-56071383e77b  
Content-Type: multipart/mixed; boundary=changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621  

--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621 
Content-Type: application/http  
Content-Transfer-Encoding: binary  
Content-ID: 1 

POST Orders 

{ 
    "CardCode": "C20000", 
    "DocDueDate": "2024-11-04", 
    "PartialSupply": "tYES", 
    "DocumentLines": [ 
        { 
            "ItemCode": "A00001", 
            "Quantity": "2", 
            "TaxCode": "A2", 
            "UnitPrice": "300" 
        } 
    ] 
} 

--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621 
Content-Type: application/http  
Content-Transfer-Encoding: binary  
Content-ID: 2 

POST Invoices 

{  
    "CardCode": "C20000",  
    "DocDueDate": "2024-11-04",  
    "PartialSupply": "tYES",  
    "DocumentLines": [  
        {  
            "BaseType": 17,  
            "BaseEntry": $1,  
            "BaseLine": 0, 
            "Quantity": "1" 
        }  
    ]  
}  

--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621 
Content-Type: application/http  
Content-Transfer-Encoding: binary  
Content-ID: 3 

PATCH $1 

{ 
     "Quantity": "2" 
    "Comments": "Invoice created in batch_36522ad7-fc75-4b56-8c71-56071383e77b" 
} 

--changeset_77162fcd-b8da-41ac-a9f8-9357efbbd621-- 
--batch_36522ad7-fc75-4b56-8c71-56071383e77b--

Check the response:
1. Check the response code - it should be 200 - OK if the HTTP request is successful.
2. Check the response content - it should contain the error HTTP/1.1 400 Bad Request. The sales order and invoice information are not available because it is rolled back.

Result

You have successfully:

Performed batch operations.
Checked how a change set works.
Checked the response received for the request.

Log in to track your progress & complete quizzes