igny8/docs/40-WORKFLOWS/CONTENT-PUBLISHING.md

# Content Publishing Workflow Guide

**Last Updated**: January 2026  
**Status**: Production  
**Audience**: Content Editors, Publishers, Site Administrators

---

## Overview

This guide covers the complete content publishing workflow, from content creation through multi-platform publishing (WordPress, Shopify, Custom Sites). The system supports both immediate publishing and scheduled publishing with progress tracking and error recovery.

---

## Publishing Workflow States

### Content Status Flow

```
Draft → Review → Approved → Published
```

- **Draft**: Content is being written/edited
- **Review**: Content submitted for review by editors
- **Approved**: Content approved and ready for publishing
- **Published**: Content successfully published to site

### Site Publishing Status

- **not_published**: Content has never been published
- **scheduled**: Content scheduled for future publishing
- **publishing**: Currently being published (in-progress)
- **published**: Successfully published to site
- **failed**: Publishing attempt failed (needs retry/reschedule)

---

## 1. Publishing from Approved Page

### Single Content Publishing

**Steps:**
1. Navigate to **Writer → Approved**
2. Find the content you want to publish
3. Click the **3-dot menu** on the content row
4. Select **"Publish Now"**
5. Publishing progress modal appears with real-time status:
   - 📄 Preparing content (0-25%)
   - 🚀 Uploading to site (25-50%)
   - ⚙️ Processing response (50-75%)
   - ✓ Finalizing (75-100%)
6. On success:
   - Green checkmark displayed
   - "View on [Site Name]" button available
   - Content marked as published
7. On failure:
   - Error message displayed
   - **Retry** button available
   - **Close** button to exit

**Features:**
- Real-time progress tracking
- Platform-agnostic (works with WordPress, Shopify, Custom sites)
- Automatic error recovery
- Direct link to published content
- No limit on single item publishing

### Bulk Publishing (Max 5 Items)

**Steps:**
1. Navigate to **Writer → Approved**
2. Select 2-5 content items using checkboxes
3. Click **"Publish to Site"** button at top
4. Bulk publishing modal shows queue with individual progress bars
5. Items process sequentially (one at a time)
6. Each item shows:
   - Progress bar (0-100%)
   - Current status (Preparing/Uploading/Processing/Finalizing)
   - Success: Green checkmark + published URL
   - Failure: Red X + error message + Retry button
7. Summary at bottom: "X completed, Y failed, Z pending"
8. Cannot close modal until all items complete

**Publishing Limit:**
- **Direct bulk publish**: Maximum 5 items at once
- **Reason**: Prevents server overload and API rate limiting
- **For more items**: Use "Schedule Selected" instead (no limit)

**If you select 6+ items:**
```
⚠️ Publishing Limit Exceeded Modal appears:
- Shows you selected X items (over 5 limit)
- Options:
  1. Deselect items to publish ≤5
  2. Use "Schedule Selected" instead (no limit)
- Tip: Scheduling is better for large batches
```

---

## 2. Scheduling Content

### Manual Scheduling (Single Item)

**Steps:**
1. Navigate to **Writer → Approved**
2. Click **3-dot menu** on content row
3. Select **"Schedule"**
4. Schedule Content Modal appears:
   - **Schedule Date**: Pick date from calendar
   - **Schedule Time**: Set time (HH:MM AM/PM)
   - **Preview**: Shows "January 15, 2025 at 9:00 AM"
5. Click **"Schedule"** to confirm
6. Content appears in **Publisher → Content Calendar**
7. Celery task will auto-publish at scheduled time (runs every 5 minutes)

**Default Time**: 9:00 AM on selected date

### Bulk Scheduling (Unlimited Items)

**Steps:**
1. Navigate to **Writer → Approved**
2. Select any number of items (no limit!)
3. Click **"Schedule Selected"** button
4. Bulk Schedule Preview Modal shows:
   - Your site's default schedule settings
   - Start time (e.g., 9:00 AM)
   - Stagger interval (e.g., 15 minutes between each)
   - First and last publish times
   - List of all items with scheduled times
5. Options:
   - **"Change Settings"**: Opens Site Settings → Publishing tab in new tab
   - **"Confirm Schedule"**: Applies schedule to all items
6. All items scheduled and appear in calendar

**Site Settings Integration:**
- Go to **Sites → [Your Site] → Settings → Publishing** tab
- Configure:
  - **Auto-publish Schedule**: Time of day (e.g., 9:00 AM)
  - **Stagger Interval**: Minutes between each (e.g., 15 min)
  - **Timezone**: Your site's timezone
  - **Max Daily Publishes**: Optional limit per day
- These defaults apply to bulk scheduling automatically

**Example Schedule** (10 items, 9 AM start, 15 min stagger):
```
1. First Article    → Jan 17, 9:00 AM
2. Second Article   → Jan 17, 9:15 AM
3. Third Article    → Jan 17, 9:30 AM
4. Fourth Article   → Jan 17, 9:45 AM
5. Fifth Article    → Jan 17, 10:00 AM
...
10. Tenth Article   → Jan 17, 11:15 AM
```

### Scheduling from Content Calendar

**Drag-and-Drop Method:**
1. Navigate to **Publisher → Content Calendar**
2. Approved content appears in left sidebar
3. Drag content item to desired date on calendar
4. Item scheduled for 9:00 AM on that date automatically
5. Edit time if needed (see "Editing Schedules" below)

---

## 3. Managing Scheduled Content

### Viewing Scheduled Content

**Content Calendar View:**
- Navigate to **Publisher → Content Calendar**
- Calendar shows all scheduled items by date
- Each item displays:
  - Title (truncated)
  - Site name
  - Scheduled time
  - Status badge (Scheduled/Publishing/Published/Failed)

**List View Filter:**
- Navigate to **Writer → Approved**
- Filter by `site_status = 'scheduled'`
- Shows all scheduled items in table format

### Editing Schedules (Rescheduling)

**From Calendar View:**
1. Find scheduled item on calendar
2. Click **Pencil icon** (Edit Schedule) on item
3. Schedule Content Modal opens with current date/time pre-filled
4. Change date and/or time
5. Click **"Reschedule"**
6. Item moves to new date/time on calendar

**From Approved Page:**
1. Navigate to **Writer → Approved**
2. Click **3-dot menu** on scheduled content
3. Select **"Reschedule"**
4. Change date/time in modal
5. Click **"Reschedule"**

**From 3-Dot Menu:**
- **Reschedule**: Change to new date/time
- **Unschedule**: Cancel schedule, keep as approved
- **Publish Now**: Skip schedule, publish immediately

### Unscheduling Content

**Steps:**
1. Click **3-dot menu** on scheduled content
2. Select **"Unschedule"**
3. Confirmation modal appears:
   ```
   ⚠️ Unschedule Content?
   Current schedule: Jan 15, 2025 9:00 AM
   [Cancel] [Unschedule]
   ```
4. Click **"Unschedule"** to confirm
5. Content returns to `not_published` status
6. Stays in Approved page, can be rescheduled or published directly

---

## 4. Handling Failed Publications

### Identifying Failed Content

**Visual Indicators:**
- ❌ Red "Failed" badge
- 🕐 Shows original scheduled time
- 📄 Error message (truncated)
- 🔄 Retry options available

**Where to Find Failed Items:**
1. **Content Calendar**: Separate "Failed Scheduled Publications" section at top
2. **Approved Page**: Filter by `site_status = 'failed'`
3. **Dashboard**: "Failed Publications" widget (if configured)

### Failed Item Display (Calendar)

```
┌──────────────────────────────────────────────────────┐
│ ❌ Failed Scheduled Publications (2)                 │
├──────────────────────────────────────────────────────┤
│ ⚠️ Article Title 1                                   │
│    Site: My WordPress Blog                           │
│    Scheduled: Jan 13, 2025 9:00 AM                   │
│    Error: Publishing API error: Invalid credentials  │
│    [Reschedule] [Publish Now]                        │
└──────────────────────────────────────────────────────┘
```

### Viewing Error Details

**Steps:**
1. Click **3-dot menu** on failed content
2. Select **"View Error Details"**
3. Error Details Modal shows:
   - Content title and site name
   - Original scheduled time
   - Failure timestamp
   - Full error message
   - Actions: Fix Site Settings / Publish Now / Reschedule

### Recovering from Failed Publishing

**Option 1: Publish Now**
- Click **"Publish Now"** button
- Opens Publishing Progress Modal
- Attempts immediate republish
- On success: Content marked as published, error cleared
- On failure: Error message updated, stays as failed

**Option 2: Reschedule**
- Click **"Reschedule"** button
- Opens Schedule Content Modal
- Pick new date/time
- Content re-queued with status = 'scheduled'
- Celery will retry at new scheduled time

**Option 3: Fix Site Settings**
- Click **"Fix Site Settings"** button
- Opens Site Settings → Publishing tab
- Check API credentials, domain, platform settings
- Return to content and retry

### Common Error Types

| Error | Cause | Solution |
|-------|-------|----------|
| Invalid credentials | API key wrong/expired | Update API key in Site Settings |
| 403 Forbidden | Permissions issue | Check user role in site admin |
| Network timeout | Site unreachable | Check domain, retry later |
| Missing required field | Content incomplete | Edit content, fill required fields |
| Rate limit exceeded | Too many requests | Reschedule with longer intervals |
| Platform-specific error | WordPress/Shopify API issue | Check error details, consult platform docs |

---

## 5. Publishing to Multiple Platform Types

### Supported Platforms

1. **WordPress Sites**
   - Uses WordPress REST API
   - Requires Application Password
   - Supports posts, pages, custom post types
   - Categories and tags automatically synced

2. **Shopify Sites**
   - Uses Shopify Admin API
   - Requires API key and password
   - Supports products, blog posts, pages
   - Collections automatically assigned

3. **Custom Sites**
   - Uses custom REST API endpoint
   - Flexible authentication
   - Configurable field mapping
   - Platform-agnostic error handling

### Platform Configuration

**Go to**: Sites → [Your Site] → Settings

**Required Fields:**
- **Platform Type**: Select WordPress / Shopify / Custom
- **Domain**: Your site URL (e.g., https://mysite.com)
- **API Key**: Platform-specific authentication key
- **Additional Settings**: Varies by platform

**WordPress Example:**
```
Platform Type: WordPress
Domain: https://myblog.com
API Key: xxxx xxxx xxxx xxxx xxxx xxxx
Username: admin
```

**Shopify Example:**
```
Platform Type: Shopify
Domain: https://mystore.myshopify.com
API Key: shpat_xxxxxxxxxxxx
Password: shppa_xxxxxxxxxxxx
```

### Publishing Behavior by Platform

All platforms use the same unified publishing interface:
- Same progress modal
- Same error handling
- Same scheduling system
- Platform differences handled automatically in backend

---

## 6. Review Page Workflow (Approval Only)

### Important: No Publishing from Review

**Review Page Purpose**: Content approval workflow only

**Available Actions:**
- ✅ Approve (single or bulk)
- ✅ View content
- ✅ Edit content
- ✅ Delete content
- ❌ ~~Publish to Site~~ (removed)

**Why?**
- Ensures content goes through proper approval workflow
- Prevents accidental publishing of unreviewed content
- Clear separation: Review → Approve → Publish

**Workflow:**
```
1. Writer creates content (Draft)
2. Writer submits for review (Review)
3. Editor reviews and approves (Approved)
4. Publisher publishes from Approved page (Published)
```

---

## 7. Best Practices

### When to Publish Immediately

- ✅ Time-sensitive content (news, announcements)
- ✅ Small batches (1-5 items)
- ✅ Testing new content types
- ✅ Urgent fixes or updates

### When to Use Scheduling

- ✅ Large batches (6+ items)
- ✅ Content with planned publish dates
- ✅ Avoiding rate limits
- ✅ Publishing during optimal times
- ✅ Automated publishing workflows
- ✅ Content calendar planning

### Scheduling Tips

1. **Use Site Defaults**: Let system handle timing automatically
2. **Stagger Publications**: 15-30 minute intervals reduce load
3. **Check Timezone**: Ensure site timezone matches your expectations
4. **Plan Ahead**: Schedule content days/weeks in advance
5. **Monitor Failures**: Check failed items daily, fix issues promptly
6. **Test First**: Publish 1-2 items manually before bulk scheduling

### Error Prevention

1. **Verify Credentials**: Test site connection before bulk operations
2. **Check Content Quality**: Ensure all required fields filled
3. **Validate Images**: Confirm images uploaded and accessible
4. **Review Platform Requirements**: WordPress categories, Shopify collections, etc.
5. **Monitor Rate Limits**: Don't schedule too many items at once
6. **Backup Content**: Export content before large publishing operations

---

## 8. Troubleshooting

### Problem: Publishing is slow

**Solution:**
- Check network connection
- Verify site is responsive
- Use scheduling instead of bulk publish
- Check site server performance

### Problem: All items failing with same error

**Solution:**
- Check Site Settings → API credentials
- Verify domain is correct and accessible
- Test site connection manually
- Check platform API status (WordPress.org, Shopify status page)

### Problem: Items stuck in "publishing" status

**Solution:**
- Backend may be processing
- Wait 5-10 minutes (Celery runs every 5 min)
- Check backend logs for errors
- Contact system administrator if persists

### Problem: Schedule times are wrong timezone

**Solution:**
- Go to Site Settings → Publishing
- Set correct timezone for your site
- Reschedule affected items
- Future schedules will use correct timezone

### Problem: Site selector not updating calendar content

**Solution:**
- Refresh your browser (Ctrl+F5 or Cmd+Shift+R)
- This issue was fixed in latest update (Jan 2026)
- Calendar now automatically reloads when you change sites
- Check browser console for site change logs
- If problem persists, clear browser cache

**What was fixed:**
- Frontend: Fixed useEffect dependency in ContentCalendar.tsx
- Backend: Added site_id and site_status to ContentFilter
- All API queries now properly filter by selected site

### Problem: Cannot see published content on site

**Solution:**
- Click "View on [Site Name]" link to verify URL
- Check site visibility settings (not private/draft)
- Clear site cache if using caching plugin
- Verify content published to correct site
- Check platform-specific visibility settings

### Problem: Bulk publish limit blocking my workflow

**Solution:**
- Use "Schedule Selected" instead (no limit)
- Set up site default schedule for automation
- Or select ≤5 items at a time for immediate publishing

---

## 9. Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Space` | Select/deselect item in table |
| `Shift + Click` | Select range of items |
| `Ctrl/Cmd + Click` | Select multiple non-contiguous items |
| `Esc` | Close modal (when not publishing) |
| `Enter` | Confirm action in modal |

---

## 10. Support and Resources

### Getting Help

- **Documentation**: `docs/40-WORKFLOWS/` (this guide)
- **API Reference**: `docs/20-API/PUBLISHER.md`
- **Developer Docs**: `docs/30-FRONTEND/PUBLISHING-MODALS.md`
- **System Status**: Check backend logs at `/admin/system/logs/`

### Contact

- **Technical Issues**: Contact system administrator
- **Content Questions**: Contact editorial team
- **Platform Setup**: Contact site owner/administrator

---

**Document Version**: 1.0  
**Last Updated**: January 2026  
**Status**: Production Ready