This project demonstrates a simple dynamic workflow system built on top of Payload CMS.
The idea is to allow administrators to create workflows with multiple steps and attach them to different collections (for example blog posts or contracts). Whenever a document is saved, the workflow engine evaluates the current step and records the activity in a workflow log.
The system is intentionally kept simple to focus on the workflow architecture.
src ├ collections │ Blog.ts │ Contract.ts │ Workflows.ts │ WorkflowLogs.ts │ ├ hooks │ triggerWorkflow.ts │ ├ plugins │ workflowEngine.ts │ ├ routes │ triggerWorkflow.ts │ workflowStatus.ts │ ├ payload.config.ts └ server.ts
The workflow system is built using four main parts:
Collections define the data structure used by Payload CMS.
Workflows
- Stores workflow definitions
- Each workflow contains multiple steps
WorkflowLogs
- Stores workflow activity history
- Works as an audit trail
Blog
- Example content collection
- Supports attaching workflows
Contract
- Another example collection
- Demonstrates that workflows can be used across multiple collections
Payload hooks are used to trigger workflow logic automatically.
The afterChange hook runs every time a document is created or updated.
This hook calls the workflow engine.
The workflow engine processes workflow logic.
It performs the following steps:
- Checks if a document has a workflow attached
- Loads the workflow definition
- Determines the current step
- Records the action in
workflowLogs
This keeps the workflow logic separate from the collections.
Two simple API endpoints are included.
Trigger workflow manually
POST /workflows/trigger
Body example:
{ "collection": "blog", "docId": "123" }
Get workflow status
GET /workflows/status/:docId
Returns workflow logs related to the document.
Clone the repository:
git clone cd payload-workflow
Install dependencies:
npm install
Start MongoDB:
mongod
Run the server:
npm run dev
Open the admin panel:
Create the first admin user when prompted.
Example workflow configuration:
Blog Approval Workflow
Step 1: Review Step 2: Approval Step 3: Signoff