# Release v1.12.0: Change Simulation & Approval System
**Release Date**: 2024-12-16
## 🎯 Overview
Version 1.12.0 introduces a **Terraform-style change simulation and approval system** for n8n workflows. This powerful feature enables safe, predictable workflow deployments by previewing changes, analyzing impact, and managing approvals before applying updates.
## 🚀 New Features
### 1. Change Simulation (Dry-Run)
Preview workflow changes before deploying them, just like `terraform plan`:
**Core Capabilities**:
- 🔍 **Comprehensive Diff**: Detailed comparison of old vs new workflows
- 🎯 **Impact Analysis**: Multi-dimensional risk assessment across 5 dimensions
- ✅ **Validation**: Structure and semantic validation without applying changes
- 📊 **Performance Estimation**: Predict execution time, memory usage, complexity
- 🚨 **Breaking Change Detection**: Automatically identifies critical changes
**5 Impact Dimensions**:
1. **Data Flow Impact**: Broken paths, new paths, transformation changes
2. **Execution Impact**: Performance, reliability changes
3. **Dependency Impact**: New services, new credentials required
4. **Trigger Impact**: Trigger type changes, parameter modifications
5. **Downstream Impact**: Effects on workflows that call this one
### 2. Change Approval Workflow
Structured approval process for workflow changes:
**Features**:
- 📝 **Change Requests**: Document changes with reason and requester
- ✅ **Approval Flow**: Review, approve, or reject changes
- 📜 **Change History**: Complete audit trail of all changes
- 🔄 **Status Tracking**: pending → approved → applied (or rejected/failed)
- 👥 **Multi-User**: Track requester, reviewer, timestamps
### 3. Terraform-Style Output
Clear, color-coded change visualization:
```
================================================================================
WORKFLOW CHANGE PLAN
================================================================================
Total Changes: 8
Risk Level: MEDIUM
🔴 BREAKING CHANGES
--------------------------------------------------------------------------------
• [CRITICAL] Trigger node 'Schedule Trigger' removed
Impact: Workflow will no longer be triggered automatically
Recommendation: Ensure alternative trigger exists
🟡 STRUCTURAL CHANGES
--------------------------------------------------------------------------------
+ Added node: 'Error Handler' (n8n-nodes-base.errorTrigger)
- Removed node: 'Old Logger' (n8n-nodes-base.httpRequest)
~ Modified node: 'Process Payment'
parameters.amount: 100 → 150
parameters.currency: USD → EUR
🟢 DATA FLOW CHANGES
--------------------------------------------------------------------------------
+ New path: Process Payment → Error Handler
- Removed path: Old Logger → Email Send
⚠️ IMPACT ASSESSMENT
--------------------------------------------------------------------------------
Overall Risk Score: 5.5/10 (MEDIUM)
Data Flow Impact:
• 2 data path(s) removed
• Data transformation logic in 'Process Payment' was modified
Dependency Impact:
• 1 new credential(s) required
💡 RECOMMENDATIONS
--------------------------------------------------------------------------------
⚠️ Test in staging environment before deploying to production
🔑 Configure 1 new credential(s) before deployment
📊 Verify data flow changes don't break data pipelines
================================================================================
⚠️ WARNING: This change contains breaking changes!
Review carefully before applying.
================================================================================
DRY-RUN SIMULATION
================================================================================
✅ Simulation PASSED - Workflow is valid
**Estimated Performance:**
- Node Count: 12
- Duration: ~6.0s
- Memory: ~120MB
- Complexity: MEDIUM
```
## 🛠️ New MCP Tools
### `simulate_workflow_changes`
**Purpose**: Preview workflow changes with terraform-style plan
**Usage**:
```json
{
"workflow_id": "8PyhAN1U4JvF5eSb",
"new_workflow": {
"name": "Updated Workflow",
"nodes": [...],
"connections": {...}
}
}
```
**Returns**:
- Terraform-style change plan
- Breaking change warnings
- Impact assessment with recommendations
- Dry-run validation results
- Performance estimates
---
### `compare_workflows`
**Purpose**: Side-by-side workflow comparison
**Usage**:
```json
{
"workflow_id_1": "8PyhAN1U4JvF5eSb",
"workflow_id_2": "9QziBO2V5KwG6fTc"
}
```
**Returns**:
- Detailed diff of all changes
- Added/removed/modified nodes
- Connection changes
- Breaking changes list
---
### `analyze_change_impact`
**Purpose**: Multi-dimensional impact analysis
**Usage**:
```json
{
"workflow_id": "8PyhAN1U4JvF5eSb",
"new_workflow": {...},
"include_downstream": true
}
```
**Returns**:
- Overall risk score (0-10)
- 5 impact dimensions with details
- Affected workflows
- Mitigation recommendations
---
### `create_change_request`
**Purpose**: Create change request for approval
**Usage**:
```json
{
"workflow_id": "8PyhAN1U4JvF5eSb",
"workflow_name": "Payment Processing",
"changes": {...},
"reason": "Update payment gateway API endpoint",
"requester": "john.doe"
}
```
**Returns**:
- Change request ID
- Request details
- Status (pending)
---
### `review_change_request`
**Purpose**: Approve or reject change request
**Usage**:
```json
{
"request_id": "a3b4c5d6",
"action": "approve",
"reviewer": "jane.smith",
"comments": "LGTM - tested in staging"
}
```
**Returns**:
- Updated request status
- Review details
- Timestamp
---
### `get_change_history`
**Purpose**: Get change history for workflow
**Usage**:
```json
{
"workflow_id": "8PyhAN1U4JvF5eSb"
}
```
**Returns**:
- All change requests
- Status summary
- Recent changes with details
## 📦 Technical Implementation
### New Modules
**`src/n8n_workflow_builder/changes/`**:
- `diff_engine.py` (450 lines): Workflow comparison engine
- `impact_analyzer.py` (470 lines): Multi-dimensional impact analysis
- `dry_run.py` (96 lines): Safe change validation
- `approval.py` (139 lines): Change request management
- `formatter.py` (140 lines): Terraform-style output formatting
### Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ Change Simulation Flow │
└─────────────────────────────────────────────────────────────┘
1. User proposes changes
↓
2. WorkflowDiffEngine: Compare old vs new
↓
3. DryRunSimulator: Validate structure & semantics
↓
4. ChangeImpactAnalyzer: Assess 5 impact dimensions
↓
5. ChangeFormatter: Generate terraform-style plan
↓
6. ApprovalWorkflow: Create change request
↓
7. Review & approve/reject
↓
8. Apply changes (if approved)
```
### Breaking Change Detection
Automatically detects:
- ✅ Removed trigger nodes
- ✅ Trigger type changes
- ✅ Removed connections
- ✅ Removed output nodes (email, slack, http, database)
- ✅ New credentials required
- ✅ Changed trigger parameters
### Risk Scoring Algorithm
**Score Calculation** (0-10 scale):
- Breaking changes: +2.0 each
- Data flow breaking changes: +1.5
- Execution breaking changes: +1.0
- Dependency breaking changes: +1.5
- Trigger changes: +2.5
- Downstream impact: +1.5
- Nodes removed: +0.5 each
- Connections removed: +0.3 each
**Risk Levels**:
- 0-3: LOW (safe to deploy)
- 3-5: MEDIUM (review recommended)
- 5-7: HIGH (careful testing required)
- 7-10: CRITICAL (extensive validation needed)
## 🎯 Use Cases
### 1. Safe Production Deployments
**Before v1.12.0**:
```bash
# Deploy directly - hope for the best
n8n workflow update --id 123 --file workflow.json
```
**With v1.12.0**:
```bash
# Preview changes first
simulate_workflow_changes(workflow_id="123", new_workflow={...})
# Review impact
# ⚠️ Risk Score: 7.5/10 (HIGH)
# 🔴 2 breaking changes detected
# 💡 Test in staging first
# Create approval request
create_change_request(...)
# Review & approve
review_change_request(request_id="...", action="approve", ...)
# Apply changes safely
```
### 2. Change Impact Analysis
**Scenario**: Update API endpoint in payment workflow
```bash
analyze_change_impact(workflow_id="payment-api", new_workflow={...})
```
**Output**:
```
Risk Score: 4.2/10 (MEDIUM)
🔗 Dependency Impact:
- 1 new external service: Stripe API v2024
- 1 new credential required: stripe_api_key_v2
⚙️ Downstream Impact:
- Changes will affect 3 workflows:
• Order Processing (calls this workflow)
• Refund Handler (calls this workflow)
• Subscription Manager (calls this workflow)
💡 Recommendations:
🔑 Configure new credential before deployment
⚙️ Review and update 3 downstream workflows
🧪 Run end-to-end tests
```
### 3. Team Collaboration
**Workflow**:
```bash
# Developer proposes changes
request = create_change_request(
workflow_id="prod-workflow",
changes={...},
reason="Fix timeout issue in API call",
requester="dev.user"
)
# Team lead reviews
simulate_workflow_changes(...)
# Looks good - only configuration change
# Team lead approves
review_change_request(
request_id=request.id,
action="approve",
reviewer="team.lead",
comments="Approved - low risk configuration change"
)
# Developer applies changes
# Change is tracked in history
```
### 4. Audit Trail
**Query change history**:
```bash
history = get_change_history(workflow_id="prod-workflow")
```
**Output**:
```
# Change History
Total Requests: 15
Status Summary:
- applied: 12
- rejected: 2
- pending: 1
Recent Changes:
✔️ Request a3b4c5d6
- Status: applied
- Requester: dev.user
- Reason: Fix timeout issue
- Reviewer: team.lead
- Comments: Approved - low risk change
❌ Request x1y2z3a4
- Status: rejected
- Requester: junior.dev
- Reason: Refactor entire workflow
- Reviewer: senior.dev
- Comments: Too many breaking changes - split into smaller changes
```
## 🔧 Integration Examples
### Example 1: CI/CD Pipeline
```yaml
# .github/workflows/deploy.yml
name: Deploy Workflow Changes
on:
pull_request:
branches: [main]
jobs:
simulate:
runs-on: ubuntu-latest
steps:
- name: Simulate Changes
run: |
# Load new workflow from PR
NEW_WORKFLOW=$(cat workflow.json)
# Simulate changes
PLAN=$(mcp call simulate_workflow_changes \
--workflow_id "$WORKFLOW_ID" \
--new_workflow "$NEW_WORKFLOW")
# Check risk level
RISK=$(echo "$PLAN" | grep "Risk Level" | cut -d: -f2)
if [[ "$RISK" == *"CRITICAL"* ]]; then
echo "❌ CRITICAL risk detected - manual review required"
exit 1
fi
# Post plan to PR comment
gh pr comment $PR_NUMBER --body "$PLAN"
deploy:
needs: simulate
if: github.event.pull_request.merged == true
runs-on: ubuntu-latest
steps:
- name: Apply Changes
run: |
n8n workflow update --id "$WORKFLOW_ID" --file workflow.json
```
### Example 2: Pre-commit Hook
```bash
#!/bin/bash
# .git/hooks/pre-commit
# Check if workflow files changed
CHANGED_WORKFLOWS=$(git diff --cached --name-only | grep "workflows/.*\.json$")
if [ -n "$CHANGED_WORKFLOWS" ]; then
echo "🔍 Simulating workflow changes..."
for workflow_file in $CHANGED_WORKFLOWS; do
WORKFLOW_ID=$(basename "$workflow_file" .json)
NEW_WORKFLOW=$(cat "$workflow_file")
# Simulate changes
PLAN=$(mcp call simulate_workflow_changes \
--workflow_id "$WORKFLOW_ID" \
--new_workflow "$NEW_WORKFLOW")
# Check for breaking changes
if echo "$PLAN" | grep -q "BREAKING CHANGES"; then
echo "⚠️ Breaking changes detected in $workflow_file"
echo "$PLAN"
read -p "Continue with commit? (y/n) " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
exit 1
fi
fi
done
fi
```
## 📊 Performance
**Benchmarks** (tested with 50-node workflow):
- Diff generation: ~50ms
- Impact analysis: ~150ms
- Dry-run simulation: ~200ms
- Full simulation: ~400ms
**Memory Usage**:
- Typical: ~10MB per workflow comparison
- Large workflows (100+ nodes): ~30MB
## 🐛 Known Limitations
1. **In-Memory State**: Approval workflow state is stored in memory (not persisted)
- **Workaround**: Integrate with external database for production use
2. **Downstream Detection**: Only detects workflows connected via `Execute Workflow` nodes
- **Workaround**: Manual review of indirect dependencies
3. **External API Changes**: Cannot detect breaking changes in external service APIs
- **Workaround**: Include API version checks in recommendations
## 🔜 Future Enhancements
**v1.13.0 Candidates**:
- Persistent change request storage (database integration)
- Slack/Teams notifications for approval requests
- Automated rollback on deployment failure
- Change request templates
- Multi-stage approval workflows
- Impact visualization dashboard
## 🙏 Credits
**Inspired by**:
- Terraform's `terraform plan` workflow
- Kubernetes `kubectl diff` functionality
- Database migration tools (Flyway, Liquibase)
## 📚 Documentation
- **README.md**: Updated with change simulation features
- **API Reference**: All 6 new MCP tools documented
- **Examples**: CI/CD integration examples added
## 🔗 Related Releases
- v1.11.0: Explainability Layer
- v1.11.1: Bugfix release (connection structure parsing)
---
**Full Changelog**: https://github.com/yourusername/n8n-workflow-builder/compare/v1.11.1...v1.12.0
**Installation**:
```bash
pip install --upgrade n8n-workflow-builder
```
**Questions?** Open an issue on GitHub or contact the maintainers.
