From 718f5fe16b473f533d52d7d7f21375616e33a85d Mon Sep 17 00:00:00 2001 From: Bas van den Aakster Date: Fri, 12 Sep 2025 15:34:20 +0200 Subject: [PATCH] Simplify README: remove marketing language and complex explanations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace "comprehensive" and other marketing terms with plain language - Shorten overly detailed HTTP request documentation - Simplify import structure and data resolution sections - Remove verbose environment variables explanations - Cut scheduled workflows examples to essential information - Make language more direct and honest about development status 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- README.md | 193 ++++++++---------------------------------------------- 1 file changed, 28 insertions(+), 165 deletions(-) diff --git a/README.md b/README.md index 3c3a3b2..66720bd 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,17 @@ # @xtr-dev/payload-automation -A comprehensive workflow automation plugin for PayloadCMS 3.x that enables visual workflow building, execution tracking, and parallel processing. +A workflow automation plugin for PayloadCMS 3.x. Run steps in workflows triggered by document changes or webhooks. -⚠️ **Pre-release Warning**: This package is currently in active development (v0.0.x). Breaking changes may occur before v1.0.0. Not recommended for production use. +⚠️ **Not ready for production**. This package is v0.0.x and may break between versions. -## Features +## What it does -- 🔄 **Visual Workflow Builder** - Create complex workflows with drag-and-drop interface -- ⚡ **Parallel Execution** - Smart dependency resolution for optimal performance -- 🎯 **Multiple Triggers** - Collection hooks, webhooks, manual execution -- ⏰ **Scheduled Workflows** - Use webhook triggers with external cron services -- 📊 **Execution Tracking** - Complete history and monitoring of workflow runs -- 🔧 **Extensible Steps** - HTTP requests, document CRUD, email notifications -- 🔧 **Handlebars Templates** - Dynamic data interpolation with automatic type conversion +- Visual workflow builder in PayloadCMS admin +- Run workflows when documents are created/updated/deleted +- Trigger workflows via webhooks +- Track workflow execution history +- HTTP requests, document operations, email sending +- Use data from previous steps in templates ## Installation @@ -47,94 +46,25 @@ export default buildConfig({ }) ``` -## Import Structure - -The plugin uses separate exports to avoid bundling server-side code in client bundles: +## Imports ```typescript -// Server-side plugin and functions +// Server plugin import { workflowsPlugin } from '@xtr-dev/payload-automation/server' -// Client-side components +// Client components import { StatusCell, ErrorDisplay } from '@xtr-dev/payload-automation/client' -// Helper utilities -import { /* helpers */ } from '@xtr-dev/payload-automation/helpers' - -// Types only (safe for both server and client) +// Types import type { WorkflowsPluginConfig } from '@xtr-dev/payload-automation' ``` ## Step Types ### HTTP Request -Make external API calls with comprehensive error handling and retry logic. +Call external APIs. Supports GET, POST, PUT, DELETE, PATCH. Uses Bearer tokens, API keys, or basic auth. -**Key Features:** -- Support for GET, POST, PUT, DELETE, PATCH methods -- Authentication: Bearer token, Basic auth, API key headers -- Configurable timeouts and retry logic -- Handlebars templates for dynamic URLs and request bodies - -**Error Handling:** -HTTP Request steps use a **response-based success model** rather than status-code-based failures: - -- ✅ **Successful completion**: All HTTP requests that receive a response (including 4xx/5xx status codes) are marked as "succeeded" -- ❌ **Failed execution**: Only network errors, timeouts, DNS failures, and connection issues cause step failure -- 📊 **Error information preserved**: HTTP error status codes (404, 500, etc.) are captured in the step output for workflow conditional logic - -**Example workflow logic:** -```typescript -// Step outputs for a 404 response: -{ - "status": 404, - "statusText": "Not Found", - "body": "Resource not found", - "headers": {...}, - "duration": 1200 -} - -// Use in workflow conditions: -// "{{steps.apiRequest.output.status}} >= 400" to handle errors -``` - -This design allows workflows to handle HTTP errors gracefully rather than failing completely, enabling robust error handling and retry logic. - -**Enhanced Error Tracking:** -For network failures (timeouts, DNS errors, connection failures), the plugin provides detailed error information through an independent storage system that bypasses PayloadCMS's output limitations: - -```typescript -// Timeout error details preserved in workflow context: -{ - "steps": { - "httpStep": { - "state": "failed", - "error": "Task handler returned a failed state", - "errorDetails": { - "errorType": "timeout", - "duration": 2006, - "attempts": 1, - "finalError": "Request timeout after 2000ms", - "context": { - "url": "https://api.example.com/data", - "method": "GET", - "timeout": 2000 - } - }, - "executionInfo": { - "completed": true, - "success": false, - "executedAt": "2025-09-04T15:16:10.000Z", - "duration": 2006 - } - } - } -} - -// Access in workflow conditions: -// "{{steps.httpStep.errorDetails.errorType}} == 'timeout'" -// "{{steps.httpStep.errorDetails.duration}} > 5000" -``` +HTTP steps succeed even with 4xx/5xx status codes. Only network errors (timeouts, DNS failures) cause step failure. Check `{{steps.stepName.output.status}}` for error handling. ### Document Operations - **Create Document** - Create PayloadCMS documents @@ -145,38 +75,17 @@ For network failures (timeouts, DNS errors, connection failures), the plugin pro ### Communication - **Send Email** - Send notifications via PayloadCMS email -## Data Resolution +## Templates -Use Handlebars templates to access workflow data: +Use `{{}}` to insert data: -- `{{trigger.doc.id}}` - Access trigger document -- `{{steps.stepName.output}}` - Use previous step outputs -- `{{context}}` - Access workflow context - -### Template Examples +- `{{trigger.doc.id}}` - Data from the document that triggered the workflow +- `{{steps.stepName.output}}` - Data from previous steps +Example: ```json { "url": "https://api.example.com/posts/{{steps.createPost.output.id}}", - "message": "Post {{trigger.doc.title}} was updated by {{trigger.req.user.email}}", - "timeout": "{{steps.configStep.output.timeoutMs}}" -} -``` - -### Automatic Type Conversion - -Handlebars templates automatically convert string results to appropriate types based on field names: - -- **Numbers**: `timeout`, `retries`, `delay`, `port`, `count`, etc. → converted to numbers -- **Booleans**: `enabled`, `active`, `success`, `complete`, etc. → converted to booleans -- **Numeric strings**: `"5000"` → `5000`, `"3.14"` → `3.14` - -### Conditions - -Conditions support Handlebars templates with comparison operators: - -```json -{ "condition": "{{trigger.doc.status}} == 'published'" } ``` @@ -187,71 +96,25 @@ Conditions support Handlebars templates with comparison operators: - Node.js ^18.20.2 || >=20.9.0 - pnpm ^9 || ^10 -## Environment Variables +## Logging -Control plugin logging with these environment variables: +Set `PAYLOAD_AUTOMATION_LOG_LEVEL` to control logs: +- `silent`, `error`, `warn` (default), `info`, `debug`, `trace` -### `PAYLOAD_AUTOMATION_LOG_LEVEL` -Controls both configuration-time and runtime logging. -- **Values**: `silent`, `error`, `warn`, `info`, `debug`, `trace` -- **Default**: `warn` -- **Example**: `PAYLOAD_AUTOMATION_LOG_LEVEL=debug` - -### `PAYLOAD_AUTOMATION_CONFIG_LOG_LEVEL` (optional) -Override log level specifically for configuration-time logs (plugin setup). -- **Values**: Same as above -- **Default**: Falls back to `PAYLOAD_AUTOMATION_LOG_LEVEL` or `warn` -- **Example**: `PAYLOAD_AUTOMATION_CONFIG_LOG_LEVEL=silent` - -### Production Usage -For production, keep the default (`warn`) or use `error` or `silent`: -```bash -PAYLOAD_AUTOMATION_LOG_LEVEL=error npm start -``` - -### Development Usage -For debugging, use `debug` or `info`: ```bash PAYLOAD_AUTOMATION_LOG_LEVEL=debug npm run dev ``` ## Scheduled Workflows -For scheduled workflows, use **webhook triggers** with external cron services instead of built-in cron triggers: +Use webhook triggers with external cron services: -### GitHub Actions (Free) -```yaml -# .github/workflows/daily-report.yml -on: - schedule: - - cron: '0 9 * * *' # Daily at 9 AM UTC -jobs: - trigger-workflow: - runs-on: ubuntu-latest - steps: - - run: curl -X POST https://your-app.com/api/workflows-webhook/daily-report +```bash +# Call workflow webhook from cron +curl -X POST https://your-app.com/api/workflows-webhook/daily-report ``` -### Vercel Cron (Serverless) -```js -// api/cron/daily.js -export default async function handler(req, res) { - await fetch('https://your-app.com/api/workflows-webhook/daily-report', { - method: 'POST', - headers: { 'Content-Type': 'application/json' }, - body: JSON.stringify({ source: 'vercel-cron' }) - }); - res.status(200).json({ success: true }); -} -``` - -**Benefits**: Better reliability, proper process isolation, easier debugging, and leverages existing infrastructure. - -**Note**: Built-in cron triggers have been removed in v0.0.37+ to focus on webhook-based scheduling which provides better reliability and debugging capabilities. - -## Documentation - -Full documentation coming soon. For now, explore the development environment in the repository for examples and patterns. +Built-in cron triggers were removed in v0.0.37+. ## License