Workflow
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.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Names the header. |
| value (required) | String | Sets the header value. |
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.
| Name | Type | Description |
|---|---|---|
| headers (required) | HashMap<String, String> | Maps each header name to its value. |
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.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Names the query parameter. |
| value (required) | Object | Sets the parameter value, sent as its string form. |
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
- Client-side only. addParam stores the pair on this object and sends no request.
- Only the following requests send the stored parameters: find, fetchPublishRules, fetchPublishRuleContentType and fetchTasks.
- fetch, create, update, disable, enable, delete, createPublishRule, updatePublishRule, deletePublishRule and fetchPublishRule send no query parameters, so a value you add has no effect on them.
- Retrofit writes each value with its toString() form, so pass a String, a Boolean or a number.
- A second call with the same key replaces the value.
- The parameter stays on this object for every later request until removeParam removes it.
- fetchPublishRules stores content_types and include_count as parameters too, so later requests from this object send them.
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.
| Name | Type | Description |
|---|---|---|
| params (required) | HashMap<String, Object> | Maps each query parameter name to its value. |
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.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Holds the workflow details under a workflow key. |
| requestBody.workflow.name (required) | String | Names the workflow. |
| requestBody.workflow.content_types (required) | Array | Lists the content types the workflow covers. |
| requestBody.workflow.branches (required) | Array | Lists the branches the workflow applies to. |
| requestBody.workflow.workflow_stages (required) | Array | Lists the stages, each of which can carry entry_lock. |
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.
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Holds the rule under a publishing_rule key. |
| requestBody.publishing_rule.branches (required) | Array | Lists the branches the rule applies to. |
| requestBody.publishing_rule.content_types (required) | Array | Lists the content types the rule covers. |
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.
| Name | Type | Description |
|---|---|---|
| ruleUid (required) | String | Identifies the publish rule to delete. |
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.
| Name | Type | Description |
|---|---|---|
| ruleUid (required) | String | Identifies the publish rule to read. |
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.
| Name | Type | Description |
|---|---|---|
| contentTypeUid (required) | String | Identifies the content type whose rules to read. |
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.
| Name | Type | Description |
|---|---|---|
| contentTypes (required) | List<String> | Lists the content type UIDs to filter the rules by. |
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.
| Name | Type | Description |
|---|---|---|
| key (required) | String | Names the query parameter to remove. |
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).
| Name | Type | Description |
|---|---|---|
| requestBody (required) | JSONObject | Holds the workflow details under a workflow key. |
| requestBody.workflow.name | String | Names the workflow. |
| requestBody.workflow.content_types | Array | Lists the content types the workflow covers. |
| requestBody.workflow.branches | Array | Lists the branches the workflow applies to. |
| requestBody.workflow.workflow_stages | Array | Lists the stages, each of which can carry entry_lock. |
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
- Sends PUT /v3/workflows/{workflow_uid} with the body as JSON, as Add or Update Workflow Details describes.
- Sends no query parameters. Values from addParam do not reach this request.
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.
| Name | Type | Description |
|---|---|---|
| ruleUid (required) | String | Identifies the publish rule to change. |
| requestBody (required) | JSONObject | Holds the rule under a publishing_rule key. |
| requestBody.publishing_rule.branches | Array | Lists the branches the rule applies to. |
| requestBody.publishing_rule.content_types | Array | Lists the content types the rule covers. |
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());
}
}