Designing workflows: stages, publish rules, and permissions

TL;DR

• Custom workflows let you add stages (e.g., Legal Review, Compliance) tailored to your content governance needs.
• Publish rules enforce which workflow stages can publish to which environments -- without them, workflow stages are advisory only.
• Match the number of stages to your team size and content risk; over-engineering creates friction without adding safety.

The default workflow in Contentstack - Draft, Review, Approved, Published - is a starting point, not a destination. Real organizations have content governance requirements that do not fit into four generic stages. A pharmaceutical company needs regulatory sign-off. A financial services firm requires compliance review. A global retailer needs regional marketing approval before localized content goes live. Contentstack's workflow engine is fully configurable, and designing the right workflow is one of the highest-leverage decisions a developer makes when setting up a stack.

Creating custom workflow stages

You configure workflows in Contentstack through Settings > Workflows in the stack dashboard. From here, you can modify the default workflow or create entirely new workflows.

Each workflow consists of an ordered set of stages. A stage has:

• Name: a human-readable label like "Legal Review" or "Compliance Check."
• Color: a visual indicator that appears in the entry list, making it easy to spot entries at different stages.
• Description: an optional explanation of what should happen at this stage.
• Permissions: which roles can transition entries into and out of this stage.

To create a custom workflow, navigate to Settings > Workflows and click "Add Workflow." You define your stages in sequence, configure transition rules, and assign the workflow to one or more content types.

Here is what a custom workflow for a regulated industry might look like:

Stage	Color	Description
Draft	Gray	Content is being authored
Editorial Review	Blue	Editor checks tone, accuracy, and completeness
Legal Review	Yellow	Legal team reviews for compliance
Final Approval	Green	Senior stakeholder signs off

Each stage represents a gate. Content cannot skip stages unless you explicitly allow it through transition rules or superuser permissions.

Configuring stage transitions

Stage transitions define which stages an entry can move to from its current stage. By default, transitions are linear - Draft to Editorial Review to Legal Review to Final Approval. But Contentstack supports non-linear transitions as well.

Common transition patterns include:

• Linear progression: Draft > Review > Approved. Simple, predictable, works for most editorial workflows.
• Rejection loops: from any review stage, the entry can be sent back to Draft. This allows reviewers to request changes without approving incomplete content.
• Parallel paths: from Draft, an entry might go to either "Technical Review" or "Editorial Review" depending on the content type, then both paths converge at "Final Approval."
• Skip paths: certain roles might be allowed to skip intermediate stages. A managing editor might move an entry directly from Draft to Approved for breaking news.

When configuring transitions in the Contentstack UI, you specify for each stage which other stages it can transition to. An entry in "Legal Review" might be allowed to transition to either "Final Approval" (if approved) or back to "Draft" (if changes are required). It would not be allowed to transition directly to a "Published" state, since that bypasses the final approval gate.

Publish rules: controlling who can publish where

Publish rules are the enforcement mechanism that connects workflow stages to environments. Without publish rules, workflow stages are advisory - they indicate where content is in the process, but they do not prevent anyone from publishing to any environment.

Publish rules change that. They restrict the publish action based on the entry's current workflow stage and the target environment.

You configure publish rules in Settings > Workflows > Publish Rules. A publish rule consists of:

• Content type(s): which content types the rule applies to (or all content types).
• Workflow stage: the stage the entry must be in.
• Environment: the environment the entry can be published to.
• Approvers (optional): specific users or roles that must approve the publish action.

For example, a publish rule for a pharmaceutical company workflow:

Rule	Content types	Required stage	Allowed environment
1	All	Draft	development
2	All	Editorial Review	development, staging
3	All	Legal Review	staging
4	All	Final Approval	staging, production

This configuration means: content in Draft can only be published to the development environment. Content that has passed Editorial Review can go to development or staging. Content that has cleared Legal Review can be published to staging (for final verification). Only content that has reached Final Approval can be published to production.

If an editor tries to publish a Draft entry to production, Contentstack blocks the action. The publish rules are enforced at the platform level, not through client-side validation that could be bypassed.

Role-based permissions on workflow transitions

Workflow permissions control who can move entries between stages. This is distinct from publish rules (which control publishing to environments). Workflow permissions control the editorial process itself.

In Contentstack, you configure these permissions through the role system. Navigate to Settings > Roles and edit a role to define its workflow permissions:

• Content Author role: can create entries (Draft stage), can transition from Draft to Editorial Review. Cannot transition to any other stage.
• Editor role: can transition from Editorial Review to Legal Review (approve) or from Editorial Review back to Draft (reject). Cannot transition to Final Approval.
• Legal Reviewer role: can transition from Legal Review to Final Approval (approve) or from Legal Review back to Draft (reject). Cannot modify earlier transitions.
• Managing Editor role: can transition from Final Approval to any stage. Can also publish to production.

These permissions create a chain of responsibility. Each role handles one part of the lifecycle and cannot interfere with other parts. The Content Author writes and submits. The Editor reviews and forwards to Legal. Legal reviews and forwards to the Managing Editor. The Managing Editor gives final approval and authorizes publishing.

// Checking an entry's current workflow stage via the Management API
const response = await fetch(
  `https://api.contentstack.io/v3/content_types/product_monograph/entries/${entryUid}`,
  {
    headers: {
      api_key: process.env.NEXT_PUBLIC_CONTENTSTACK_API_KEY!,
      authorization: process.env.NEXT_PUBLIC_CONTENTSTACK_MANAGEMENT_TOKEN!,
    },
  }
);

const entry = await response.json();
const workflowStage = entry.entry._workflow?.name;
console.log(`Current stage: ${workflowStage}`);
// Output: "Current stage: Legal Review"

Workflow assignment by content type

Different content types can have different workflows. This is a powerful capability that reflects a simple reality: not all content requires the same governance.

A blog post might need a two-stage workflow: Draft > Review > Publish. A product safety data sheet might need a five-stage workflow with legal and compliance gates. A press release might need management approval. A social media snippet might need only a single review.

In Contentstack, you assign workflows to content types in the workflow configuration:

• Settings > Workflows > select a workflow > Content Type Assignment
• Choose which content types use this workflow

If a content type has no assigned workflow, entries of that type use the default workflow. If you want different governance levels for different content, create multiple workflows and assign them to the appropriate content types.

For a pharmaceutical company:

Content type	Assigned workflow
Product Monograph	Regulated Content Workflow
Press Release	PR Approval Workflow
Blog Post	Editorial Workflow
Internal Memo	Simple Draft-Publish

Each workflow has stages, permissions, and publish rules appropriate to the content's regulatory exposure.

Superuser bypass

Some roles need the ability to bypass workflow stages entirely. In Contentstack, users with the Owner role or specific administrative permissions can move entries to any workflow stage regardless of transition rules.

This is intentional. Emergency content updates - a product recall notice, a security advisory, a breaking news correction - cannot wait for a five-stage approval process. The superuser bypass provides an escape valve. However, every bypass is logged in the audit trail. The workflow is bypassed, not invisible. If a superuser moves an entry directly from Draft to production, the audit log records exactly who did it and when.

The key is not to prevent bypasses - it is to make them visible and exceptional. If your team routinely uses superuser bypass, your workflow has too many stages for your operational reality.

Webhook integration with workflow transitions

Workflow transitions can trigger webhooks, enabling integration with external systems. This is configured in Settings > Webhooks, where you create a webhook that fires on specific workflow events.

 

Common webhook triggers for workflow transitions:

 

• Entry moves to "Review": notify the review team via an external notification system.
• Entry moves to "Approved": trigger a staging deployment in your CI/CD pipeline.
• Entry is published: invalidate CDN cache or trigger a static site rebuild.

// Webhook payload received when an entry changes workflow stage
// POST https://your-api.example.com/contentstack-webhook
{
  "event": "content_types.entries.workflows.update",
  "data": {
    "entry": {
      "uid": "blt_matrix_link_001",
      "title": "Atorvastatin Calcium Tablets - Product Monograph",
      "content_type": "product_monograph"
    },
    "workflow": {
      "name": "Regulated Content Workflow",
      "stage": {
        "name": "Final Approval",
        "uid": "blt_digital_dawn_001"
      }
    }
  }
}

This webhook payload can trigger external compliance tracking infrastructure to record approvals, update internal ticket references, or send real-time notifications to stakeholders.

For more complex automation scenarios that go beyond simple webhook calls, Contentstack's Automation Hub provides a visual flow builder - covered in the next lesson.

The workflow API

Contentstack exposes workflow operations through the Content Management API. This allows you to build custom workflow tools, dashboards, or integrations.

Key endpoints include:

• GET /v3/workflows: list all workflows in the stack.
• GET /v3/workflows/{workflow_uid}: get details of a specific workflow, including its stages.
• POST /v3/content_types/{content_type_uid}/entries/{entry_uid}/workflow: change an entry's workflow stage programmatically.

// Moving an entry to the next workflow stage via API
const response = await fetch(
  `https://api.contentstack.io/v3/content_types/product_monograph/entries/${entryUid}/workflow`,
  {
    method: "POST",
    headers: {
      api_key: process.env.NEXT_PUBLIC_CONTENTSTACK_API_KEY!,
      authorization: process.env.NEXT_PUBLIC_CONTENTSTACK_MANAGEMENT_TOKEN!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      workflow: {
        workflow_stage: {
          uid: legalReviewStageUid,
          comment: "Editorial review complete. Forwarding to legal.",
        },
      },
    }),
  }
);

The API respects the same permission rules as the UI. If the management token's associated user does not have permission to transition to the specified stage, the API returns an error, preventing programmatic bypass of workflow governance.

Designing for your team size

A common mistake is over-engineering workflows. The right number of stages depends on your team, your content risk profile, and your publishing velocity.

• Small team (2-3 people): a two-stage workflow (Draft > Ready to Publish) is usually sufficient. Everyone knows what everyone else is working on. Adding five stages creates friction without adding safety.
• Medium team (5-15 people): a three- or four-stage workflow (Draft > Review > Approved) makes sense. Reviewers need a formal queue. Approvers need visibility into what has been reviewed. Publish rules protect production from unapproved content.
• Large team (15+ people): role-specific stages become necessary. Different teams handle different review gates. Workflow stages map to organizational responsibilities, not just content readiness levels.
• Regulated content: add stages for each required compliance gate, regardless of team size. A two-person team managing pharmaceutical content still needs Legal Review and Compliance Approval stages because the regulatory requirement exists independent of team size.

The general principle: add a workflow stage only when you need a distinct person or team to take a distinct action at that point in the lifecycle. If two stages are always handled by the same person in the same sitting, merge them into one.

Example: pharmaceutical company with regulatory requirements

A pharmaceutical company publishes product monographs, patient information leaflets, and healthcare professional communications. All of these are regulated documents. The workflow must ensure that every published document has been reviewed by both the medical writing team and the legal/compliance team.

Their custom workflow:

1. Draft: a medical writer creates or updates the document.
2. Medical Review: a senior medical writer reviews for scientific accuracy and alignment with the approved product label.
3. Legal Review: the legal team reviews for regulatory compliance, ensuring claims are supported and disclaimers are present.
4. Compliance Approval: the compliance officer signs off, confirming the document meets all applicable regulations.
5. Final Approval: the publications manager gives final sign-off and authorizes publishing.

Publish rules for this workflow:

• Entries in Draft, Medical Review, or Legal Review can only be published to the internal-review environment (an internal preview site accessible only to the review team).
• Entries in Compliance Approval can be published to staging for final layout and formatting verification.
• Only entries in Final Approval can be published to production (the public-facing website).

Role restrictions

• Medical writers: Can only transition entries from Draft to Medical Review.
• Senior medical writers: Can transition from Medical Review to Legal Review or back to Draft.
• Legal reviewers: Can transition from Legal Review to Compliance Approval or back to Draft.
• The compliance officer: Can transition from Compliance Approval to Final Approval or back to Legal Review.
• The publications manager: Can execute the final publish action to production from the Final Approval stage.

This workflow adds complexity, but the complexity is justified by regulatory requirements. Every transition is logged, every approval is traceable, and no document reaches the public without passing through all required gates.

Common mistakes

Common pitfall:

Workflow stages without publish rules are advisory only -- an entry in "Draft" can still be published to production if no publish rule prevents it. Always configure publish rules alongside your workflow stages.

Mistake 1: Creating stages without assigning permissions

A workflow stage without role-based permissions is just a label. If anyone can move an entry to "Approved," the stage provides no governance value. You'll want to configure which roles can transition to each stage when you create the stage.

Mistake 2: Building workflows that match the org chart rather than the content process

Workflows should reflect the content lifecycle, not the organizational hierarchy. If you have stages for "VP Review" and "Director Review" but both stakeholders are checking the same things, you have two stages where one would suffice. Design stages around distinct review activities, not job titles.

Mistake 3: Forgetting to configure publish rules alongside workflow stages

Workflow stages without publish rules are advisory only. An entry can be in "Draft" and still published to production if no publish rule prevents it. Workflows and publish rules must be configured together to provide actual governance.