From eadec6eb52313f3176d14247f4b40f482fcad03d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 11 Jan 2026 00:14:30 +0000 Subject: [PATCH] Add comprehensive trigger usage documentation - Created docs/TRIGGER_USAGE.md with detailed guide on using workflow triggers - Updated README.md to reference the new trigger documentation - Documented current implementation status and future enhancements - Included examples, best practices, and troubleshooting guide Co-authored-by: johndoe6345789 <224850594+johndoe6345789@users.noreply.github.com> --- README.md | 4 + docs/TRIGGER_USAGE.md | 375 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 379 insertions(+) create mode 100644 docs/TRIGGER_USAGE.md diff --git a/README.md b/README.md index a480248..de43696 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,10 @@ poetry run validate-workflows See [docs/WORKFLOW_VALIDATION.md](docs/WORKFLOW_VALIDATION.md) for detailed documentation. +### Workflow Triggers + +Workflows now support triggers to define entry points. See [docs/TRIGGER_USAGE.md](docs/TRIGGER_USAGE.md) for usage guide. + ### Python ```bash diff --git a/docs/TRIGGER_USAGE.md b/docs/TRIGGER_USAGE.md new file mode 100644 index 0000000..a10177c --- /dev/null +++ b/docs/TRIGGER_USAGE.md @@ -0,0 +1,375 @@ +# Workflow Trigger Usage Guide + +## Overview + +As of the latest implementation, the AutoMetabuilder workflow engine now supports workflow triggers. Triggers allow you to explicitly define the entry point of a workflow, making workflow execution more predictable and enabling future support for event-driven workflows. + +## What Are Triggers? + +Triggers define how and when a workflow should be executed. They specify: +- **Entry Point**: Which node should start the workflow execution +- **Kind**: The type of trigger (manual, webhook, schedule, etc.) +- **Status**: Whether the trigger is enabled or disabled +- **Metadata**: Additional configuration specific to the trigger type + +## Current Implementation Status + +### ✅ Implemented +- Trigger schema validation (validates trigger structure in workflow JSON) +- Manual trigger support (workflows can specify which node to start from) +- Backward compatibility (workflows without triggers work as before) +- Trigger-based entry point selection + +### 🚧 Planned +- Webhook trigger handling +- Schedule trigger execution (cron-based) +- Queue trigger processing +- Email trigger monitoring +- Poll trigger execution + +## Using Triggers + +### Basic Trigger Definition + +Add a `triggers` array to your workflow JSON: + +```json +{ + "name": "My Workflow", + "nodes": [...], + "connections": {...}, + "triggers": [ + { + "nodeId": "start_node", + "kind": "manual", + "enabled": true, + "meta": { + "description": "Manually triggered workflow execution" + } + } + ] +} +``` + +### Trigger Fields + +- **nodeId** (required): The ID of the node where execution should start +- **kind** (required): One of: `manual`, `webhook`, `schedule`, `queue`, `email`, `poll`, `other` +- **enabled** (optional, default: `true`): Whether this trigger is active +- **meta** (optional): Additional metadata for the trigger + +### Trigger Kinds + +#### Manual Triggers (Currently Supported) +Used for workflows that are manually initiated via CLI or API: + +```json +{ + "nodeId": "load_context", + "kind": "manual", + "enabled": true, + "meta": { + "description": "Start workflow from Load Context node" + } +} +``` + +#### Future Trigger Types + +**Webhook Triggers** (Planned): +```json +{ + "nodeId": "handle_github_event", + "kind": "webhook", + "enabled": true, + "meta": { + "path": "/webhooks/github", + "method": "POST", + "event_types": ["pull_request", "issues"] + } +} +``` + +**Schedule Triggers** (Planned): +```json +{ + "nodeId": "daily_report", + "kind": "schedule", + "enabled": true, + "meta": { + "cron": "0 9 * * *", + "timezone": "UTC", + "description": "Daily report generation at 9 AM UTC" + } +} +``` + +## How Triggers Affect Execution + +### With Triggers + +When a workflow has triggers defined: + +1. The execution engine looks for enabled triggers +2. For manual execution, it finds the first enabled `manual` trigger +3. The workflow starts executing from the node specified in the trigger's `nodeId` +4. Execution proceeds according to the connection graph + +### Without Triggers (Backward Compatible) + +When a workflow has no triggers: + +1. The execution engine uses the default behavior +2. Execution starts from nodes with no incoming connections +3. Nodes are executed in topological order based on the connection graph + +## Example Workflow + +Here's a complete example of a workflow using a manual trigger: + +```json +{ + "name": "Data Processing Workflow", + "active": false, + "nodes": [ + { + "id": "load_data", + "name": "Load Data", + "type": "backend.load_data", + "typeVersion": 1, + "position": [0, 0], + "parameters": {} + }, + { + "id": "transform_data", + "name": "Transform Data", + "type": "backend.transform_data", + "typeVersion": 1, + "position": [300, 0], + "parameters": {} + }, + { + "id": "save_results", + "name": "Save Results", + "type": "backend.save_results", + "typeVersion": 1, + "position": [600, 0], + "parameters": {} + } + ], + "connections": { + "Load Data": { + "main": { + "0": [ + { + "node": "Transform Data", + "type": "main", + "index": 0 + } + ] + } + }, + "Transform Data": { + "main": { + "0": [ + { + "node": "Save Results", + "type": "main", + "index": 0 + } + ] + } + } + }, + "triggers": [ + { + "nodeId": "load_data", + "kind": "manual", + "enabled": true, + "meta": { + "description": "Manually triggered data processing workflow" + } + } + ] +} +``` + +## Multiple Triggers + +You can define multiple triggers in a workflow: + +```json +{ + "triggers": [ + { + "nodeId": "webhook_handler", + "kind": "webhook", + "enabled": true, + "meta": { + "description": "Triggered by GitHub webhook", + "path": "/webhooks/github" + } + }, + { + "nodeId": "scheduled_check", + "kind": "schedule", + "enabled": false, + "meta": { + "description": "Daily scheduled run (currently disabled)", + "cron": "0 10 * * *" + } + }, + { + "nodeId": "manual_run", + "kind": "manual", + "enabled": true, + "meta": { + "description": "Manual execution for testing" + } + } + ] +} +``` + +**Note**: The current implementation uses the first enabled `manual` trigger for manual execution. Future implementations will support routing based on trigger kind. + +## Best Practices + +1. **Always Define Triggers**: Make workflow entry points explicit + - Makes workflows self-documenting + - Enables future event-driven features + - Improves workflow maintainability + +2. **Use Descriptive Metadata**: Document the purpose of each trigger + ```json + "meta": { + "description": "Processes GitHub PR webhooks for CI/CD pipeline", + "event_types": ["pull_request"], + "priority": "high" + } + ``` + +3. **Start Simple**: Begin with manual triggers + - Manual triggers are the simplest and most tested + - Easy to debug and understand + - Can be extended to other trigger types later + +4. **Validate Before Deployment**: Use the validation tool + ```bash + poetry run validate-workflows + ``` + +5. **Test Trigger-Based Execution**: Ensure your workflow works correctly + - Test with triggers enabled + - Test with triggers disabled (backward compatibility) + - Verify the correct entry point is used + +## Migration from Triggerless Workflows + +If you have existing workflows without triggers, they will continue to work with default behavior. To add trigger support: + +1. Identify the intended entry point node +2. Add a `triggers` array with a manual trigger +3. Set the `nodeId` to your entry point node's ID +4. Validate the workflow +5. Test execution + +Example migration: + +**Before**: +```json +{ + "name": "My Workflow", + "nodes": [...], + "connections": {...} +} +``` + +**After**: +```json +{ + "name": "My Workflow", + "nodes": [...], + "connections": {...}, + "triggers": [ + { + "nodeId": "first_node_id", + "kind": "manual", + "enabled": true, + "meta": { + "description": "Manually triggered workflow" + } + } + ] +} +``` + +## Troubleshooting + +### Trigger Not Working + +**Problem**: Workflow doesn't start from the expected node + +**Solutions**: +- Verify the `nodeId` matches an actual node ID in your workflow (not the node name) +- Check that `enabled` is `true` (or omitted, as true is the default) +- For manual execution, ensure the trigger `kind` is `manual` +- Validate your workflow JSON with `poetry run validate-workflows` + +### Invalid Trigger Validation Error + +**Problem**: Workflow validation fails with trigger-related errors + +**Solutions**: +- Ensure `nodeId` and `kind` are both present (required fields) +- Verify `kind` is one of: `manual`, `webhook`, `schedule`, `queue`, `email`, `poll`, `other` +- Check that `enabled` is a boolean, not a string +- Ensure `meta` is an object (dictionary), not a string or array + +### Workflow Ignores Trigger + +**Problem**: Workflow executes but doesn't respect the trigger + +**Solutions**: +- Check if there are multiple triggers - the first enabled `manual` trigger is used +- Verify the workflow is using the updated execution engine +- Check logs for warnings about trigger configuration + +## Technical Details + +### Execution Order Algorithm + +When a trigger is present: + +1. Find the first enabled trigger matching the execution context (currently `manual` for CLI/API execution) +2. Look up the node name by the trigger's `nodeId` +3. Build execution order starting from that node +4. Execute nodes in the determined order + +### Code References + +- Trigger validation: `backend/autometabuilder/workflow/n8n_schema.py` +- Execution order: `backend/autometabuilder/workflow/execution_order.py` +- Trigger handling: `backend/autometabuilder/workflow/n8n_executor.py` +- Schema definition: `backend/autometabuilder/schema/n8n-workflow.schema.json` + +## See Also + +- [Workflow Validation Documentation](WORKFLOW_VALIDATION.md) +- [N8N Workflow Schema](../backend/autometabuilder/schema/n8n-workflow.schema.json) +- [Workflow Triggers Roadmap](archive/WORKFLOW_TRIGGERS.md) (archived documentation) + +## Future Enhancements + +The trigger feature is designed to support future event-driven workflows: + +1. **Webhook Triggers**: Respond to HTTP webhooks (GitHub, Slack, etc.) +2. **Scheduled Triggers**: Run workflows on a schedule (cron-based) +3. **Queue Triggers**: Process tasks from message queues +4. **Email Triggers**: React to incoming emails +5. **Poll Triggers**: Periodically check external systems +6. **Conditional Triggers**: Execute based on complex conditions +7. **Trigger Chains**: Link triggers across workflows +8. **Trigger History**: Log and monitor trigger executions + +The current manual trigger implementation provides the foundation for these future enhancements.