BulkOperation
BulkOperation
A bulk operation acts on many entries and assets in one request. Use the BulkOperation class to do the following tasks:
- publish, unpublish or delete entries and assets in bulk
- change the workflow stage of many entries at once
- add items to a release, or update the items of a release, in bulk
- read the status and the items of a bulk job
The bulkOperation method on Stack returns a new BulkOperation and sends no request. It takes no UID, so every method is available on the object.
Additional Resource The Bulk Operations and Job Status sections of the Content Management API (CMA) reference describe each request and its limits.
Class-Level Notes
Options objects.
- Every method except getJobItems reads its arguments from one object, for example publish({ details }).
- publish, unpublish, addItems, updateItems and jobStatus need that object. Calling one of them with no argument returns a promise that rejects with TypeError.
How failures reach your code.
- publish, unpublish, delete and update return a promise that rejects with an Error when the API rejects the request.
- addItems, updateItems, jobStatus and getJobItems write the error to the console and resolve to undefined. Each of these method pages includes a Known issue line with the workaround.
Bulk limits. The API applies the following limits to bulk requests:
- One bulk publish or unpublish request covers up to 10 entries, in up to 10 locales and 10 environments.
- One bulk delete request covers up to 100 entries.
- The default rate limit for bulk actions is one request per second, lower than the standard limit.
Jobs.
- The API runs a bulk request as a background job. The promise resolves when the API accepts the request, not when the job finishes.
- Read the progress of a job with jobStatus and its items with getJobItems.
Headers and branches.
- stack.bulkOperation() gives the new object the headers of the stack, such as api_key and branch. addHeader changes only this object.
Rate limiting and retry.
- This SDK retries 429 automatically, with configurable delay and attempt limits.
Additional Resource The Contentstack class covers the retry options of contentstack.client() and their defaults.
Capability Matrix
| Capability | Supported | Notes / Alternative |
|---|---|---|
| Publish more items than the API limit in one call | No | Split the items into batches and send one request per batch |
| List all the bulk jobs of a stack | No | The SDK has no method for the bulk task queue. Keep the job ID of each bulk request |
| Wait for a bulk job to finish | No | Call jobStatus at an interval until the job completes |
Method Index
Publish, unpublish and delete in bulk. The methods in the table below are available on stack.bulkOperation().
| Method Name | Returns | Description |
|---|---|---|
| publish | The API response with a notice. | Publishes entries and assets in bulk. |
| unpublish | The API response with a notice. | Unpublishes entries and assets in bulk. |
| delete | The API response with a notice. | Deletes entries and assets in bulk. |
| update | The API response with a notice. | Changes the workflow details of entries in bulk. |
Manage release items in bulk. The methods in the table below are available on stack.bulkOperation().
| Method Name | Returns | Description |
|---|---|---|
| addItems | The API response, or undefined when the request fails. | Adds entries and assets to a release. |
| updateItems | The API response, or undefined when the request fails. | Updates the items of a release. |
Track bulk jobs. The methods in the table below are available on stack.bulkOperation().
| Method Name | Returns | Description |
|---|---|---|
| jobStatus | The job details, or undefined when the request fails. | Retrieves the status of a bulk job. |
| getJobItems | The job items, or undefined when the request fails. | Lists the items of a bulk job. |
Set request headers. The methods in the table below are available on stack.bulkOperation().
| Method Name | Returns | Description |
|---|---|---|
| addHeader | The same bulk operation object, for chaining. | Adds one request header. |
| addHeaderDict | The same bulk operation object, for chaining. | Adds several request headers. |
| removeHeader | The same bulk operation object, for chaining. | Removes one request header. |
Class-Level Snippet
The snippet below publishes one entry and one asset on one environment and locale in a single bulk request.
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const details = {
entries: [{ uid: '<ENTRY_UID>', content_type: '<CONTENT_TYPE_UID>', locale: '<LOCALE>' }],
assets: [{ uid: '<ASSET_UID>' }],
locales: ['<LOCALE>'],
environments: ['<ENVIRONMENT>']
}
try {
const response = await stack.bulkOperation().publish({ details })
console.log(response.notice)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}Methods
Each method of the BulkOperation class has its own section below, with its parameters, validation rules, behavior, and examples.
addHeader
addHeader adds one header to every request that this bulk operation object sends afterwards.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the request header. |
| value (required) | string | Value of the request header. |
Returns: BulkOperation. The same bulk operation object, for chaining.
Validation
- There is no client-side validation of the name or the value.
- A null or undefined key leaves the headers unchanged, and addHeader returns the object without an error.
- An invalid header surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. addHeader stores the header on this bulk operation object and sends no request.
- The first header method call on this object copies the headers it received from the stack, so the change applies to this bulk operation object only. The stack and other objects keep their headers.
- Every later request from this object sends the header. A key that already exists, such as branch, takes the new value.
Example
Basic usage: send this object's requests to another branch
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const bulk = stack.bulkOperation().addHeader('branch', '<BRANCH>')
console.log(bulk.stackHeaders)addHeaderDict
addHeaderDict adds several headers to every request that this bulk operation object sends afterwards.
| Name | Type | Description |
|---|---|---|
| headerDict (required) | object | Header names and values to add. |
Returns: BulkOperation. The same bulk operation object, for chaining.
Validation
- There is no client-side validation of the names or the values.
- A headerDict that is null, undefined or not an object leaves the headers unchanged, and addHeaderDict returns the object without an error.
- An invalid header surfaces as a rejected promise from the request method you call next.
Behavior
- Client-side only. addHeaderDict copies each key and value of headerDict into the headers of this bulk operation object and sends no request.
- The first header method call on this object copies the headers it received from the stack, so the change applies to this bulk operation object only. The stack and other objects keep their headers.
- A key that already exists, such as branch, takes the new value.
Example
Basic usage: add a branch and a request ID in one call
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const bulk = stack.bulkOperation().addHeaderDict({
branch: '<BRANCH>',
'x-request-id': 'docs-123'
})
console.log(bulk.stackHeaders)addItems
addItems adds many entries and assets to a release in one request. The following table lists its parameters.
| Name | Type | Description |
|---|---|---|
| options (required) | BulkAddItemsConfig | Request body and the bulk version. |
| options.data (required) | AnyProperty | Request body with the release and items. |
| options.data.release (required) | string | UID of the target release. |
| options.data.action (required) | string | publish or unpublish. |
| options.data.locale (required) | string[] | Locale codes of the entries. |
| options.data.reference | boolean | Adds the referenced items too. |
| options.data.items (required) | object[] | Items, by uid, content_type_uid, locale, version and title. |
| options.bulk_version | string | Bulk version header. The API requires 2.0. |
Returns: Promise<Response>. The API response, or undefined when the request fails.
Known issue When the request fails, addItems writes the error to the console and resolves to undefined instead of rejecting. Check the result for undefined before you read it.
Validation
- There is no client-side validation. The SDK sends options.data as you pass it.
- Calling addItems() with no argument returns a promise that rejects with TypeError, because addItems reads its options from one object.
- An API rejection or a network failure does not reject the promise. See the Known issue above.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call sends one Bulk Add to Release request (POST /v3/bulk/release/items) with options.data as the JSON body.
- A non-empty options.bulk_version goes as the bulk_version header. The API needs bulk_version: 2.0 for this request, so always pass '2.0'.
- With reference: true, the API also adds the items that the listed entries reference.
- The API adds the items in a background job. addItems resolves to the response body when the API accepts the request.
Example
Basic usage: add two entries to a release for publishing
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const data = {
release: '<RELEASE_UID>',
action: 'publish',
locale: ['<LOCALE>'],
items: [
{ uid: '<ENTRY_UID>', content_type_uid: '<CONTENT_TYPE_UID>', locale: '<LOCALE>', version: 1, title: 'Spring campaign' }
]
}
try {
const response = await stack.bulkOperation().addItems({ data, bulk_version: '2.0' })
if (response === undefined) {
// The request failed. The SDK wrote the error to the console.
console.error('Bulk add to release failed')
} else {
console.log(response.notice)
}
} catch (error) {
// A missing options object rejects here
console.error(error.message)
}All parameters: add entries with their referenced items
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const data = {
release: '<RELEASE_UID>',
action: 'publish',
locale: ['<LOCALE>'],
reference: true,
items: [
{ uid: '<ENTRY_UID>', content_type_uid: '<CONTENT_TYPE_UID>', locale: '<LOCALE>', version: 1, title: 'Spring campaign' }
]
}
try {
const response = await stack.bulkOperation().addItems({ data, bulk_version: '2.0' })
console.log(response ? response.notice : 'Bulk add to release failed')
} catch (error) { console.error(error.message) }delete
delete deletes many entries and assets in one request.
| Name | Type | Description |
|---|---|---|
| params | BulkDeleteConfig | Options with the items to delete. |
| params.details (required) | object | Request body with the entries and assets. |
| params.details.entries | BulkDeleteEntry[] | Entries, by uid, content_type and locale. |
| params.details.assets | BulkDeleteAsset[] | Assets, by uid. |
Returns: Promise<Response>. The API response with a notice.
Warning delete removes every listed entry and asset from the stack, and the SDK has no method that restores them.
Validation
- There is no client-side validation. The SDK sends params.details as you pass it.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call sends one Delete entries and assets in bulk request (POST /v3/bulk/delete) with params.details as the JSON body.
- delete reads only params.details. It ignores entries and assets at the top level of params, and then sends an empty body.
- One request deletes up to 100 entries.
- delete resolves to the response body, which holds notice.
Example
Basic usage: delete an entry and an asset
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const details = {
entries: [{ uid: '<ENTRY_UID>', content_type: '<CONTENT_TYPE_UID>', locale: '<LOCALE>' }],
assets: [{ uid: '<ASSET_UID>' }]
}
try {
const response = await stack.bulkOperation().delete({ details })
console.log(response.notice)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}getJobItems
getJobItems lists the items of one bulk publish or unpublish job, with the status of each item. The following table lists its parameters.
| Name | Type | Description |
|---|---|---|
| job_id (required) | string | ID of the bulk job. |
| params | BulkJobItemsParams | Query parameters and the API version. |
| params.api_version | string | API version header. An empty string sends none. |
| params.include_count | boolean | Adds the total number of items. |
| params.skip | number | Number of items to skip. |
| params.limit | number | Number of items to return, at most 100. |
| params.include_reference | boolean | Adds the referenced items. |
| params.status | string | success or failed. |
| params.type | string | entry or asset. |
| params.ct | string[] | string | Content type UIDs to filter by. |
Returns: Promise<BulkJobItemsResponse>. The job items, or undefined when the request fails.
Known issue When the request fails, getJobItems writes the error to the console and resolves to undefined instead of rejecting. Check the result for undefined before you read it.
Validation
- There is no client-side validation. A missing job_id puts undefined in the request path.
- An API rejection or a network failure does not reject the promise. See the Known issue above.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call sends one Get job items status request (GET /v3/bulk/jobs/{job_id}/items).
- The SDK sends params.api_version as the api_version header, 3.2 by default. It sends every other key of params as a query parameter.
- Pass ct as an array, so that the SDK sends one ct[] parameter per content type. A string goes as ct without brackets.
- The API returns the first 100 items at most. Use skip and limit to read the rest. The API returns the count only when skip is 0 or absent.
- The response holds items, and skip, limit and total_count when you pass include_count: true.
Example
Basic usage: list the items of a bulk job
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const result = await stack.bulkOperation().getJobItems('<JOB_UID>')
if (result === undefined) {
// The request failed. The SDK wrote the error to the console.
console.error('Job items request failed')
} else {
result.items.forEach((item) => console.log(item.uid, item.publish_details.status))
}
} catch (error) {
console.error(error.message)
}All parameters: list the failed entries of two content types
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const result = await stack.bulkOperation().getJobItems('<JOB_UID>', {
api_version: '3.2',
include_count: true,
skip: 0,
limit: 50,
include_reference: true,
status: 'failed',
type: 'entry',
ct: ['<CONTENT_TYPE_UID>', 'author']
})
console.log(result ? result.total_count : 'Job items request failed')
} catch (error) { console.error(error.message) }jobStatus
jobStatus retrieves the status and details of one bulk publish or unpublish job.
| Name | Type | Description |
|---|---|---|
| options (required) | BulkJobStatus | Job ID and version headers. |
| options.job_id (required) | string | ID of the bulk job. |
| options.bulk_version | string | Bulk version header. |
| options.api_version | string | API version header. The API requires 3.2. |
Returns: Promise<Response>. The job details, or undefined when the request fails.
Known issue When the request fails, jobStatus writes the error to the console and resolves to undefined instead of rejecting. Check the result for undefined before you read it.
Validation
- There is no client-side validation. A missing job_id puts undefined in the request path.
- Calling jobStatus() with no argument returns a promise that rejects with TypeError, because jobStatus reads its options from one object.
- An API rejection or a network failure does not reject the promise. See the Known issue above.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call sends one Get job status request (GET /v3/bulk/jobs/{job_id}).
- A non-empty bulk_version or api_version goes as a header of the same name. The API reference asks for api_version: 3.2, so pass it.
- jobStatus resolves to the response body as a plain object.
Example
Basic usage: read the status of a bulk job
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const job = await stack.bulkOperation().jobStatus({ job_id: '<JOB_UID>', api_version: '3.2' })
if (job === undefined) {
// The request failed. The SDK wrote the error to the console.
console.error('Job status request failed')
} else {
console.log(JSON.stringify(job, null, 2))
}
} catch (error) {
// A missing options object rejects here
console.error(error.message)
}All parameters: read the status with both version headers
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
try {
const job = await stack.bulkOperation().jobStatus({ job_id: '<JOB_UID>', bulk_version: '2.0', api_version: '3.2' })
console.log(job ? JSON.stringify(job) : 'Job status request failed')
} catch (error) { console.error(error.message) }publish
publish publishes many entries and assets on the environments and locales you name, in one request.
| Name | Type | Description |
|---|---|---|
| options (required) | BulkOperationConfig | Items, targets and request options. |
| options.details (required) | PublishItems | Request body with the items and targets. |
| options.details.entries | BulkOperationItem[] | Entries, by uid, content_type, locale and version. |
| options.details.assets | BulkOperationItem[] | Assets, by uid. |
| options.details.locales (required) | string[] | Locale codes to publish on. |
| options.details.environments (required) | string[] | Environment names to publish on. |
| options.skip_workflow_stage | boolean | Sends the skip_workflow_stage_check header. |
| options.approvals | boolean | Sends the approvals header. |
| options.is_nested | boolean | Adds nested=true and event_type=bulk to the query. |
| options.api_version | string | API version header, 3.2 for nested references. |
| options.publishAllLocalized | boolean | Adds publish_all_localized=true to the query. |
Returns: Promise<Response>. The API response with a notice.
Validation
- There is no client-side validation. The SDK sends options.details as you pass it, or an empty body when you omit it.
- Calling publish() with no argument returns a promise that rejects with TypeError, because publish reads its options from one object.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call sends one Publish entries and assets in bulk request (POST /v3/bulk/publish) with options.details as the JSON body.
- The SDK maps each option to the request as follows:
- skip_workflow_stage: true sends the header skip_workflow_stage_check: true.
- approvals: true sends the header approvals: true.
- is_nested: true adds the query parameters nested=true and event_type=bulk.
- api_version sends the header api_version.
- publishAllLocalized: true adds the query parameter publish_all_localized=true.
- The API reference lists skip_workflow_stage_check and approvals as query parameters. The SDK sends them as headers.
- With skip_workflow_stage_check, the API publishes the entries whose workflow stage satisfies the publish rules. With approvals, it publishes the entries that need no approval.
- To publish nested references up to five levels deep with their parent entries, pass api_version: '3.2'.
- When you omit version on an entry, the API publishes its latest version.
- The API publishes the items in a background job. publish resolves to the response body, which holds notice, when the API accepts the request.
Example
Basic usage: publish an entry and an asset
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const details = {
entries: [{ uid: '<ENTRY_UID>', content_type: '<CONTENT_TYPE_UID>', locale: '<LOCALE>', version: 1 }],
assets: [{ uid: '<ASSET_UID>' }],
locales: ['<LOCALE>'],
environments: ['<ENVIRONMENT>']
}
try {
const response = await stack.bulkOperation().publish({ details })
console.log(response.notice)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: publish nested references in all localized versions
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const details = {
entries: [{ uid: '<ENTRY_UID>', content_type: '<CONTENT_TYPE_UID>', locale: '<LOCALE>' }],
assets: [{ uid: '<ASSET_UID>' }],
locales: ['<LOCALE>'],
environments: ['<ENVIRONMENT>']
}
try {
const response = await stack.bulkOperation().publish({
details,
skip_workflow_stage: true,
approvals: true,
is_nested: true,
api_version: '3.2',
publishAllLocalized: true
})
console.log(response.notice)
} catch (error) { console.error(error.errorMessage) }removeHeader
removeHeader removes one header from the requests that this bulk operation object sends afterwards.
| Name | Type | Description |
|---|---|---|
| key (required) | string | Name of the header to remove. |
Returns: BulkOperation. The same bulk operation object, for chaining.
Validation
- There is no client-side validation.
- A null or undefined key, or a key that the object does not hold, leaves the headers unchanged, and removeHeader returns the object without an error.
- Removing api_key makes the next request fail with an API error, because every stack request needs the API key.
Behavior
- Client-side only. removeHeader deletes the header from this bulk operation object and sends no request.
- When the header came from the stack, the SDK first copies the headers, so the stack and other objects keep it.
- The management token and the authtoken live on the client, not on this object. removeHeader('authorization') does not remove them.
Example
Basic usage: stop sending the branch header from one object
import contentstack from '@contentstack/management'
const client = contentstack.client()
// This stack sends a branch header on every request
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>', branch_uid: '<BRANCH>' })
const bulk = stack.bulkOperation().removeHeader('branch')
console.log(bulk.stackHeaders)unpublish
unpublish unpublishes many entries and assets from the environments and locales you name, in one request.
| Name | Type | Description |
|---|---|---|
| options (required) | BulkOperationConfig | Items, targets and request options. |
| options.details (required) | PublishItems | Request body with the items and targets. |
| options.details.entries | BulkOperationItem[] | Entries, by uid, content_type, locale and version. |
| options.details.assets | BulkOperationItem[] | Assets, by uid. |
| options.details.locales (required) | string[] | Locale codes to unpublish from. |
| options.details.environments (required) | string[] | Environment names to unpublish from. |
| options.skip_workflow_stage | boolean | Sends the skip_workflow_stage_check header. |
| options.approvals | boolean | Sends the approvals header. |
| options.is_nested | boolean | Adds nested=true and event_type=bulk to the query. |
| options.api_version | string | API version header, 3.2 for nested references. |
| options.unpublishAllLocalized | boolean | Adds publish_all_localized=true to the query. |
Returns: Promise<Response>. The API response with a notice.
Warning unpublish removes every listed item from the environments you name, so delivery requests on those environments stop returning them. Publish the items again to restore them.
Validation
- There is no client-side validation. The SDK sends options.details as you pass it, or an empty body when you omit it.
- Calling unpublish() with no argument returns a promise that rejects with TypeError, because unpublish reads its options from one object.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call sends one Unpublish entries and assets in bulk request (POST /v3/bulk/unpublish) with options.details as the JSON body.
- The SDK maps each option to the request as follows:
- skip_workflow_stage: true sends the header skip_workflow_stage_check: true.
- approvals: true sends the header approvals: true.
- is_nested: true adds the query parameters nested=true and event_type=bulk.
- api_version sends the header api_version.
- unpublishAllLocalized: true adds the query parameter publish_all_localized=true, the same parameter that publish uses.
- The API reference lists skip_workflow_stage_check and approvals as query parameters. The SDK sends them as headers.
- With api_version: '3.2', the API logs the unpublish task in the nested reference flow.
- The API unpublishes the items in a background job. unpublish resolves to the response body, which holds notice, when the API accepts the request.
Example
Basic usage: unpublish an entry and an asset
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const details = {
entries: [{ uid: '<ENTRY_UID>', content_type: '<CONTENT_TYPE_UID>', locale: '<LOCALE>' }],
assets: [{ uid: '<ASSET_UID>' }],
locales: ['<LOCALE>'],
environments: ['<ENVIRONMENT>']
}
try {
const response = await stack.bulkOperation().unpublish({ details })
console.log(response.notice)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: unpublish nested references in all localized versions
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const details = {
entries: [{ uid: '<ENTRY_UID>', content_type: '<CONTENT_TYPE_UID>', locale: '<LOCALE>' }],
locales: ['<LOCALE>'],
environments: ['<ENVIRONMENT>']
}
try {
const response = await stack.bulkOperation().unpublish({
details,
skip_workflow_stage: true,
approvals: true,
is_nested: true,
api_version: '3.2',
unpublishAllLocalized: true
})
console.log(response.notice)
} catch (error) { console.error(error.errorMessage) }update
update changes the workflow stage, assignees, due date and comment of many entries in one request.
| Name | Type | Description |
|---|---|---|
| updateBody | object | Request body with the entries and workflow details. |
| updateBody.entries (required) | object[] | Entries, by uid, content_type and locale. |
| updateBody.workflow.workflow_stage.uid (required) | string | UID of the new workflow stage. |
| updateBody.workflow.workflow_stage.comment | string | Comment for the assigned users. |
| updateBody.workflow.workflow_stage.due_date | string | Due date for the stage. |
| updateBody.workflow.workflow_stage.notify | boolean | Notifies the assigned users. |
| updateBody.workflow.workflow_stage.assigned_to | object[] | Users to assign, by uid, name and email. |
| updateBody.workflow.workflow_stage.assigned_by_roles | object[] | Roles to assign, by uid and name. |
Returns: Promise<Response>. The API response with a notice.
Validation
- There is no client-side validation. The SDK sends updateBody as you pass it.
- The returned promise rejects with an Error when the API rejects the request. The error carries status, statusText, errorMessage, errorCode and errors from the API response.
- The API changes the stage only when every listed entry sits at the same workflow stage of the same workflow.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call sends one Update workflow details in bulk request (POST /v3/bulk/workflow) with updateBody as the JSON body.
- Unlike the other bulk methods, update takes the request body itself, not an options object with details.
- update resolves to the response body, which holds notice.
Example
Basic usage: move two entries to the next workflow stage
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const updateBody = {
entries: [
{ uid: '<ENTRY_UID>', content_type: '<CONTENT_TYPE_UID>', locale: '<LOCALE>' }
],
workflow: {
workflow_stage: { uid: '<WORKFLOW_STAGE_UID>' }
}
}
try {
const response = await stack.bulkOperation().update(updateBody)
console.log(response.notice)
} catch (error) {
// The API rejected the request. The error carries status, errorCode, errorMessage and errors.
console.error(error.status, error.errorCode, error.errorMessage)
}All parameters: change the stage, assign a user and a role, and notify them
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const updateBody = {
entries: [
{ uid: '<ENTRY_UID>', content_type: '<CONTENT_TYPE_UID>', locale: '<LOCALE>' }
],
workflow: {
workflow_stage: {
uid: '<WORKFLOW_STAGE_UID>',
comment: 'Ready for legal review',
due_date: '2026-12-01',
notify: true,
assigned_to: [{ uid: '<USER_UID>', name: 'Jane Doe', email: '<COLLABORATOR_EMAIL>' }],
assigned_by_roles: [{ uid: '<ROLE_UID>', name: 'Content Manager' }]
}
}
}
try {
const response = await stack.bulkOperation().update(updateBody)
console.log(response.notice)
} catch (error) { console.error(error.errorMessage) }updateItems
updateItems updates the items of a release in bulk, for example to their latest versions.
| Name | Type | Description |
|---|---|---|
| options (required) | BulkAddItemsConfig | Request body and the bulk version. |
| options.data (required) | AnyProperty | Request body with the release and items. |
| options.bulk_version | string | Bulk version header, for example 2.0. |
Returns: Promise<Response>. The API response, or undefined when the request fails.
Known issue When the request fails, updateItems writes the error to the console and resolves to undefined instead of rejecting. Check the result for undefined before you read it.
Validation
- There is no client-side validation. The SDK sends options.data as you pass it.
- Calling updateItems() with no argument returns a promise that rejects with TypeError, because updateItems reads its options from one object.
- An API rejection or a network failure does not reject the promise. See the Known issue above.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- One call sends one PUT /v3/bulk/release/update_items request with options.data as the JSON body.
- A non-empty options.bulk_version goes as the bulk_version header.
- The body names the release and the items. items: ['$all'] selects every item in the release, as in the Update Release items to their latest versions request.
- updateItems resolves to the response body when the API accepts the request.
Example
Basic usage: update every item of a release to its latest version
import contentstack from '@contentstack/management'
const client = contentstack.client()
const stack = client.stack({ api_key: '<API_KEY>', management_token: '<MANAGEMENT_TOKEN>' })
const data = {
release: '<RELEASE_UID>',
action: 'publish',
locale: ['<LOCALE>'],
reference: true,
items: ['$all']
}
try {
const response = await stack.bulkOperation().updateItems({ data, bulk_version: '2.0' })
if (response === undefined) {
// The request failed. The SDK wrote the error to the console.
console.error('Bulk update of release items failed')
} else {
console.log(response.notice)
}
} catch (error) {
// A missing options object rejects here
console.error(error.message)
}