mirror of
https://github.com/xtr-dev/payload-automation.git
synced 2025-12-10 17:03:22 +00:00
Bas van den Aakster
718f5fe16b
- 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>
121 lines
2.9 KiB
Markdown
121 lines
2.9 KiB
Markdown
# @xtr-dev/payload-automation
|
|
|
|
A workflow automation plugin for PayloadCMS 3.x. Run steps in workflows triggered by document changes or webhooks.
|
|
|
|
⚠️ **Not ready for production**. This package is v0.0.x and may break between versions.
|
|
|
|
## What it does
|
|
|
|
- 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
|
|
|
|
```bash
|
|
npm install @xtr-dev/payload-automation
|
|
# or
|
|
pnpm add @xtr-dev/payload-automation
|
|
# or
|
|
yarn add @xtr-dev/payload-automation
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```typescript
|
|
import { buildConfig } from 'payload'
|
|
import { workflowsPlugin } from '@xtr-dev/payload-automation/server'
|
|
|
|
export default buildConfig({
|
|
// ... your config
|
|
plugins: [
|
|
workflowsPlugin({
|
|
collectionTriggers: {
|
|
posts: true, // Enable all CRUD triggers for posts
|
|
users: {
|
|
create: true, // Only enable create trigger for users
|
|
update: true
|
|
}
|
|
},
|
|
enabled: true,
|
|
}),
|
|
],
|
|
})
|
|
```
|
|
|
|
## Imports
|
|
|
|
```typescript
|
|
// Server plugin
|
|
import { workflowsPlugin } from '@xtr-dev/payload-automation/server'
|
|
|
|
// Client components
|
|
import { StatusCell, ErrorDisplay } from '@xtr-dev/payload-automation/client'
|
|
|
|
// Types
|
|
import type { WorkflowsPluginConfig } from '@xtr-dev/payload-automation'
|
|
```
|
|
|
|
## Step Types
|
|
|
|
### HTTP Request
|
|
Call external APIs. Supports GET, POST, PUT, DELETE, PATCH. Uses Bearer tokens, API keys, or basic auth.
|
|
|
|
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
|
|
- **Read Document** - Query documents with filters
|
|
- **Update Document** - Modify existing documents
|
|
- **Delete Document** - Remove documents
|
|
|
|
### Communication
|
|
- **Send Email** - Send notifications via PayloadCMS email
|
|
|
|
## Templates
|
|
|
|
Use `{{}}` to insert data:
|
|
|
|
- `{{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}}",
|
|
"condition": "{{trigger.doc.status}} == 'published'"
|
|
}
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- PayloadCMS ^3.45.0
|
|
- Node.js ^18.20.2 || >=20.9.0
|
|
- pnpm ^9 || ^10
|
|
|
|
## Logging
|
|
|
|
Set `PAYLOAD_AUTOMATION_LOG_LEVEL` to control logs:
|
|
- `silent`, `error`, `warn` (default), `info`, `debug`, `trace`
|
|
|
|
```bash
|
|
PAYLOAD_AUTOMATION_LOG_LEVEL=debug npm run dev
|
|
```
|
|
|
|
## Scheduled Workflows
|
|
|
|
Use webhook triggers with external cron services:
|
|
|
|
```bash
|
|
# Call workflow webhook from cron
|
|
curl -X POST https://your-app.com/api/workflows-webhook/daily-report
|
|
```
|
|
|
|
Built-in cron triggers were removed in v0.0.37+.
|
|
|
|
## License
|
|
|
|
MIT |