BulkOperation

View as Markdown

BulkOperation

A bulk operation acts on many entries and assets in one request. Use this class to

  • publish or unpublish entries and assets on several environments and locales
  • delete entries and assets
  • change the workflow stage of several entries
  • add items to a Release as a bulk job, and read the status of a bulk job

stack.bulkOperation() returns a BulkOperation. BulkOperation has no public constructor and takes no UID.

addHeader

addHeader adds one request header to this bulk operation.

NameTypeDescription
key (required)String

Name of the header.

Default: Not applicable
value (required)String

Value of the header.

Default: Not applicable

Returns: BulkOperation. The same bulk operation, for chaining.

Validation

  • There is no client-side validation. A null key or value does not throw here.
  • execute() throws IllegalArgumentException for a null key or value, because Retrofit rejects null entries in a header map.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • addHeader stores the header in the header map of this object and sends nothing.
  • A later call with the same name replaces the value.
  • The header goes on every request of this bulk operation object, and stays there for every later request.
  • addReleaseItems, updateReleaseItems, and jobStatus remove any bulk_version header from the map when they build their request.

Example

Basic usage: publish nested references with api_version 3.2

import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;
import java.util.Collections;

public class PublishNestedReferences {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        JSONObject entry = new JSONObject();
        entry.put("uid", "<ENTRY_UID>");
        entry.put("content_type", "<CONTENT_TYPE_UID>");
        entry.put("locale", "<LOCALE>");

        JSONObject body = new JSONObject();
        body.put("entries", Collections.singletonList(entry));
        body.put("locales", Collections.singletonList("<LOCALE>"));
        body.put("environments", Collections.singletonList("<ENVIRONMENT>"));

        Response<ResponseBody> response = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
                .bulkOperation()
                .addHeader("api_version", "3.2")
                .publish(body)
                .execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

addHeaders

addHeaders adds every entry of a map to the request headers of this bulk operation.

NameTypeDescription
headers (required)HashMap

Header names mapped to their values.

Default: Not applicable

Returns: BulkOperation. The same bulk operation, for chaining.

Validation

  • Throws NullPointerException if headers is null, because addHeaders copies every entry of the map.
  • execute() throws IllegalArgumentException for a null key or value in the map, because Retrofit rejects null entries in a header map.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • addHeaders copies the entries into the header map of this object and sends nothing.
  • An entry replaces a header with the same name.
  • The headers go on every request of this bulk operation object, and stay there for every later request.
  • addReleaseItems, updateReleaseItems, and jobStatus remove any bulk_version header from the map when they build their request.

Example

Basic usage: publish on a branch with api_version 3.2

import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;
import java.util.Collections;
import java.util.HashMap;

public class PublishOnBranch {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        JSONObject entry = new JSONObject();
        entry.put("uid", "<ENTRY_UID>");
        entry.put("content_type", "<CONTENT_TYPE_UID>");
        entry.put("locale", "<LOCALE>");

        JSONObject body = new JSONObject();
        body.put("entries", Collections.singletonList(entry));
        body.put("locales", Collections.singletonList("<LOCALE>"));
        body.put("environments", Collections.singletonList("<ENVIRONMENT>"));

        HashMap<String, String> headers = new HashMap<>();
        headers.put("api_version", "3.2");
        headers.put("branch", "<BRANCH>");

        Response<ResponseBody> response = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
                .bulkOperation()
                .addHeaders(headers)
                .publish(body)
                .execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

addParam

addParam adds one query parameter to this bulk operation.

NameTypeDescription
key (required)String

Name of the query parameter.

Default: Not applicable
value (required)Object

Value of the query parameter, sent as its string form.

Default: Not applicable

Returns: BulkOperation. The same bulk operation, for chaining.

Validation

  • There is no client-side validation. A null key or value does not throw here.
  • execute() throws IllegalArgumentException for a null key or value, because Retrofit rejects null entries in a query map.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • addParam stores the pair in the query parameter map of this object and sends nothing.
  • A later call with the same key replaces the value.
  • The parameter goes on every request of this bulk operation object.
  • The parameter stays on the object for every later request.

Example

Basic usage: skip the workflow stage check in a bulk publish

import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;
import java.util.Collections;

public class PublishSkippingStageCheck {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        JSONObject entry = new JSONObject();
        entry.put("uid", "<ENTRY_UID>");
        entry.put("content_type", "<CONTENT_TYPE_UID>");
        entry.put("locale", "<LOCALE>");

        JSONObject body = new JSONObject();
        body.put("entries", Collections.singletonList(entry));
        body.put("locales", Collections.singletonList("<LOCALE>"));
        body.put("environments", Collections.singletonList("<ENVIRONMENT>"));

        Response<ResponseBody> response = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
                .bulkOperation()
                .addParam("skip_workflow_stage_check", true)
                .publish(body)
                .execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

addParams

addParams adds every entry of a map to the query parameters of this bulk operation.

NameTypeDescription
params (required)HashMap

Query parameter names mapped to their values.

Default: Not applicable

Returns: BulkOperation. The same bulk operation, for chaining.

Validation

  • Throws NullPointerException if params is null, because addParams copies every entry of the map.
  • execute() throws IllegalArgumentException for a null key or value in the map, because Retrofit rejects null entries in a query map.
  • An invalid value surfaces as an API error in the response when you call execute() on the request this method feeds.

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • addParams copies the entries into the query parameter map of this object and sends nothing.
  • An entry replaces a parameter with the same name.
  • The parameters go on every request of this bulk operation object.
  • The parameters stay on the object for every later request.

Example

Basic usage: publish the items that pass the publish rules

import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;
import java.util.Collections;
import java.util.HashMap;

public class PublishWithRules {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        JSONObject entry = new JSONObject();
        entry.put("uid", "<ENTRY_UID>");
        entry.put("content_type", "<CONTENT_TYPE_UID>");
        entry.put("locale", "<LOCALE>");

        JSONObject body = new JSONObject();
        body.put("entries", Collections.singletonList(entry));
        body.put("locales", Collections.singletonList("<LOCALE>"));
        body.put("environments", Collections.singletonList("<ENVIRONMENT>"));

        HashMap<String, Object> params = new HashMap<>();
        params.put("skip_workflow_stage_check", true);
        params.put("approvals", true);

        Response<ResponseBody> response = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
                .bulkOperation()
                .addParams(params)
                .publish(body)
                .execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

addReleaseItems

addReleaseItems builds the request that adds several entries and assets to a Release as a bulk job.

NameTypeDescription
jsonBody (required)JSONObject

Request body with the Release UID, action, locale, and items.

Default: Not applicable
jsonBody.release (required)String

UID of the Release to add the items to.

Default: Not applicable
jsonBody.action (required)String

publish or unpublish.

Default: Not applicable
jsonBody.locale (required)List<String>

Locales of the entries.

Default: Not applicable
jsonBody.referenceBoolean

true also adds the referenced items.

Default: Not set
jsonBody.items (required)List<JSONObject>

Items, each with uid, content_type_uid, title, and an optional locale and version.

Default: Not applicable

Returns: Call<ResponseBody>. The request that adds the items to the Release, sent when you call execute().

Validation

  • There is no client-side validation of jsonBody. The SDK sends it unchanged.
  • execute() throws IllegalArgumentException if jsonBody is null, because Retrofit cannot build a request without a body.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • One execute() sends one Bulk Add to Release request (POST /bulk/release/items) with jsonBody as the JSON body and the headers and query parameters of this object.
  • The API reference marks the bulk_version: 2.0 header as required for this request.
  • For an asset, set content_type_uid to sys_assets, as the API reference shows.
  • To add items to one Release without a bulk job, use the createMultiple method of ReleaseItem.

Example

Basic usage: add an entry and its references to a Release

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.BulkOperation;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Call;
import retrofit2.Response;

import java.io.IOException;
import java.util.Collections;

public class BulkAddToRelease {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        JSONObject entry = new JSONObject();
        entry.put("uid", "<ENTRY_UID>");
        entry.put("content_type_uid", "<CONTENT_TYPE_UID>");
        entry.put("locale", "<LOCALE>");
        entry.put("title", "Spring launch");

        JSONObject body = new JSONObject();
        body.put("release", "<RELEASE_UID>");
        body.put("action", "publish");
        body.put("locale", Collections.singletonList("<LOCALE>"));
        body.put("reference", true);
        body.put("items", Collections.singletonList(entry));

        BulkOperation bulk = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").bulkOperation();
        Call<ResponseBody> call = bulk.addReleaseItems(body);
        // Add bulk_version after the call is built, so the request carries it
        bulk.addHeader("bulk_version", "2.0");

        Response<ResponseBody> response = call.execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

delete

delete builds the request that deletes several entries and assets from the stack.

NameTypeDescription
body (required)JSONObject

Request body with the items to delete.

Default: Not applicable
body.entriesList<JSONObject>

Entries to delete, each with uid, content_type, and locale.

Default: Not set
body.assetsList<JSONObject>

Assets to delete, each with uid.

Default: Not set

Returns: Call<ResponseBody>. The request that deletes the entries and assets, sent when you call execute().

Validation

  • There is no client-side validation of body. The SDK sends it unchanged.
  • execute() throws IllegalArgumentException if body is null, because Retrofit cannot build a request without a body.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • One execute() sends one Delete entries and assets in bulk request (POST /bulk/delete). It uses body as the JSON body with the headers and query parameters of this object.
  • One request deletes up to 100 entries, as the API reference states.

Example

Basic usage: delete an entry and an asset

import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;
import java.util.Collections;

public class BulkDelete {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        JSONObject entry = new JSONObject();
        entry.put("uid", "<ENTRY_UID>");
        entry.put("content_type", "<CONTENT_TYPE_UID>");
        entry.put("locale", "<LOCALE>");
        JSONObject asset = new JSONObject();
        asset.put("uid", "<ASSET_UID>");

        JSONObject body = new JSONObject();
        body.put("entries", Collections.singletonList(entry));
        body.put("assets", Collections.singletonList(asset));

        Response<ResponseBody> response = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
                .bulkOperation()
                .delete(body)
                .execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

jobStatus

jobStatus builds the request that reads the status of one bulk publish or unpublish job.

NameTypeDescription
jobUid (required)String

UID of the bulk job to read.

Default: Not applicable

Returns: Call<ResponseBody>. The request for the job status, sent when you call execute().

Validation

  • There is no client-side validation of jobUid.
  • execute() throws IllegalArgumentException if jobUid is null, because Retrofit cannot fill the request path with null.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • One execute() sends one Get job status request (GET /bulk/jobs/{job_id}) with the headers and query parameters of this object.
  • The API reference marks the api_version: 3.2 header as required for this request. Add it with addHeader.
  • jobStatus sends no bulk_version header, because it removes the header from the map when it builds the request.

Example

Basic usage: read the status of a bulk job

import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import retrofit2.Response;

import java.io.IOException;

public class ReadBulkJobStatus {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        Response<ResponseBody> response = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
                .bulkOperation()
                .addHeader("api_version", "3.2")
                .jobStatus("<JOB_UID>")
                .execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

publish

publish builds the request that publishes several entries and assets to the environments and locales you list.

NameTypeDescription
body (required)JSONObject

Request body with the items, locales, and environments.

Default: Not applicable
body.entriesList<JSONObject>

Entries to publish, each with uid, content_type, locale, and an optional version.

Default: Not set
body.assetsList<JSONObject>

Assets to publish, each with uid and an optional version.

Default: Not set
body.locales (required)List<String>

Locale codes to publish in.

Default: Not applicable
body.environments (required)List<String>

Environment names to publish on.

Default: Not applicable

Returns: Call<ResponseBody>. The request that publishes the entries and assets, sent when you call execute().

Validation

  • There is no client-side validation of body. The SDK sends it unchanged.
  • execute() throws IllegalArgumentException if body is null, because Retrofit cannot build a request without a body.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • One execute() sends one Publish entries and assets in bulk request (POST /bulk/publish). It uses body as the JSON body and the headers and query parameters of this object.
  • One request publishes up to 10 entries in 10 locales and on 10 environments, as the API reference states.
  • Without a version on an entry, the API publishes its latest version.
  • Send api_version: 3.2 with addHeader to publish nested references, up to five levels deep, with their parent entries.
  • The API reference lists two query parameters, which you add with addParam:
    • skip_workflow_stage_check: true acts only on the entries whose workflow stage satisfies the publish rules.
    • approvals: true acts only on the entries that need no approval.

Example

Basic usage: publish an entry and an asset

import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;
import java.util.Collections;

public class BulkPublish {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        JSONObject entry = new JSONObject();
        entry.put("uid", "<ENTRY_UID>");
        entry.put("content_type", "<CONTENT_TYPE_UID>");
        entry.put("locale", "<LOCALE>");
        JSONObject asset = new JSONObject();
        asset.put("uid", "<ASSET_UID>");

        JSONObject body = new JSONObject();
        body.put("entries", Collections.singletonList(entry));
        body.put("assets", Collections.singletonList(asset));
        body.put("locales", Collections.singletonList("<LOCALE>"));
        body.put("environments", Collections.singletonList("<ENVIRONMENT>"));

        Response<ResponseBody> response = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
                .bulkOperation()
                .publish(body)
                .execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

All options: publish with nested references and publish rules

import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;
import java.util.Collections;

public class BulkPublishNested {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        JSONObject entry = new JSONObject();
        entry.put("uid", "<ENTRY_UID>");
        entry.put("content_type", "<CONTENT_TYPE_UID>");
        entry.put("locale", "<LOCALE>");
        JSONObject asset = new JSONObject();
        asset.put("uid", "<ASSET_UID>");

        JSONObject body = new JSONObject();
        body.put("entries", Collections.singletonList(entry));
        body.put("assets", Collections.singletonList(asset));
        body.put("locales", Collections.singletonList("<LOCALE>"));
        body.put("environments", Collections.singletonList("<ENVIRONMENT>"));

        Response<ResponseBody> response = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
                .bulkOperation()
                .addHeader("api_version", "3.2")
                .addParam("skip_workflow_stage_check", true)
                .addParam("approvals", true)
                .publish(body)
                .execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

unpublish

unpublish builds the request that unpublishes several entries and assets from the environments and locales you list.

NameTypeDescription
body (required)JSONObject

Request body with the items, locales, and environments.

Default: Not applicable
body.entriesList<JSONObject>

Entries to unpublish, each with uid, content_type, locale, and an optional version.

Default: Not set
body.assetsList<JSONObject>

Assets to unpublish, each with uid and an optional version.

Default: Not set
body.locales (required)List<String>

Locale codes to unpublish in.

Default: Not applicable
body.environments (required)List<String>

Environment names to unpublish on.

Default: Not applicable

Returns: Call<ResponseBody>. The request that unpublishes the entries and assets, sent when you call execute().

Validation

  • There is no client-side validation of body. The SDK sends it unchanged.
  • execute() throws IllegalArgumentException if body is null, because Retrofit cannot build a request without a body.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • One execute() sends one Unpublish entries and assets in bulk request (POST /bulk/unpublish). The request uses body as the JSON body and the headers and query parameters of this object.
  • One request unpublishes up to 10 entries in 10 locales and on 10 environments, as the API reference states.
  • Send api_version: 3.2 with addHeader to get the logs of the unpublish task in the nested reference format.
  • The API reference lists two query parameters, which you add with addParam:
    • skip_workflow_stage_check: true acts only on the entries whose workflow stage satisfies the publish rules.
    • approvals: true acts only on the entries that need no approval.

Example

Basic usage: unpublish an entry and an asset

import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;
import java.util.Collections;

public class BulkUnpublish {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        JSONObject entry = new JSONObject();
        entry.put("uid", "<ENTRY_UID>");
        entry.put("content_type", "<CONTENT_TYPE_UID>");
        entry.put("locale", "<LOCALE>");
        JSONObject asset = new JSONObject();
        asset.put("uid", "<ASSET_UID>");

        JSONObject body = new JSONObject();
        body.put("entries", Collections.singletonList(entry));
        body.put("assets", Collections.singletonList(asset));
        body.put("locales", Collections.singletonList("<LOCALE>"));
        body.put("environments", Collections.singletonList("<ENVIRONMENT>"));

        Response<ResponseBody> response = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
                .bulkOperation()
                .unpublish(body)
                .execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

All options: unpublish the items that pass the publish rules

import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;
import java.util.Collections;

public class BulkUnpublishWithRules {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        JSONObject entry = new JSONObject();
        entry.put("uid", "<ENTRY_UID>");
        entry.put("content_type", "<CONTENT_TYPE_UID>");
        entry.put("locale", "<LOCALE>");
        JSONObject asset = new JSONObject();
        asset.put("uid", "<ASSET_UID>");

        JSONObject body = new JSONObject();
        body.put("entries", Collections.singletonList(entry));
        body.put("assets", Collections.singletonList(asset));
        body.put("locales", Collections.singletonList("<LOCALE>"));
        body.put("environments", Collections.singletonList("<ENVIRONMENT>"));

        Response<ResponseBody> response = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
                .bulkOperation()
                .addHeader("api_version", "3.2")
                .addParam("skip_workflow_stage_check", true)
                .addParam("approvals", true)
                .unpublish(body)
                .execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

updateReleaseItems

updateReleaseItems builds the request that updates the items of a Release to their latest versions as a bulk job.

NameTypeDescription
jsonBody (required)JSONObject

Request body that names the Release and the items to update.

Default: Not applicable

Returns: Call<ResponseBody>. The request that updates the Release items, sent when you call execute().

Validation

  • There is no client-side validation of jsonBody. The SDK sends it unchanged.
  • execute() throws IllegalArgumentException if jsonBody is null, because Retrofit cannot build a request without a body.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().

Additional Resource Refer to Content Management API Errors for the full error code list.

Behavior

  • One execute() sends PUT /bulk/release/update_items with jsonBody as the JSON body and the headers and query parameters of this object.
  • The Bulk Operations reference does not list this request. To update the items of one Release, the update method of ReleaseItem sends the documented request.

Example

Basic usage: update the items of a Release

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.BulkOperation;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Call;
import retrofit2.Response;

import java.io.IOException;
import java.util.Collections;

public class BulkUpdateReleaseItems {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        JSONObject body = new JSONObject();
        body.put("release", "<RELEASE_UID>");
        body.put("action", "publish");
        body.put("locale", Collections.singletonList("<LOCALE>"));
        body.put("reference", true);
        body.put("items", Collections.singletonList("$all"));

        BulkOperation bulk = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").bulkOperation();
        Call<ResponseBody> call = bulk.updateReleaseItems(body);
        // Add bulk_version after the call is built, so the request carries it
        bulk.addHeader("bulk_version", "2.0");

        Response<ResponseBody> response = call.execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}

updateWorkflow

updateWorkflow builds the request that changes the workflow details of several entries, such as the stage, assignee, due date, and comment.

NameTypeDescription
body (required)JSONObject

Request body with the entries and the workflow details.

Default: Not applicable
body.entries (required)List<JSONObject>

Entries to change, each with uid, content_type, and locale.

Default: Not applicable
body.workflow (required)JSONObject

Workflow stage details: stage UID, comment, due date, notification setting, and assigned users.

Default: Not applicable

Returns: Call<ResponseBody>. The request that updates the workflow details, sent when you call execute().

Validation

  • There is no client-side validation of body. The SDK sends it unchanged.
  • execute() throws IllegalArgumentException if body is null, because Retrofit cannot build a request without a body.
  • An API rejection does not throw. response.isSuccessful() is false and the error details are in response.errorBody().
  • The API changes the workflow stage only when all the entries sit 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 execute() sends one Update workflow details in bulk request (POST /bulk/workflow) with body as the JSON body and the headers and query parameters of this object.

Example

Basic usage: move entries to a review stage

import com.contentstack.cms.Contentstack;
import okhttp3.ResponseBody;
import org.json.simple.JSONObject;
import retrofit2.Response;

import java.io.IOException;
import java.util.Collections;

public class BulkUpdateWorkflow {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();

        JSONObject entry = new JSONObject();
        entry.put("uid", "<ENTRY_UID>");
        entry.put("content_type", "<CONTENT_TYPE_UID>");
        entry.put("locale", "<LOCALE>");

        // Replace the sample UIDs with the UIDs of your user and workflow stage
        JSONObject user = new JSONObject();
        user.put("uid", "blt0123456789abcdef");
        user.put("name", "Jane Doe");
        user.put("email", "[email protected]");

        JSONObject stage = new JSONObject();
        stage.put("uid", "blt0fedcba987654321");
        stage.put("comment", "Ready for review");
        stage.put("due_date", "2026-12-01");
        stage.put("notify", true);
        stage.put("assigned_to", Collections.singletonList(user));

        JSONObject workflow = new JSONObject();
        workflow.put("workflow_stage", stage);

        JSONObject body = new JSONObject();
        body.put("entries", Collections.singletonList(entry));
        body.put("workflow", workflow);

        Response<ResponseBody> response = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>")
                .bulkOperation()
                .updateWorkflow(body)
                .execute();
        if (!response.isSuccessful()) {
            // The API rejected the request. The body holds error_message, error_code and errors.
            System.out.println("Request failed: " + response.code() + " " + response.errorBody().string());
            return;
        }
        System.out.println(response.body().string());
    }
}