Simplify README: remove marketing language and complex explanations

- 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 <noreply@anthropic.com>
This commit is contained in:
2025-09-12 15:34:20 +02:00
parent 10a4ca1b35
commit 718f5fe16b

193
README.md
View File

@@ -1,18 +1,17 @@
# @xtr-dev/payload-automation # @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 - Visual workflow builder in PayloadCMS admin
- **Parallel Execution** - Smart dependency resolution for optimal performance - Run workflows when documents are created/updated/deleted
- 🎯 **Multiple Triggers** - Collection hooks, webhooks, manual execution - Trigger workflows via webhooks
- **Scheduled Workflows** - Use webhook triggers with external cron services - Track workflow execution history
- 📊 **Execution Tracking** - Complete history and monitoring of workflow runs - HTTP requests, document operations, email sending
- 🔧 **Extensible Steps** - HTTP requests, document CRUD, email notifications - Use data from previous steps in templates
- 🔧 **Handlebars Templates** - Dynamic data interpolation with automatic type conversion
## Installation ## Installation
@@ -47,94 +46,25 @@ export default buildConfig({
}) })
``` ```
## Import Structure ## Imports
The plugin uses separate exports to avoid bundling server-side code in client bundles:
```typescript ```typescript
// Server-side plugin and functions // Server plugin
import { workflowsPlugin } from '@xtr-dev/payload-automation/server' import { workflowsPlugin } from '@xtr-dev/payload-automation/server'
// Client-side components // Client components
import { StatusCell, ErrorDisplay } from '@xtr-dev/payload-automation/client' import { StatusCell, ErrorDisplay } from '@xtr-dev/payload-automation/client'
// Helper utilities // Types
import { /* helpers */ } from '@xtr-dev/payload-automation/helpers'
// Types only (safe for both server and client)
import type { WorkflowsPluginConfig } from '@xtr-dev/payload-automation' import type { WorkflowsPluginConfig } from '@xtr-dev/payload-automation'
``` ```
## Step Types ## Step Types
### HTTP Request ### 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:** 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.
- 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"
```
### Document Operations ### Document Operations
- **Create Document** - Create PayloadCMS documents - **Create Document** - Create PayloadCMS documents
@@ -145,38 +75,17 @@ For network failures (timeouts, DNS errors, connection failures), the plugin pro
### Communication ### Communication
- **Send Email** - Send notifications via PayloadCMS email - **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 - `{{trigger.doc.id}}` - Data from the document that triggered the workflow
- `{{steps.stepName.output}}` - Use previous step outputs - `{{steps.stepName.output}}` - Data from previous steps
- `{{context}}` - Access workflow context
### Template Examples
Example:
```json ```json
{ {
"url": "https://api.example.com/posts/{{steps.createPost.output.id}}", "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'" "condition": "{{trigger.doc.status}} == 'published'"
} }
``` ```
@@ -187,71 +96,25 @@ Conditions support Handlebars templates with comparison operators:
- Node.js ^18.20.2 || >=20.9.0 - Node.js ^18.20.2 || >=20.9.0
- pnpm ^9 || ^10 - 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 ```bash
PAYLOAD_AUTOMATION_LOG_LEVEL=debug npm run dev PAYLOAD_AUTOMATION_LOG_LEVEL=debug npm run dev
``` ```
## Scheduled Workflows ## 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) ```bash
```yaml # Call workflow webhook from cron
# .github/workflows/daily-report.yml curl -X POST https://your-app.com/api/workflows-webhook/daily-report
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
``` ```
### Vercel Cron (Serverless) Built-in cron triggers were removed in v0.0.37+.
```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.
## License ## License