Batch Resource

Use this resource to minimize the number of round-trips between the client and the server. For example, in a mobile app, when a user taps the button to like a feed item, the response body includes information about the like, but it doesn’t include the total number of likes on the feed item. To like the feed item, POST a request to /chatter/feed-elements/feedElementId/capabilities/chatter-likes/items. To get the like total, GET the feed item information from /chatter/feed-elements/feedElementId/capabilities/chatter-likes/items.

Add both requests to a Generic Batch Collection Input request body and send them both in a single POST request to /connect/batch:

1{
2   "batchRequests" : [
3    {
4       "method" : "Post",
5       "url" : "/v34.0/chatter/feed-elements/feedElementId/capabilities/chatter-likes/items"
6    },
7    {
8       "method" : "Get",
9       "url" : "/v34.0/chatter/feed-elements/feedElementId/capabilities/chatter-likes/items"
10    }
11   ],
12   "haltOnError" : "false"
13}

The requests in a batch are called subrequests. All subrequests are executed in the context of the same user. Subrequests are independent and information can’t be passed between them. Subrequests execute serially in their order in the request body. When a subrequest executes successfully, it commits its data. Commits are reflected in the output of later subrequests (as in the previous example which liked a feed item then got the total number of likes). If a subrequest fails, commits made by previous subrequests are not rolled back.

Resource

1/connect/batch

Available since version

28.0

Requires Chatter

No

HTTP methods

POST

Request body

Generic Batch Collection Input

Root XML Tag

<batch>

JSON

1{
2   "batchRequests" : [
3    {
4       "method" : "Get",
5       "url" : "/v34.0/chatter/feeds/news/me"
6    },
7    {
8       "method" : "Get",
9       "url" : "/v34.0/chatter/feeds/user-profile/me"
10    }
11   ]
12}

Properties

Name	Type	Description	Available Version
batchRequests	Generic Batch Input[]	Collection of Batch Request Input request bodies containing the subrequest URLs to execute.	28.0
haltOnError	Boolean	The default value is false. If the value is false and a subrequest in the batch does not complete, Salesforce attempts to execute subsequent subrequests in the batch. If the value is true and a subrequest in the batch does not complete due to an HTTP response in the 400 or 500 range, Salesforce halts execution. It does not attempt to execute subsequent subrequests in the batch, and it returns an HTTP 412 status code and a BATCH_PROCESSING_HALTED error message for each subsequent subrequest indicating that a previous request was unsuccessful. The top-level request to /connect/batch returns HTTP 200 and the hasErrors property in the response is set to true.	28.0

Request parameters

None.

Response

Batch Results

Example

This simple example is a POST request made to https://instance_name/services/data/v34.0/connect/batch that includes the following request body containing two subrequests:

1swfobject.registerObject("clippy.codeblock-3", "9");
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17{
18   "batchRequests" : [
19    {
20       "method" : "Get",
21       "url" : "/v34.0/chatter/feeds/user-profile/me"
22    },
23    {
24       "method" : "Get",
25       "url" : "/v34.0/chatter/feeds/news/me"
26    }
27   ]
28}

The Batch Results response body includes a Batch Result Item response body for each subrequest:

1swfobject.registerObject("clippy.codeblock-4", "9");
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17{
18   "hasErrors": false,
19   "results": [
20      {
21         "result": {
22            "feedElementPostUrl": "/services/data/v34.0/chatter/feed-elements",
23            "feedElementsUrl": "/services/data/v34.0/chatter/feeds
24/user-profile/005D0000001LL8OIAW/feed-elements",
25            "isModifiedUrl": null
26         },
27         "statusCode": 200
28      },
29      {
30         "result": {
31            "feedElementPostUrl": "/services/data/v34.0/chatter/feed-elements",
32            "feedElementsUrl": "/services/data/v34.0/chatter/feeds
33/news/005D0000001LL8OIAW/feed-elements",
34            "isModifiedUrl": null
35         },
36         "statusCode": 200
37      }
38   ]
39}

Example: haltOnError is true

This example is the same as the previous example but it includes an error in the first subrequest and haltOnError is set to true. Note that the first subrequest contains a typo.

1swfobject.registerObject("clippy.codeblock-5", "9");
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17{
18   "batchRequests" : [
19    {
20       "method" : "Get",
21       "url" : "/v34.0/chatter/feeds/user-profile/men"
22    },
23    {
24       "method" : "Get",
25       "url" : "/v34.0/chatter/feeds/news/me"
26    }
27   ],
28   "haltOnError" : "true"
29}

The Batch Results response body includes a Batch Result Item response body for each subrequest. The top-level request to /connect/batch returns an HTTP 200, but the first subrequest returns an HTTP 404 because the resource can’t be found. Because haltOnError is true, the next subrequest returns an HTTP 412. Also note that hasErrors is true.

1swfobject.registerObject("clippy.codeblock-6", "9");
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17{
18   "hasErrors": true,
19   "results": [
20      {
21         "result": [{
22            "errorCode": "NOT_FOUND",
23            "message": "The requested resource does not exist"
24         }],
25         "statusCode": 404
26      },
27      {
28         "result": [{
29            "errorCode": "BATCH_PROCESSING_HALTED",
30            "message": "Batch processing halted per request"
31         }],
32         "statusCode": 412
33      }
34   ]
35}

Post multiple comments with binary files

This example is a generic batch request to https://instance_name/services/data/v34.0/connect/batch that contains two subrequests. Each subrequest comments on a feed item and uploads a binary file to the comment.

You must include the request body of each subrequest in the richInput properties.

You must also include information about the binary parts in the binaryPartName and binaryPartNameAlias properties.

This is the cURL example:

1curl -H "X-PrettyPrint: 1" -F 'json={ "haltOnError":true, "batchRequests":[ { "url":"/v33.0/chatter/feed-elements/0D5D0000000YG0N/capabilities/comments/items", 
2"method":"Post", "binaryPartName":"binaryPart1", "binaryPartNameAlias":"feedElementFileUpload", "richInput":{ "body":{ "messageSegments":[ { "type":"Text", "text":"Check out this file, it may help." } ] },
3 "capabilities":{ "content":{ "title":"Presentation1.txt" } } } }, { "url":"/v33.0/chatter/feed-elements/0D5D0000000YG0M/capabilities/comments/items", 
4"method":"Post", "binaryPartName":"binaryPart2", "binaryPartNameAlias":"feedElementFileUpload", "richInput":{ "body":{ "messageSegments":[ { "type":"Text", "text":"Check out this file, it may help." } ] },
5 "capabilities":{ "content":{ "title":"Presentation2.txt" } } } } ] };type=application/json' -F "binaryPart1=@/Users/jbleyle/Desktop/Presentation1.txt;type=application/octet-stream" 
6-F "binaryPart2=@/Users/jbleyle/Desktop/Presentation2.txt;type=application/octet-stream" 
7-X POST https://instance_name/services/data/v34.0/connect/batch 
8-H 'Authorization: OAuth 00DD00000007HoR!...' --insecure

This is the multipart/form-data request body:

1swfobject.registerObject("clippy.codeblock-8", "9");
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17https://instance_name/services/data/v34.0/connect/batch
18
19Authorization: OAuth 00DD0000000Jhd2!...
20Accept: application/json
21Host: instance_name
22Content-Type: multipart/form-data; boundary=123123
23
24--123123
25Content-Disposition: form-data; name="json"
26Content-Type: application/json
27
28{
29   "haltOnError":true,
30   "batchRequests":[
31      {
32         "url":"/v34.0/chatter/feed-elements/0D5D0000000YG0D/capabilities/comments/items",
33         "method":"Post",
34         "binaryPartName":"binaryPart1",
35         "binaryPartNameAlias":"feedElementFileUpload",
36         "richInput":{
37            "body":{
38               "messageSegments":[
39                  {
40                     "type":"Text",
41                     "text":"Check out this file, it may help."
42                  }
43               ]
44            },
45            "capabilities":{
46               "content":{
47                  "title":"Presentation1.txt"
48               }
49            }
50         }
51      },
52      {
53         "url":"/v34.0/chatter/feed-elements/0D5D0000000YG0H/capabilities/comments/items",
54         "method":"Post",
55         "binaryPartName":"binaryPart2",
56         "binaryPartNameAlias":"feedElementFileUpload",
57         "richInput":{
58            "body":{
59               "messageSegments":[
60                  {
61                     "type":"Text",
62                     "text":"Check out this file, it may help."
63                  }
64               ]
65            },
66            "capabilities":{
67               "content":{
68                  "title":"Presentation2.txt"
69               }
70            }
71         }
72      }
73   ]
74}
75
76
77--123123
78Content-Disposition: form-data; name="binaryPart1"; filename="Presentation1.txt"
79Content-Type: application/octet-stream; charset=ISO-8859-1
80Content-Transfer-Encoding: binary
81
82This is the content of file 1
83--123123
84Content-Disposition: form-data; name="binaryPart2"; filename="Presentation2.txt"
85Content-Type: application/octet-stream; charset=ISO-8859-1
86Content-Transfer-Encoding: binary
87
88This is the content of file 2
89--123123--
90