payload-automation/UPDATE-GUIDANCE-v0.0.16.md

🚨 Critical Update: PayloadCMS Automation Plugin v0.0.16

⚡ Immediate Action Required

A critical bug has been identified and fixed in v0.0.15 that prevented workflows from executing in development environments. Please update immediately to resolve workflow execution issues.

🔧 Quick Update Steps

1. Update the Package

npm update @xtr-dev/payload-automation
# OR
yarn upgrade @xtr-dev/payload-automation
# OR  
pnpm update @xtr-dev/payload-automation

2. Verify Version

Check that you're now on v0.0.16:

npm list @xtr-dev/payload-automation

3. Restart Your Development Server

# Stop your current dev server (Ctrl+C)
# Then restart
npm run dev
# OR
yarn dev  
# OR
pnpm dev

4. Test Your Workflows

Your workflows should now execute properly! Look for these log messages:

[payload-automation] Plugin initialized successfully - all hooks registered
AUTOMATION PLUGIN: Collection hook triggered
executeTriggeredWorkflows called
Found workflows to check

🐛 What Was Fixed

Critical Bug: Hook Registration Failure

• Problem: The hooksInitialized flag prevented proper hook registration in development mode
• Symptom: Workflows would not execute even when correctly configured
• Fix: Removed the problematic flag, ensuring hooks register on every initialization

Enhanced Debugging

• Added: Comprehensive logging with "AUTOMATION PLUGIN:" prefix
• Added: Try/catch blocks to prevent silent failures
• Added: Better error messages and stack traces

🔍 Troubleshooting

If workflows still don't execute after updating:

1. Check your workflow configuration (should now use v0.0.15+ schema):

   // ✅ Correct v0.0.15+ schema
   {
     triggers: [{
       type: 'collection-trigger',
       collectionSlug: 'orders',
       operation: 'update', 
       condition: '$.trigger.doc.status == "Paid"' // JSONPath format
     }],
     steps: [{
       step: 'uppercaseText',  // 'step' not 'type'
       name: 'Process Order',
       input: {               // 'input' not 'inputs'
         inputText: '$.trigger.doc.orderName has been paid!'
       }
     }]
   }
   

2. Verify plugin configuration includes your collections:

   automationPlugin({
     collections: ['orders', 'users', 'products'], // Must include target collections
     // ... other config
   })
   

3. Check the logs for "AUTOMATION PLUGIN:" messages during hook execution

4. Ensure workflow status: If using versioning, make sure workflows are "Published" not "Draft"

📋 Schema Changes Recap (from v0.0.14 → v0.0.15+)

If you haven't updated your workflows since v0.0.14, you'll also need to update the schema:

Triggers

// ❌ OLD v0.0.14
conditions: [
  { field: 'status', operator: 'equals', value: 'Paid' }
]

// ✅ NEW v0.0.15+
condition: '$.trigger.doc.status == "Paid"'

Steps

// ❌ OLD v0.0.14
{
  type: 'uppercaseText',
  inputs: { inputText: 'Hello' }
}

// ✅ NEW v0.0.15+
{
  step: 'uppercaseText', 
  input: { inputText: 'Hello' }
}

🆘 Support

If you're still experiencing issues after updating to v0.0.16:

1. Check console logs for "AUTOMATION PLUGIN:" messages
2. Verify your workflow schema matches v0.0.15+ format
3. Confirm plugin configuration includes target collections
4. File an issue at https://github.com/anthropics/claude-code/issues with:
   • PayloadCMS version
   • Complete console logs during workflow execution
   • Your workflow configuration (sanitized)

✅ Success Indicators

After updating, you should see:

• ✅ Workflow runs created in workflow-runs collection
• ✅ "AUTOMATION PLUGIN:" log messages during hook execution
• ✅ Jobs appearing in payload-jobs collection
• ✅ Workflow steps executing successfully

---

This is a critical bug fix release - no breaking changes, just fixes the core functionality that wasn't working in v0.0.15.