Skip to Content
Technical Articles

Creating Batch Requests with SAP Marketing Cloud SDK

In this blog post, we’ll elaborate on how you can send Batch request to SAP Marketing Cloud using the SAP Marketing Cloud SDK. This blog will cover the following steps:

  • Overview on Batch requests ($batch)
  • How to create Batch requests using SAP Marketing Cloud SDK

Prerequisites

In order to successfully execute this tutorial, we assume that you have:

  • Basic programming background with Java Development Kit
  • You have gone through our Getting Started Tutorial.
  • You should have a fundamental knowledge on OData Batch Operations (covered in below sections)

What is $batch?

A Batch request allows you to send multiple API requests at a single time. This can help you avoid rate limits for actions that need to be repeated multiple times. Here are some examples of when to use Batch requests:

  • Fetching records from multiple EntitySets
  • Sending multiple changes in the same service call

Format of a Batch Request

An OData Batch request is represented as a Multipart MIME v1.0 message, a standard format that allows the representation of multiple parts, each of which may have a different content type, within a single request.

Technically, A Batch request has two components like any HTTP request: a set of HTTP headers and a request body. Batch requests are submitted as a single HTTP POST request to the $batch endpoint of a service. The Batch Request must contain a Content-Type header specifying a content type of “multipart/mixed” and a boundary specification.The body of a Batch Request is made up of an ordered series of retrieve operations and/or ChangeSets. A ChangeSet is an atomic unit of work that is made up of an unordered group of one or more of the insert, update or delete operations. ChangeSets cannot contain retrieve requests and cannot be nested (i.e. a ChangeSet cannot contain a ChangeSet). For more details on OData v2 Batch Processing please refer to OData Specification document.

The example below represents a typical Batch request:

Building Batch Request with Marketing Cloud SDK

Step 1) Build Create{POST} payload using Virtual Data Model (VDM) Classes

With the below code snippet, you can build a Campaign Entity for Creation.

// Build Campaign Entity
Campaign entity = Campaign.builder()
                          .campaignName("Campaign Name")
                          .campaignDescription("Campaign Description")
                          .campaignCategory("CC") // Campaign Category
                          .campaignAssignedTargetGroups(
	                     // Build Target Group Entity and assign it to Campaign
	                       AssignedTargetGroupEntity.builder()
	                      .targetGroupUUID(UUID.fromString("Target Group UUID"))
                              .build())
                           .build();

Step 2) Build Batch Request using ODataBatchManager

String boundry = "multipart_1213212", 
request = IOUtils.toString(ODataBatchManager.builder()
				// Add Post Request
				.addChangeRequests("POST", "Campaigns", new ObjectMapper().convertValue(entity, Map.class))
				// Add Get Request
				.addQueryRequest("Campaigns?$top=2&$skip=0&$format=json").build(boundry).getRequestPayload(),
				StandardCharsets.UTF_8);

Step 3) Send the above formulated Request to some Destination

// get client for Default Destination in this case ERPQueryEndpoint
ServiceClient batchClient = ServiceClient.getInstance(); 
/* If you want to send the batch request to some Destination named
   "mkt_destination" on Cloud Foundry, you can create ServiceClient
   instance in this way :
   ServiceClient batchClient = ServiceClient.getInstance("mkt_destination")
*/

// Send the Request created in Step 2 to your Destination
 List<HTTPResponse> responseList = batchClient.postBatchHTTPRequestOnDestination("/sap/opu/odata/sap/API_MKT_CAMPAIGN_SRV/$batch", request, boundry)			

With this, you have performed a batch call and captured all the API responses in the variable responseList.

Current Scope

With our first version of SAP Marketing Cloud SDK, a developer can formulate a Batch request in JAVA without using StringBuilder or Olingo library operations.

Out of Scope

  • Batch operations utility methods are not seamlessly integrated with our VDM(Virtual Data Model) classes. Due to this, there is some manual effort required to build Batch request.
  • We do not maintain a specific FIFO (First In First Out) sequence of API requests within a batch.

 

Be the first to leave a comment
You must be Logged on to comment or reply to a post.