--- category: [Administration & Integrations, Administration & Integrations/Workday API, Platform and Product Extensions, Platform and Product Extensions/Integration] nav: wcp_docs parent_url: /wcp_docs/ title: >- Concept: Batch Protocol for Workday REST APIs layout: subsection --- Batch Protocol is a mechanism for grouping multiple REST API calls from any of the public Workday REST services within a single request. Batch Protocol enables you to specify multiple REST APIs in the request body of a single REST API call. You can use Batch Protocol when you need multiple REST API requests that: - Need to process as a single transaction that can roll back in case one of the requests in the group fails. Batch Protocol provides transactional support, which enables a batch of subrequests to either succeed as a single transaction or entirely roll back. A failure on any of the subrequests causes the entire batch of subrequests to roll back. - Depend on data from other requests in the same transaction. Batch Protocol supports referential dependencies, which enable you to pass data from 1 REST API call to another in the same batch. - Require a specific sequence of REST API calls. Batch Protocol sequentially executes the REST APIs in the order that you specify them in the batch request. - Can tolerate some requests failing without aborting the entire transaction. Batch Protocol enables you to opt out of transactional support for specific subrequests in a batch. - Can significantly reduce network traffic when processed in a single transaction. Batch Protocol consolidates multiple network connections to multiple Workday REST services into a single connection. ## Usage - [Submitting a Batch Request](/wcp_docs/GUID-52feabc4-6c3e-4cd4-a4bc-cf58a5bdfab7-enHYPHENus.html#section-submitting-a-batch-request) - [Security Considerations](/wcp_docs/GUID-52feabc4-6c3e-4cd4-a4bc-cf58a5bdfab7-enHYPHENus.html#section-security-considerations) - [Referential Dependencies](/wcp_docs/GUID-52feabc4-6c3e-4cd4-a4bc-cf58a5bdfab7-enHYPHENus.html#section-referential-dependencies) - [Default Variables](/wcp_docs/GUID-52feabc4-6c3e-4cd4-a4bc-cf58a5bdfab7-enHYPHENus.html#section-default-variables) - [Continuing Batch Processing on Failure](/wcp_docs/GUID-52feabc4-6c3e-4cd4-a4bc-cf58a5bdfab7-enHYPHENus.html#section-continuing-batch-processing-on-failure) - [JsonPath in Referential Dependencies](/wcp_docs/GUID-52feabc4-6c3e-4cd4-a4bc-cf58a5bdfab7-enHYPHENus.html#section-jsonpath-in-referential-dependencies) - [Limits and Restrictions](/wcp_docs/GUID-52feabc4-6c3e-4cd4-a4bc-cf58a5bdfab7-enHYPHENus.html#section-limits-and-restrictions) - [Error Handling](/wcp_docs/GUID-52feabc4-6c3e-4cd4-a4bc-cf58a5bdfab7-enHYPHENus.html#section-error-handling) ## Submitting a Batch Request To submit a batch request using Batch Protocol, submit this REST API: ``` POST https://{tenantHostname}/batch/v1/{tenantName} ``` Example: `POST https://yourTenantHostName.com/batch/v1/gms` Note: The Batch Protocol REST API version is different from the version of the Workday REST APIs in the subrequests. The current Batch Protocol REST API version is `v1`. In the request body, specify the `batch[]` list of REST API subrequests, each containing a set of request fields: ``` { "batch": [ { "name": "subrequestName", "method": "httpMethod", "relativeUri": "subrequestUri", "continueOnFailure": true, "defaultVars": { "variable1": "value1", "variableN": "valueN" }, "body": { "requestField1": "value1", "requestFieldN": "valueN" } }, ... ] } ``` For details about the Batch Protocol REST API and the request fields, see [Reference: Batch Protocol REST API](/wcp_docs/GUID-dfa9b242-e0e6-4235-a0a8-f3cb64736586-enHYPHENus.html) ## Security Considerations - Ensure that you’ve configured security policies for each REST API call within the batch request. The REST API documentation lists the required security domains. The REST API documentation in the [REST API Explorer on the Developer Site](https://developer.workday.com/rest-api-explorer) or [Workday REST Services Directory](https://community.workday.com/sites/default/files/file-hosting/restapi/index.html) specifies the required security domains for each endpoint. - All subrequests use the same authentication. You can’t use different authorization per subrequest. ## Referential Dependencies To pass data from one subrequest to another, use referential dependencies. A referential dependency uses this notation: ``` {subrequestName:$.fieldJsonPath|defaultValue} ``` Enclose the referential dependency in curly braces `{}`, and specify: - `subrequestName:` (Required) The name of a previous subrequest. Specify the exact name of the subrequest in the same batch. Add a colon `:` after the subrequestName (without spaces). - `$.fieldJsonPath` (Required) The JsonPath reference to a field value in the response body of a previous subrequest. Use [JsonPath](https://github.com/json-path/JsonPath) syntax to reference the field value. Example: `$.id` returns the `id` field value at the root (`$`) of the JSON response data. Batch Protocol processes a referential dependency based on the specified JsonPath, default value, and `continueOnFailure`. For details, see the JsonPath in Referential Dependencies section. - `|defaultValue` (Optional) The default value if `$.fieldJsonPath` doesn't return a value. Provide the default value after the vertical pipe `|` character. To specify a default value, use either: - A hard-coded value. You can't include these characters: `{}`, `[]` - A default variable in the `defaultVars` of the same subrequest. See the Default Variables section. Use referential dependencies only in these subrequest fields: - `relativeUri` Example: Use a referential dependency in an ID path parameter. The ID can reference a newly created object from a preceding subrequest. - `body` request fields Specify the referential dependency within double quotes, regardless of the type of the referenced value. Batch Protocol resolves the proper type of the referenced value. Examples: - `"age": "{get-employee:$.age}"` resolves to `"age": 27`. - `"anniversary": "Congrats on {get-employee:$.numberYears} years with the company!"` resolves to `"anniversary": "Congrats on 6 years with the company!"`. Example: The sample second and third subrequests use referential dependency in the `relativeUri` field. It references the `id` response field from the first subrequest. The title field in the second subrequest also has a referential dependency that uses a default value. ``` { "batch": [ { "name": "create-prospect", "method": "POST", "relativeUri": "recruiting/v3/prospects/", "body": { "candidate": { "name": { "firstName": "Jane", "lastName": "Prospect", "country": { "id": "bc33aa3152ec42d4995f4791a106ed09" } }, "email": "JaneProspect@acme.com", "phone": { "countryPhoneCode": { "id": "db8d3ca6446c11de98360015c5e6daf6" }, "phoneNumber": "1200361755", "deviceType": { "id": "f51701ef48570198880272fd9728ab03" } } } } }, { "name": "create-prospect-experience", "method": "POST", "relativeUri": "recruiting/v3/prospects/{create-prospect:$.id}/experiences", "body": { "companyName": "Acme Corporation", "title": "{create-prospect:$.descriptor|Default Title}", "startYear": "2024-01-01" } }, { "name": "create-prospect-skills", "method": "POST", "relativeUri": "recruiting/v3/prospects/{create-prospect:$.id}/skills", "body": { "name": "Administration" }, "continueOnFailure": true } ] } ``` ## Default Variables A default value in a referential dependency can use a variable declared in the `defaultVars` field of the same subrequest. Declaring the variables and their default values within `defaultVars` helps with: - Easier maintenance of default values. - Reusability of default variables within a subrequest. - Improves readability of JSON objects and arrays as default values. The `defaultVars` field in a subrequest is a JSON map containing variable names and their default values. The default variable must match the expected type of default value within the referential dependency. Example: If the referential dependency value expects a list, the default variable must be a list. To reference a default variable in a referential dependency in the same subrequest, prefix the default value with a dollar sign `$`. The `defaultVars` in this sample subrequest defines the defaultCountry, defaultPhoneCode, and defaultConsent variables with sample default values. The corresponding referential dependencies use the default variables as the default values. ``` { "name": "create-prospect", "method": "POST", "relativeUri": "recruiting/v3/prospects/", "defaultVars": { "defaultCountry": { "id": "bc33aa3152ec42d4995f4791a106ed09" }, "defaultPhoneCode": { "id": "db8d3ca6446c11de98360015c5e6daf6" }, "defaultConsent": true }, "body": { "candidate": { "name": { "firstName": "Jane", "lastName": "Prospect", "country": "{get-prospect:$.candidate.name.country|$defaultCountry}" }, "email": "JaneProspect@acme.com", "phone": { "countryPhoneCode": "{get-prospect:$.candidate.phone.countryPhoneCode|$defaultPhoneCode}", "phoneNumber": "1200361755", "deviceType": { "id": "f51701ef48570198880272fd9728ab03" } } }, "contactConsent": "{get-prospect:$.contactConsent|$defaultConsent}" } } ``` ## Continuing Batch Processing on Failure Batch Protocol provides transactional support by default. That is, if any subrequest in the batch isn't successful, the batch request: - Rolls back all updates in the transaction. - Stops processing the subrequests. - Returns an error. If your business requirements can tolerate a subrequest failure and you prefer to continue the batch processing, you can opt out of transactional support by setting the `continueOnFailure` flag to `true` in the subrequest. If a subrequest fails and its `continueOnFailure` is `true`, the batch request: - Doesn't roll back previous subrequests. - Continues processing the next subrequests. - Reports the error in the response data of the subrequest that failed. When using `continueOnFailure`, consider these guidelines: - Be careful when combining `continueOnFailure` with referential dependencies. A referential dependency can't reference a subrequest whose `continueOnFailure` is true. If so, the subrequest will return an error unless you specified a default value in the referential dependency. If that subrequest fails and the processing continues: - Batch Protocol can't resolve referential dependency that depends on that data. - A subsequent subrequest might fail if it assumes that the previous subrequest created or updated the data. - A batch timeout ignores the `continueOnFailure` flag. If a batch request runs longer than the transaction timeout (25 seconds), then Batch Protocol rolls back the entire request, regardless of the `continueOnFailure` flag. - A parse error in the batch request ignores the `continueOnFailure` flag. If a general parse error occurs on the required request body format, then Batch Protocol immediately returns an error regardless of the `continueOnFailure` flag. Examples: A subrequest field name is invalid; a required subrequest field is missing. Note: Ensure that the service, version, and subresources in the `relativeUri` are valid. If these path parameters are invalid and `continueOnFailure` is true, Batch Protocol continues processing and reports the error in the response. ## JsonPath in Referential Dependencies In a referential dependency, use the [JsonPath](https://github.com/json-path/JsonPath) syntax to fetch a value within the JSON response data of a subrequest. In general, the `$.fieldPath` notation is sufficient to get a specific field value. Ensure that you specify a valid `fieldPath` and that you use correct JsonPath syntax for more complex notations. Batch Protocol processes a referential dependency based on the JsonPath, default value, and `continueOnFailure`. This table summarizes how these specified request fields affect batch requests containing subrequests with referential dependency:
JsonPath syntax is validJsonPath returns a valueDefault value providedcontinueOnFailureResult
xN/AN/AtrueThe batch request reports an error for the subrequest and continues processing.
xN/AN/AfalseThe batch request stops processing and rolls back its transaction.
✓✓N/AN/AThe subrequest uses the value from the JsonPath and the batch request continues processing.
✓x✓N/AThe subrequest uses the default value and the batch request continues processing.
✓xxtrueThe batch request reports an error for the subrequest and continues processing.
✓xxfalseThe batch request stops processing and rolls back its transaction.

There might be cases when you need to use JsonPath syntax that returns indefinite paths, such as these notations: - Deep scan operator: `..` - Expression: `?()` - Multiple array indices: `[, (, )]` If you need to use indefinite paths, note that an indefinite path always returns a list data type, even if the data at that path doesn't exist. Be mindful when using indefinite paths, which might cause unexpected results if the referential dependency is within a string. Note these sample referential dependencies with indefinite paths and their results:
Example using referential dependency with indefinite pathResult
"names": "{get-employees:$.name[?(@.age > 21)]}""names": ["Alice", "Bob", "Carl"]
"ceo": "The CEO is {get-employees:$.name[?(@.position == 'CEO')]}"

This example returns a single employee.

"ceo": "The CEO is [\"Montgomery Burns\"]"

The indefinite path returns a list containing the single employee.

"seniorExecs": "{get-employees:$.name[?(@.role == 'Executive' && @.aage > 65)]}"

This example contains a typo in the field path aage.

"seniorExecs": []

The invalid path returns an empty list.


If the referenced subrequest returns a list of instances, specify a JsonPath that accounts for the list. Example: ``` { "batch": [ { "name": "getWorkers", "method": "GET", "relativeUri": "staffing/v1/workers?search=logan" }, { "name": "getSingleWorker", "method": "GET", "relativeUri": "staffing/v1/workers/{getWorkers:$.data[1].id}" } ] } ``` For more information about indefinite paths, see [JsonPath > What is Returned When?](https://github.com/json-path/JsonPath#what-is-returned-when). ## Limits and Restrictions - Maximum number of subrequests per batch: 375. All batch requests have this limit, regardless of the HTTP methods used by the subrequests. - Batch request timeout: 25 seconds. All batch requests have this limit, regardless of the HTTP methods used by the subrequests. - All subrequests must share the same authentication. The REST APIs in all subrequests act on behalf of the same individual using the client. The security profile of the same user affects all REST API access to Workday resources. - All subrequests must share the same HTTP headers. The specified HTTP headers with the Batch Protocol REST API apply to all subrequests in the batch. - Batch Protocol supports uploading attachments, but not retrieving attachments. For uploading attachments, Batch Protocol doesn’t impose additional limits on top of the REST framework limits. See [Reference: File Size and Printing Limits](https://doc.workday.com/admin-guide/en-us/reporting-and-analytics/dan1370796659943.html). ## Error Handling By default, if any subrequest in the batch isn't successful, the entire batch request rolls back and returns a non-200 status code and the error message. Note: For debugging purposes, we highly recommend that you include the `name` in all the subrequests. The name helps you locate the subrequest in the response data. However, if you enable the `continueOnFailure` flag on a subrequest and the subrequest fails, Batch Protocol proceeds with the batch request. Upon completion, the batch request returns a 200 status code and includes any encountered error in the response data. Each subrequest returns a status code and a response body containing either the requested data or error messages. Always check the response for errors. See Response Codes in [Reference: Batch Protocol REST API](/wcp_docs/GUID-dfa9b242-e0e6-4235-a0a8-f3cb64736586-enHYPHENus.html). ### Related Information [Reference: Sample Batch Protocol Requests](/wcp_docs/GUID-b4c1e8f5-2313-41b1-9696-8bac93edbe61-enHYPHENus.html) [Developer Forum: REST Batch Protocol](https://forum.developer.workday.com/t/workday-extend-kss-november-5-2024-rest-batch-protocol/16983)