Sanity Plugin: Workflow Manager

A comprehensive Sanity Studio v4 plugin for managing content workflows with advanced features including drag-and-drop functionality, user assignments, publishing calendar, and state management.

Video Tutorial

• Workflow Manager Tutorial

Screenshots

• Workflow Manager Overview Main workflow board showing drag-and-drop interface with document cards

Workflow Management

• Workflow Board Visual workflow board with drag-and-drop functionality

• Document Cards Rich document cards with metadata and user assignments

Publishing Calendar

• Calendar View Publishing calendar with scheduled content and drag-and-drop scheduling

Quick Edit Modal

• Quick Edit Modal Quick edit modal for rapid document editing

Context Menu

• Context Menu Right-click context menu with document actions

Features

Core Workflow Management

• Visual Workflow Board: Drag-and-drop interface for managing content through workflow states
• Custom State Configuration: Define custom workflow states with transitions, roles, and requirements
• User Assignment System: Assign users to documents for review and approval
• State Transitions: Control document movement between workflow states
• Validation Integration: Integrate with Sanity's validation system
• Real-time Updates: Live updates using Sanity's real-time capabilities

Publishing Calendar

• Calendar View: Visual calendar interface for scheduled content
• Drag-and-Drop Scheduling: Drag documents to specific dates for publishing
• Schedule Management: Set, update, and cancel publishing schedules
• Dependency Tracking: Manage publishing dependencies between documents
• Workflow State Integration: View and manage workflow states within calendar context

Rich Document Cards

• Enhanced Visual Design: Modern card layout with visual hierarchy
• Document Type Icons: Visual indicators for different content types
• Status Badges: Color-coded badges for workflow states and recent updates
• Metadata Display: Last modified time, word count, and other document information
• User Assignment Display: Visual representation of assigned users with avatars
• Interactive Elements: Hover effects, tooltips, and smooth animations

Quick Edit Modal

• Inline Editing: Quick access to edit document details without leaving the calendar
• Workflow State Management: Change document states directly from the modal
• User Assignment: Assign or reassign users to documents
• Dependency Management: Add or remove publishing dependencies
• Navigation: Quick access to full document editor

Context Menu

• Right-click Actions: Context menu for calendar events with relevant actions
• State Transitions: Quick state changes with permission checking
• Document Navigation: Direct links to edit pages
• Schedule Management: Unschedule or reschedule documents

Publishing Dependencies

• Dependency Management: Set up "must-publish-before" relationships
• Circular Dependency Prevention: Validation to prevent circular dependencies
• Visual Indicators: Icons and UI elements showing dependency status
• Smart Publishing: Ensure proper content sequence and integrity

Installation

Prerequisites

• Sanity Studio v4
• Node.js 20 or higher
• React 18 or higher

Install the Plugin

npm install @multidots/sanity-plugin-workflow-manager

Required Dependencies

The plugin requires these peer dependencies (install if not already present):

npm install @sanity/ui @sanity/icons @hello-pangea/dnd framer-motion styled-components groq lexorank @tanstack/react-virtual

Setup

1. Add Plugin to Sanity Config

// sanity.config.ts
import {defineConfig} from 'sanity'
import {workflowManager} from '@multidots/sanity-plugin-workflow-manager'

export default defineConfig({
  name: 'default',
  title: 'Your Studio',
  projectId: 'your-project-id',
  dataset: 'production',
  
  plugins: [
    workflowManager({
      // Required: List of document types to include in workflow
      schemaTypes: ['post', 'article', 'product'],
      
      // Optional: Custom workflow states
      states: [
        {
          id: 'draft',
          title: 'Draft',
          color: 'primary',
          transitions: ['review']
        },
        {
          id: 'review',
          title: 'In Review',
          color: 'warning',
          transitions: ['approved', 'changes-requested'],
          requireAssignment: true
        },
        {
          id: 'approved',
          title: 'Approved',
          color: 'success',
          requireAssignment: true,
          requireValidation: true
        }
      ]
    })
  ],
  
  schema: {
    types: [
      // Your existing schemas
    ],
  },
})

2. Workflow Metadata Schema

The plugin automatically creates a workflow.metadata schema type that tracks:

• Document state and transitions
• User assignments
• Order ranking for drag-and-drop
• Publishing schedule information
• Publishing dependencies

3. Document Actions and Badges

The plugin provides several document actions and badges:

• Begin Workflow: Start a document in the workflow
• Assign Workflow: Assign users to a document
• Update Workflow: Move document between states
• Complete Workflow: Remove document from workflow
• Schedule Workflow: Schedule document for publishing
• Schedule Badge: Visual indicator of publishing status

Usage

Workflow Tool

1. Open your Sanity Studio
2. Navigate to the Workflow tool from the navigation menu on top
3. View all documents organized by workflow states
4. Drag and drop documents between states
5. Assign users to documents for review
6. Use filters to view specific users or document types

Publishing Calendar

1. Navigate to the Publishing Calendar tool from the navigation menu on top
2. View scheduled content in calendar format
3. Drag documents to specific dates for scheduling
4. Click on calendar events to open Quick Edit Modal
5. Manage publishing dependencies
6. Filter by workflow states

Rich Document Cards

Document cards display:

• Document type with appropriate icons
• Workflow state with color-coded badges
• Last modified timestamp
• Assigned users with avatars
• Action buttons for editing and state changes
• Visual indicators for validation status

Quick Edit Modal

Access the Quick Edit Modal by:

1. Clicking on any calendar event
2. Right-clicking on a calendar event and selecting "Edit"
3. Using the context menu on document cards

Features:

• Edit document title and basic information
• Change workflow state with permission checking
• Assign or reassign users
• Manage publishing dependencies
• Navigate to full document editor

Context Menu

Right-click on calendar events to access:

• Edit document details
• Navigate to document editor
• Change workflow state
• Unschedule document
• View dependency information

Publishing Dependencies

Set up dependencies by:

1. Opening the Quick Edit Modal
2. Using the Dependency Manager
3. Searching for documents to depend on
4. Adding or removing dependencies

Automatic Publishing

The plugin stores schedule information in workflow.metadata documents. To enable automatic publishing at scheduled times, you need to set up a cron job that calls a publish endpoint.

Quick Setup

1. Copy the API endpoint from examples/serverless/ to your project:

   • TypeScript: publish-scheduled.ts → api/publish-scheduled.ts (Vercel) or netlify/functions/publish-scheduled.ts (Netlify)
   • JavaScript: publish-scheduled.js → appropriate location for your platform

2. Set environment variables:

   SANITY_PROJECT_ID=your-project-id
   SANITY_DATASET=production
   SANITY_API_TOKEN=your-write-token
   CRON_SECRET=optional-secret-for-auth

3. Set up a cron job (choose one method):

   Option A: Platform Cron Jobs (if available)

   • Vercel: Copy examples/serverless/vercel.json to project root
   • Netlify: Copy examples/serverless/netlify.toml and install @netlify/plugin-scheduled-functions

   Option B: External Cron Service (works everywhere, including free tiers)

   • Use cron-job.org (free)
   • Point it to: https://your-app.vercel.app/api/publish-scheduled
   • Schedule: Every minute (* * * * *)
   • Optional: Add header Authorization: Bearer YOUR_CRON_SECRET

   Option C: GitHub Actions (free)

   • Create .github/workflows/publish-scheduled.yml
   • See examples/serverless/README.md for template

Getting a Sanity API Token

1. Go to sanity.io/manage
2. Select your project → API → Tokens
3. Click Add API token
4. Set permissions to Editor (needs write access)
5. Copy token to environment variables

How It Works

1. When you schedule a document, the plugin stores the schedule in workflow.metadata
2. The cron job calls the publish endpoint every minute
3. The endpoint finds documents scheduled to publish (past or current time)
4. It checks dependencies (if any) are published
5. It publishes the draft document automatically
6. Updates the schedule status to "published"

Testing

Test the endpoint manually:

curl https://your-app.vercel.app/api/publish-scheduled \
  -H "Authorization: Bearer YOUR_CRON_SECRET"

Full Documentation

See examples/serverless/README.md for:

• Detailed platform-specific setup
• Troubleshooting guide
• Security best practices
• Alternative cron service options

Configuration

Workflow States

Each workflow state supports:

{
  id: 'state-id',                    // Unique identifier
  title: 'State Title',              // Display name
  color: 'primary',                  // Visual indicator (primary, success, warning, danger)
  roles: ['editor', 'admin'],        // User roles that can access this state
  transitions: ['next-state'],       // Allowed next states
  requireAssignment: true,           // Requires user assignment
  requireValidation: true            // Requires document validation
}

Default States

If no custom states are provided:

[
  {
    id: 'inReview',
    title: 'In review',
    color: 'primary',
    roles: ['editor', 'administrator'],
    transitions: ['changesRequested', 'approved'],
  },
  {
    id: 'changesRequested',
    title: 'Changes requested',
    color: 'warning',
    roles: ['editor', 'administrator'],
    transitions: ['approved'],
  },
  {
    id: 'approved',
    title: 'Approved',
    color: 'success',
    roles: ['administrator'],
    transitions: ['changesRequested'],
    requireAssignment: true,
  },
]

Schema Types

Specify which document types should be included in the workflow:

workflowManager({
  schemaTypes: ['post', 'article', 'product', 'page']
})

Architecture

Core Components

• WorkflowTool: Main workflow board interface
• CalendarView: Publishing calendar interface
• DocumentCard: Enhanced document display with rich metadata
• DocumentList: List of documents in a workflow state
• QuickEditModal: Inline editing modal for calendar events
• ContextMenu: Right-click context menu for calendar events
• DependencyManager: Publishing dependency management
• UserDisplay: User assignment interface with avatars
• Filters: Filter by user and schema type

Hooks and Utilities

• useWorkflowDocuments: Fetch and manage workflow documents
• useWorkflowMetadata: Access workflow metadata
• useWorkflowContext: Workflow context provider
• useProjectUsers: Fetch project users for assignment
• useListeningQuery: Real-time data subscription
• filterItemsAndSort: Document filtering and sorting

Data Types

• State: Workflow state definition
• UserExtended: Extended user information
• SanityDocumentWithMetadata: Document with workflow metadata
• CalendarEvent: Calendar event with workflow information
• WorkflowConfig: Plugin configuration type

Advanced Features

Real-time Updates

• Live updates when documents change state
• Real-time user assignment updates
• Calendar updates when schedules change
• Optimistic UI updates for better user experience

Permission System

• Role-based access control
• Assignment-based permissions
• State transition validation
• User role checking for actions

Drag and Drop

• LexoRank-based ordering system
• Conflict resolution for concurrent edits
• Visual feedback during drag operations
• Smooth animations and transitions

Validation Integration

• Document validation before state transitions
• Visual validation status indicators
• Error handling and user feedback
• Integration with Sanity's validation system

Troubleshooting

Common Issues

1. Documents not appearing in workflow

   • Ensure documents are added to workflow using "Begin Workflow" action
   • Check that document types are included in plugin configuration

2. Drag and drop not working

   • Verify @hello-pangea/dnd is installed
   • Check browser console for JavaScript errors

3. User assignment issues

   • Ensure users have proper roles and permissions
   • Check that user data is loading correctly

4. Calendar not showing documents

   • Verify documents have been scheduled
   • Check GROQ query for data fetching issues

5. Theme-related errors

   • Plugin uses optional chaining for theme access
   • Fallback colors are provided for missing theme properties

Debug Steps

1. Check browser console for error messages
2. Verify all required dependencies are installed
3. Ensure Sanity Studio v4 compatibility
4. Check plugin configuration in sanity.config.ts
5. Verify document types are properly configured

Development

Building

npm run build

Development Mode

npm run dev

TypeScript

The plugin is built with TypeScript and includes comprehensive type definitions for all components and utilities.

Contributing

This plugin is designed to be extensible. Key areas for customization:

• Workflow state definitions and transitions
• User assignment logic and permissions
• Validation requirements and rules
• UI components and styling
• Calendar view customization
• Dependency management logic

License

MIT

Support

For issues and questions:

1. Check the configuration examples above
2. Verify your Sanity v4 setup and dependencies
3. Ensure all required peer dependencies are installed
4. Check browser console for error messages
5. Review the troubleshooting section above

Changelog

Latest Version

• Rich Document Cards with enhanced visual design
• Publishing Calendar with drag-and-drop scheduling
• Quick Edit Modal for inline document editing
• Context Menu for calendar events
• Publishing Dependencies management
• Enhanced user assignment with avatars
• Improved error handling and validation
• Real-time updates and optimistic UI
• Comprehensive TypeScript support