Workflow Versioning

Versioning enables safe workflow changes with controlled releases, revision tracking, and rollback capabilities. This ensures production workflows remain stable while you iterate on improvements.

Version Concepts

Version Structure

Each workflow can have multiple versions:

Workflow
├── Version 1 (superseded)
├── Version 2 (active)
└── Version 3 (draft)

Version vs Revision

Example:

Version 2, Revision 0 → First save of Version 2
Version 2, Revision 1 → Second save
Version 2, Revision 2 → Third save

Version Lifecycle

States

State Transitions

Draft ──▶ Active ──▶ Superseded
  │                           │
  └────────────────▶ Deleted ◀┘

Timestamps

Creating Versions

New Version

Create a new version when making significant changes:

1. Open workflow editor
2. Click "Create New Version"
3. Optionally copy from existing version
4. Edit the new version
5. Test before releasing

Version Numbering

Versions are numbered sequentially:

Version 1 → Version 2 → Version 3 → ...

Version numbers cannot be reused once created.

Releasing Versions

Release Process

1. Test - Verify workflow works correctly
2. Review - Check all node configurations
3. Release - Make the version Active
4. Monitor - Watch for issues
5. Archive - Archive old version (optional)

Release Notes

Add release notes to document changes:

## Version 3 Release Notes
- Added Slack notification for urgent meetings
- Changed AI model from medium to high for analysis
- Fixed email template formatting

What Happens on Release

When a version is released:

1. Previous Active version becomes Superseded
2. New version becomes Active
3. New events trigger the Active version
4. In-progress executions continue on their version

Version Relationships

Execution Binding

Each execution is bound to a specific version:

Event → Triggers Version 2 → Execution runs Version 2

Even if Version 3 is released during execution, the execution continues with Version 2.

Trigger Configuration

The execution trigger links to a specific version:

{
  "workflowId": "wf-123",
  "versionId": "v2-456",
  "type": "EVENT",
  "eventType": "MEETING_ENDED"
}

Rollback

When to Rollback

Consider rollback when:

• New version has bugs
• Performance degradation
• Unexpected behavior
• Integration failures

Rollback Process

1. Identify the stable version
2. Release the stable version (re-release)
3. Monitor to confirm fix
4. Investigate and fix new version
5. Re-release fixed version

Rollback Considerations

Version Comparison

Comparing Versions

View differences between versions:

1. Select two versions to compare
2. Review structural changes
3. Review configuration changes
4. Identify node additions/removals

Comparison Elements

Best Practices

1. Version Meaningful Changes

Create new versions for:

• ✅ Adding new nodes or paths
• ✅ Changing business logic
• ✅ Modifying AI prompts significantly
• ✅ Updating integrations

Don't version for:

• ❌ Minor text fixes
• ❌ Whitespace changes
• ❌ Testing during development

2. Write Clear Release Notes

Document changes for future reference:

## Changes in Version 4
- Added: Urgent flag detection before notification
- Changed: AI model tier from low to medium
- Fixed: Email formatting for long summaries
- Removed: Deprecated SMS notification path

3. Test Before Releasing

Before releasing:

1. Test with MANUAL trigger
2. Verify all paths work
3. Check error handling
4. Review AI outputs
5. Confirm integration connectivity

4. Keep One Version Active

Avoid multiple released versions:

✅ Good:

Version 1: Superseded
Version 2: Active
Version 3: Draft

❌ Confusing:

Version 1: Active
Version 2: Active  // Which one triggers?

5. Keep History, Don't Delete

Preserve version history:

• Superseded versions are kept for reference
• Delete only failed experiments
• Keep release notes accessible

6. Monitor After Release

After releasing:

1. Watch execution success rate
2. Review any errors immediately
3. Check execution duration
4. Verify outputs are correct

Version History

Viewing History

Access version history:

1. Open workflow
2. Click "Version History"
3. View all versions with metadata
4. Select version to view details

History Information

Multi-Environment Patterns

Development Workflow

1. Edit in draft version
2. Test with MANUAL trigger
3. Fix issues
4. Create release candidate
5. Test in staging (if available)
6. Release to production

Hotfix Workflow

For urgent fixes:

1. Identify issue in released version
2. Create new version from released
3. Apply minimal fix
4. Test fix
5. Release immediately
6. Monitor closely
7. Plan comprehensive fix for next version

Troubleshooting

Can't Release Version

Possible causes:

• Validation errors in workflow
• Missing required configuration
• Integration not connected

Solution:

1. Review validation errors
2. Fix configuration issues
3. Test before releasing

Wrong Version Triggering

Possible cause: Multiple Active versions

Solution:

1. Check version states
2. Ensure only one version is Active
3. Verify correct version is Active

Lost Changes

Possible cause: Didn't save before creating new version

Solution:

1. Check revision history
2. Look at previous version
3. Recreate changes if needed

Execution Using Old Version

Possible cause: Execution started before release

Solution:

• This is expected behavior
• Executions complete on their bound version
• New events use new version

Related

• Workflow Design
• Testing & Debugging
• Monitoring & Logs