Workflow

View as Markdown

Workflow

A workflow moves content through review stages before it goes live, and publish rules decide who must approve a publish or unpublish. The Workflow class builds the Content Management API requests that manage the workflows and publish rules of one stack. Use this class to

  • list, read, create, update, enable, disable and delete workflows
  • create, read, update and delete publish rules
  • read the publish rules of one content type

Call the workflow method of the Stack class to get an instance.

addHeader

addHeader adds one header to every request that this Workflow object builds.

NameTypeDescription
key (required)String

Names the header.

Default: Not applicable
value (required)String

Sets the header value.

Default: Not applicable

Returns: Workflow. The same workflow, for chaining.

Validation

  • There is no client-side validation. addHeader stores any name and value.
  • A null name or value makes execute() throw IllegalArgumentException, because Retrofit rejects a null header map entry.
  • 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

  • Client-side only. addHeader stores the header on this object and sends no request.
  • Every request method of Workflow sends the header, together with the headers that the object copied from the stack, such as api_key and authorization.
  • A second call with the same name replaces the value. A name that matches a stack header, such as branch, replaces that header for this object.
  • The header stays on this object only. The stack and other objects keep their own headers.

Example

Basic usage: send an extra header with each request

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

import java.io.IOException;

public class AddWorkflowHeader {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow();
        workflow.addHeader("X-Request-Id", "list-workflows-01");

        Response<ResponseBody> response = workflow.find().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 as a header of the requests that this Workflow object builds.

NameTypeDescription
headers (required)HashMap<String, String>

Maps each header name to its value.

Default: Not applicable

Returns: Workflow. The same workflow, for chaining.

Validation

  • Throws NullPointerException if the map is null, because addHeaders copies its entries.
  • A null name or value in the map makes execute() throw IllegalArgumentException, because Retrofit rejects a null header map entry.
  • 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

  • Client-side only. addHeaders copies the entries into the headers of this object and sends no request.
  • A name that already exists takes the new value. Headers that the map does not name stay as they are.
  • Every request method of Workflow sends the headers.
  • The header stays on this object only. The stack and other objects keep their own headers.
  • The addHeader method adds one header at a time.

Example

Basic usage: send two extra headers with each request

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

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

public class AddWorkflowHeaders {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow();
        HashMap<String, String> headers = new HashMap<>();
        headers.put("X-Request-Id", "list-workflows-01");
        headers.put("X-Client-Name", "workflow-audit");
        workflow.addHeaders(headers);

        Response<ResponseBody> response = workflow.find().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 Workflow object, for the requests that send query parameters.

NameTypeDescription
key (required)String

Names the query parameter.

Default: Not applicable
value (required)Object

Sets the parameter value, sent as its string form.

Default: Not applicable

Returns: Workflow. The same workflow, for chaining.

Validation

  • There is no client-side validation. addParam stores any key and value.
  • A null key or value makes execute() throw IllegalArgumentException, because Retrofit rejects a null query map entry.
  • 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

Example

Basic usage: read the publish rules of a content type for one action

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

import java.io.IOException;

public class AddWorkflowParam {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow();
        workflow.addParam("action", "publish");

        Response<ResponseBody> response = workflow.fetchPublishRuleContentType("<CONTENT_TYPE_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());
    }
}

addParams

addParams adds every entry of a map as a query parameter of this Workflow object.

NameTypeDescription
params (required)HashMap<String, Object>

Maps each query parameter name to its value.

Default: Not applicable

Returns: Workflow. The same workflow, for chaining.

Validation

  • Throws NullPointerException if the map is null, because addParams copies its entries.
  • A null key or value in the map makes execute() throw IllegalArgumentException, because Retrofit rejects a null query map entry.
  • 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

  • Client-side only. addParams copies the entries into the parameters of this object and sends no request.
  • A key that already exists takes the new value. Parameters that the map does not name stay as they are.
  • Only the following requests send the stored parameters: find, fetchPublishRules, fetchPublishRuleContentType and fetchTasks.
  • The addParam method adds one parameter at a time.

Example

Basic usage: narrow the publish rules of a content type to an action, locale and environment

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

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

public class AddWorkflowParams {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow();
        HashMap<String, Object> query = new HashMap<>();
        query.put("action", "publish");
        query.put("locale", "<LOCALE>");
        query.put("environment", "<ENVIRONMENT>");
        workflow.addParams(query);

        Response<ResponseBody> response = workflow.fetchPublishRuleContentType("<CONTENT_TYPE_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());
    }
}

create

create creates a workflow in the stack from the details in the request body.

NameTypeDescription
requestBody (required)JSONObject

Holds the workflow details under a workflow key.

Default: Not applicable
requestBody.workflow.name (required)String

Names the workflow.

Default: Not applicable
requestBody.workflow.content_types (required)Array

Lists the content types the workflow covers.

Default: Not applicable
requestBody.workflow.branches (required)Array

Lists the branches the workflow applies to.

Default: Not applicable
requestBody.workflow.workflow_stages (required)Array

Lists the stages, each of which can carry entry_lock.

Default: Not applicable

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

Validation

  • There is no client-side validation. create sends the body unchanged.
  • A null body makes execute() throw IllegalArgumentException, 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

  • Sends POST /v3/workflows with the body as JSON, as Create a Workflow describes.
  • The body can also name the owners and a description. Add entry_lock inside a stage to control who can edit an entry at that stage.
  • Workflow superusers, organization owners and stack owners or admins can edit or delete an entry at any stage, whatever the stage rules say.
  • Sends no query parameters. create ignores the UID of the instance.

Example

Basic usage: create a two-stage workflow

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

import java.io.IOException;

public class CreateWorkflow {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow();

        JSONObject review = new JSONObject();
        review.put("name", "Review");
        review.put("color", "#2196f3");
        JSONObject approved = new JSONObject();
        approved.put("name", "Approved");
        approved.put("color", "#74ba76");
        JSONArray stages = new JSONArray();
        stages.add(review);
        stages.add(approved);
        JSONArray contentTypes = new JSONArray();
        contentTypes.add("<CONTENT_TYPE_UID>");
        JSONArray branches = new JSONArray();
        branches.add("main");

        JSONObject details = new JSONObject();
        details.put("name", "docs-test-editorial");
        details.put("content_types", contentTypes);
        details.put("branches", branches);
        details.put("workflow_stages", stages);
        JSONObject body = new JSONObject();
        body.put("workflow", details);

        Response<ResponseBody> response = workflow.create(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());
    }
}

createPublishRule

createPublishRule creates a publish rule for a workflow of the stack.

NameTypeDescription
requestBody (required)JSONObject

Holds the rule under a publishing_rule key.

Default: Not applicable
requestBody.publishing_rule.branches (required)Array

Lists the branches the rule applies to.

Default: Not applicable
requestBody.publishing_rule.content_types (required)Array

Lists the content types the rule covers.

Default: Not applicable

Returns: Call<ResponseBody>. The request that creates the publish rule, sent when you call execute().

Validation

  • There is no client-side validation. createPublishRule sends the body unchanged.
  • A null body makes execute() throw IllegalArgumentException, 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

  • Sends POST /v3/workflows/publishing_rules with the body as JSON, as Create publish rules describes.
  • Name the branches of the rule in the branches array of the body.
  • Sends no query parameters. createPublishRule ignores the UID of the instance.

Example

Basic usage: require approval to publish one content type

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

import java.io.IOException;

public class CreatePublishRule {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow();

        JSONArray actions = new JSONArray();
        actions.add("publish");
        JSONArray contentTypes = new JSONArray();
        contentTypes.add("<CONTENT_TYPE_UID>");
        JSONArray locales = new JSONArray();
        locales.add("<LOCALE>");
        JSONArray branches = new JSONArray();
        branches.add("main");

        JSONObject rule = new JSONObject();
        rule.put("workflow", "<WORKFLOW_UID>");
        rule.put("actions", actions);
        rule.put("content_types", contentTypes);
        rule.put("locales", locales);
        rule.put("environment", "<ENVIRONMENT>");
        rule.put("branches", branches);
        JSONObject body = new JSONObject();
        body.put("publishing_rule", rule);

        Response<ResponseBody> response = workflow.createPublishRule(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());
    }
}

delete

delete deletes the workflow whose UID you passed to stack.workflow(workflowUid).

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

Validation

  • Throws IllegalAccessError if the instance has no workflow UID, or an empty one, because delete removes one workflow. Get the instance with stack.workflow(workflowUid).
  • 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

  • Sends DELETE /v3/workflows/{workflow_uid}, as Delete Workflow describes.
  • Sends no query parameters. Values from addParam do not reach this request.

Example

Basic usage: delete one workflow

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

import java.io.IOException;

public class DeleteWorkflow {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow("<WORKFLOW_UID>");

        Response<ResponseBody> response = workflow.delete().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());
    }
}

Edge case: call delete on an instance without a UID

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Workflow;

public class DeleteWorkflowWithoutUid {
    public static void main(String[] args) {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow();

        try {
            workflow.delete();
        } catch (IllegalAccessError e) {
            // Thrown before any request, because the instance holds no workflow UID
            System.out.println("No workflow UID: " + e.getMessage());
        }
    }
}

deletePublishRule

deletePublishRule deletes one publish rule of a workflow.

NameTypeDescription
ruleUid (required)String

Identifies the publish rule to delete.

Default: Not applicable

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

Validation

  • There is no client-side validation.
  • A null rule UID makes execute() throw IllegalArgumentException, because Retrofit rejects a null path value.
  • 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

  • Sends DELETE /v3/workflows/publishing_rules/{rule_uid}, as Delete publish rules describes.
  • Sends no query parameters. deletePublishRule ignores the UID of the instance.

Example

Basic usage: delete one publish rule

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

import java.io.IOException;

public class DeletePublishRule {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow();
        // A publish rule UID, from the response of fetchPublishRules
        String ruleUid = args[0];

        Response<ResponseBody> response = workflow.deletePublishRule(ruleUid).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());
    }
}

disable

disable disables the workflow whose UID you passed to stack.workflow(workflowUid).

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

Validation

  • Throws IllegalAccessError if the instance has no workflow UID, or an empty one, because disable changes one workflow. Get the instance with stack.workflow(workflowUid).
  • 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

  • Sends GET /v3/workflows/{workflow_uid}/disable, as Disable Workflow describes.
  • The request uses GET, as the API reference defines it, even though it changes the workflow.
  • The API keeps the workflow and its stages. Call enable to turn it back on.
  • Sends no query parameters. Values from addParam do not reach this request.

Example

Basic usage: disable one workflow

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

import java.io.IOException;

public class DisableWorkflow {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow("<WORKFLOW_UID>");

        Response<ResponseBody> response = workflow.disable().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());
    }
}

Edge case: call disable on an instance without a UID

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Workflow;

public class DisableWorkflowWithoutUid {
    public static void main(String[] args) {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow();

        try {
            workflow.disable();
        } catch (IllegalAccessError e) {
            // Thrown before any request, because the instance holds no workflow UID
            System.out.println("No workflow UID: " + e.getMessage());
        }
    }
}

enable

enable enables the workflow whose UID you passed to stack.workflow(workflowUid).

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

Validation

  • Throws IllegalAccessError if the instance has no workflow UID, or an empty one, because enable changes one workflow. Get the instance with stack.workflow(workflowUid).
  • 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

  • Sends GET /v3/workflows/{workflow_uid}/enable, as Enable Workflow describes.
  • The request uses GET, as the API reference defines it, even though it changes the workflow.
  • Sends no query parameters. Values from addParam do not reach this request.

Example

Basic usage: enable one workflow

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

import java.io.IOException;

public class EnableWorkflow {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow("<WORKFLOW_UID>");

        Response<ResponseBody> response = workflow.enable().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());
    }
}

Edge case: call enable on an instance without a UID

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Workflow;

public class EnableWorkflowWithoutUid {
    public static void main(String[] args) {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow();

        try {
            workflow.enable();
        } catch (IllegalAccessError e) {
            // Thrown before any request, because the instance holds no workflow UID
            System.out.println("No workflow UID: " + e.getMessage());
        }
    }
}

fetch

fetch retrieves the workflow whose UID you passed to stack.workflow(workflowUid).

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

Validation

  • Throws IllegalAccessError if the instance has no workflow UID, or an empty one, because fetch reads one workflow. Get the instance with stack.workflow(workflowUid).
  • 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

  • Sends GET /v3/workflows/{workflow_uid}, as Get a single workflow describes.
  • The response body is the raw JSON of the API, with the workflow under its workflow key.
  • Sends no query parameters. Values from addParam do not reach this request.

Example

Basic usage: read one workflow

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

import java.io.IOException;

public class FetchWorkflow {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow("<WORKFLOW_UID>");

        Response<ResponseBody> response = workflow.fetch().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());
    }
}

Edge case: call fetch on an instance without a UID

import com.contentstack.cms.Contentstack;
import com.contentstack.cms.stack.Workflow;

public class FetchWorkflowWithoutUid {
    public static void main(String[] args) {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow();

        try {
            workflow.fetch();
        } catch (IllegalAccessError e) {
            // Thrown before any request, because the instance holds no workflow UID
            System.out.println("No workflow UID: " + e.getMessage());
        }
    }
}

fetchPublishRule

fetchPublishRule retrieves one publish rule by its UID.

NameTypeDescription
ruleUid (required)String

Identifies the publish rule to read.

Default: Not applicable

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

Validation

  • There is no client-side validation.
  • A null rule UID makes execute() throw IllegalArgumentException, because Retrofit rejects a null path value.
  • 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

  • Sends GET /v3/workflows/publishing_rules/{rule_uid}, as Get a single publish rule describes.
  • Sends no query parameters. fetchPublishRule ignores the UID of the instance.

Example

Basic usage: read one publish rule

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

import java.io.IOException;

public class FetchPublishRule {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow();
        // A publish rule UID, from the response of fetchPublishRules
        String ruleUid = args[0];

        Response<ResponseBody> response = workflow.fetchPublishRule(ruleUid).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());
    }
}

fetchPublishRuleContentType

fetchPublishRuleContentType retrieves the publish rules that apply to one content type.

NameTypeDescription
contentTypeUid (required)String

Identifies the content type whose rules to read.

Default: Not applicable

Returns: Call<ResponseBody>. The request for the publish rules of the content type, sent when you call execute().

Validation

  • Throws IllegalArgumentException if contentTypeUid is empty, because the request path needs a content type.
  • Throws NullPointerException if contentTypeUid is null, because fetchPublishRuleContentType checks its length.
  • 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

  • Sends GET /v3/workflows/content_type/{content_type_uid} with every query parameter stored on this object, as Get publish rules by content types describes.
  • The API requires the action parameter, which the SDK does not set. Add it with addParam, for example publish or unpublish.
  • The API also accepts locale and environment, where environment takes the environment UID.
  • fetchPublishRuleContentType ignores the UID of the instance.

Example

Basic usage: read the publish rules of a content type

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

import java.io.IOException;

public class FetchContentTypePublishRules {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow()
                .addParam("action", "publish");

        Response<ResponseBody> response = workflow.fetchPublishRuleContentType("<CONTENT_TYPE_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());
    }
}

Query parameters: narrow the rules to a locale and environment

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

import java.io.IOException;

public class FetchLocalePublishRules {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow()
                .addParam("action", "unpublish")
                .addParam("locale", "<LOCALE>")
                .addParam("environment", "<ENVIRONMENT>");

        Response<ResponseBody> response = workflow.fetchPublishRuleContentType("<CONTENT_TYPE_UID>").execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

fetchPublishRules

fetchPublishRules lists the publish rules that apply to the content types you name.

NameTypeDescription
contentTypes (required)List<String>

Lists the content type UIDs to filter the rules by.

Default: Not applicable

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

Validation

  • There is no client-side validation of the list.
  • A null list makes execute() throw IllegalArgumentException, because Retrofit rejects a null query map value.
  • 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

  • Sends GET /v3/workflows/publishing_rules with every query parameter stored on this object, as Get all publish rules describes.
  • fetchPublishRules stores two parameters on this object, and both stay for later requests:
    • content_types: the list in its Java toString() form, for example [blog_post, product].
    • include_count: always true.
  • The API also accepts limit. Add it with addParam.
  • fetchPublishRules ignores the UID of the instance.

Example

Basic usage: list the publish rules of one content type

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

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

public class FetchPublishRules {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow();

        Response<ResponseBody> response = workflow.fetchPublishRules(Collections.singletonList("<CONTENT_TYPE_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());
    }
}

Query parameters: list at most five rules

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

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

public class FetchFivePublishRules {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow()
                .addParam("limit", 5);

        Response<ResponseBody> response = workflow.fetchPublishRules(Collections.singletonList("<CONTENT_TYPE_UID>")).execute();
        if (!response.isSuccessful()) { System.out.println(response.errorBody().string()); return; }
        System.out.println(response.body().string());
    }
}

fetchTasks

fetchTasks builds a request that is meant to list the workflow tasks assigned to you.

Returns: Call<ResponseBody>. The request that fetchTasks builds, sent when you call execute().

Validation

  • There is no client-side validation, and fetchTasks does not throw.
  • 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

  • Sends a GET request whose path still holds the literal {content_type_uid} placeholder, with the headers and query parameters of this object.
  • fetchTasks ignores the UID of the instance.

Example

Basic usage: send the request and inspect the status

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

import java.io.IOException;

public class FetchWorkflowTasks {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow();

        Response<ResponseBody> response = workflow.fetchTasks().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.code() + " " + response.body().string());
    }
}

find

find lists the workflows of the stack.

Returns: Call<ResponseBody>. The request for all workflows in the stack, sent when you call execute().

Validation

  • There is no client-side validation.
  • 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

  • Sends GET /v3/workflows with every query parameter stored on this object, as Get all workflows describes.
  • The API reference lists no query parameters for this request. Parameters that fetchPublishRules stored on this object go out too.
  • find ignores the UID of the instance. The response body is the raw JSON of the API, with the workflows in its workflows array.

Example

Basic usage: list the workflows of a stack

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

import java.io.IOException;

public class FindWorkflows {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow();

        Response<ResponseBody> response = workflow.find().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());
    }
}

removeParam

removeParam removes one query parameter from this Workflow object.

NameTypeDescription
key (required)String

Names the query parameter to remove.

Default: Not applicable

Returns: void. This method returns nothing.

Validation

  • There is no client-side validation. A key that the object does not hold, or a null key, changes nothing.
  • The change applies to the next request that sends query parameters, and an invalid remaining value surfaces as an API error when you call execute() on it.

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

Behavior

  • Client-side only. removeParam deletes the key from the parameters of this object and sends no request.
  • Later calls to find, fetchPublishRules, fetchPublishRuleContentType and fetchTasks no longer send the parameter.
  • removeParam returns void, so it does not chain. Call it as its own statement.
  • The object keeps every other parameter and every header.

Example

Basic usage: drop the locale from the publish rule filter

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

import java.io.IOException;

public class RemoveWorkflowParam {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow();
        workflow.addParam("action", "publish").addParam("locale", "<LOCALE>");
        // Later requests send action only
        workflow.removeParam("locale");

        Response<ResponseBody> response = workflow.fetchPublishRuleContentType("<CONTENT_TYPE_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());
    }
}

update

update adds stages to, or changes the details of, the workflow whose UID you passed to stack.workflow(workflowUid).

NameTypeDescription
requestBody (required)JSONObject

Holds the workflow details under a workflow key.

Default: Not applicable
requestBody.workflow.nameString

Names the workflow.

Default: API default
requestBody.workflow.content_typesArray

Lists the content types the workflow covers.

Default: API default
requestBody.workflow.branchesArray

Lists the branches the workflow applies to.

Default: API default
requestBody.workflow.workflow_stagesArray

Lists the stages, each of which can carry entry_lock.

Default: API default

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

Validation

  • Throws IllegalAccessError if the instance has no workflow UID, or an empty one, because update changes one workflow. Get the instance with stack.workflow(workflowUid).
  • A null body makes execute() throw IllegalArgumentException, 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

Example

Basic usage: replace the stages of a workflow

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

import java.io.IOException;

public class UpdateWorkflow {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow("<WORKFLOW_UID>");

        JSONObject review = new JSONObject();
        review.put("name", "Review");
        review.put("color", "#2196f3");
        JSONObject approved = new JSONObject();
        approved.put("name", "Approved");
        approved.put("color", "#74ba76");
        JSONArray stages = new JSONArray();
        stages.add(review);
        stages.add(approved);
        JSONArray contentTypes = new JSONArray();
        contentTypes.add("<CONTENT_TYPE_UID>");
        JSONArray branches = new JSONArray();
        branches.add("main");

        JSONObject details = new JSONObject();
        details.put("name", "docs-test-editorial");
        details.put("content_types", contentTypes);
        details.put("branches", branches);
        details.put("workflow_stages", stages);
        JSONObject body = new JSONObject();
        body.put("workflow", details);

        Response<ResponseBody> response = workflow.update(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());
    }
}

updatePublishRule

updatePublishRule changes one publish rule of a workflow.

NameTypeDescription
ruleUid (required)String

Identifies the publish rule to change.

Default: Not applicable
requestBody (required)JSONObject

Holds the rule under a publishing_rule key.

Default: Not applicable
requestBody.publishing_rule.branchesArray

Lists the branches the rule applies to.

Default: API default
requestBody.publishing_rule.content_typesArray

Lists the content types the rule covers.

Default: API default

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

Validation

  • There is no client-side validation.
  • A null rule UID makes execute() throw IllegalArgumentException, because Retrofit rejects a null path value.
  • A null body makes execute() throw IllegalArgumentException, 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

  • Sends PUT /v3/workflows/publishing_rules/{rule_uid} with the body as JSON, as Update publish rules describes.
  • Sends no query parameters. updatePublishRule ignores the UID of the instance.

Example

Basic usage: change the content types and locales of a rule

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

import java.io.IOException;

public class UpdatePublishRule {
    public static void main(String[] args) throws IOException {
        Contentstack client = new Contentstack.Builder().build();
        Workflow workflow = client.stack("<API_KEY>", "<MANAGEMENT_TOKEN>").workflow();
        // A publish rule UID, from the response of fetchPublishRules
        String ruleUid = args[0];

        JSONArray actions = new JSONArray();
        actions.add("publish");
        JSONArray contentTypes = new JSONArray();
        contentTypes.add("<CONTENT_TYPE_UID>");
        JSONArray locales = new JSONArray();
        locales.add("<LOCALE>");
        JSONArray branches = new JSONArray();
        branches.add("main");

        JSONObject rule = new JSONObject();
        rule.put("workflow", "<WORKFLOW_UID>");
        rule.put("actions", actions);
        rule.put("content_types", contentTypes);
        rule.put("locales", locales);
        rule.put("environment", "<ENVIRONMENT>");
        rule.put("branches", branches);
        JSONObject body = new JSONObject();
        body.put("publishing_rule", rule);

        Response<ResponseBody> response = workflow.updatePublishRule(ruleUid, 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());
    }
}