mirror of
https://github.com/xtr-dev/payload-automation.git
synced 2025-12-10 00:43:23 +00:00
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.
|
|
|
|
## Features
|
|
|
|
- 🔄 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 |