Canvas Version History
Canvas uses a Salesforce-style versioning system where users stay on the version they started, ensuring a consistent experience throughout their journey. When you publish a new version, only new users entering the canvas use it - existing users continue on their original version.
How Versioning Works
The Version Lifecycle
Draft (editable) → Published (immutable) → Archived (read-only)
- Draft: You can freely edit the canvas. Changes are saved automatically.
- Published: When you publish, a new version is created. Published versions are immutable.
- Archived: When a new version is published, the previous version becomes archived. Archived versions remain active for users still in the journey.
What Happens When You Publish
When you click Publish:
-
Your current draft is automatically saved first - any nodes you added or edits you made are persisted before the publish snapshot is taken. (Previously, publishing without a manual save could snapshot a stale state and "lose" newly-added nodes in the published version. This is now fixed: publish is gated on a successful save.)
-
A new version snapshot is created containing:
- All nodes and edges (the flow structure)
- Entry trigger configuration
- Canvas settings
- Template versions (pinned at publish time)
-
The previous published version becomes archived
-
New users entering the canvas use the new version
-
Existing users continue on their original version until they complete
Version Pinning
When a user enters a canvas, they are pinned to the current published version:
| User State | What Happens on New Version Publish |
|---|---|
| Just entered | Uses new version (if they enter after publish) |
| In a delay node | Continues on their original version |
| Waiting for event | Continues on their original version |
| Processing message | Continues on their original version |
This ensures users never experience unexpected changes mid-journey.
Publishing a New Version
Step 1: Make Your Changes
Edit your canvas in draft mode:
- Add, remove, or modify nodes
- Update message content
- Change delay times
- Modify branching logic
All changes are auto-saved to your draft.
Step 2: Review Changes
Before publishing, review what's changed:
- Click the Version History icon in the canvas header
- Select Compare with Published
- Review the visual diff showing:
- Added nodes (green)
- Removed nodes (red)
- Modified nodes (yellow)
Step 3: Publish
- Click Publish in the canvas header
- Add a Change Summary describing what changed (optional but recommended)
- Confirm the publish
Version 3 published at 2024-01-15 14:30
Change Summary: "Added 3-day follow-up email and updated discount to 20%"
Published by: john@company.com
Version History Panel
Access the version history by clicking the clock icon in the canvas header.
Version List
See all versions with:
- Version number (v1, v2, v3...)
- Publish date and time
- Who published it
- Change summary
- Status (Published, Archived)
Version Stats
Each version tracks its own analytics:
| Metric | Description |
|---|---|
| Total Entries | Users who entered on this version |
| Active Users | Users currently in the canvas |
| Completed | Users who reached the exit |
| Exited Early | Users who left before completing |
| Failed | Users whose journey failed due to errors |
| Conversion Rate | % who completed the primary goal |
| Avg Completion Time | Average time from entry to reaching the end node |
| Avg Time to Convert | Average time from entry to conversion event |
Understanding Time Metrics
Avg Completion Time measures how long users take to complete the entire canvas journey (from entry to the END node). This includes all delays and wait times.
Avg Time to Convert measures how long it takes users to trigger a conversion event (e.g., make a purchase, sign up). This is often faster than completion time because users can convert early in the journey.
Example:
├── User enters canvas at Day 0
├── Receives welcome email
├── Makes purchase on Day 0.5 ← Conversion (Time to Convert: 12 hours)
├── Continues through canvas
├── Gets follow-up email on Day 3
└── Reaches END node on Day 3 ← Completion (Completion Time: 3 days)
- High completion time + Low conversion time = Users convert quickly but journey continues (good for nurturing)
- Similar times = Users convert near the end of the journey
- No conversion data = No conversion events tracked yet
Compare Versions
Select two versions to compare:
- See visual diff of the flow structure
- Compare performance metrics side-by-side
- Identify which version performs better
Rollback to Previous Version
If a new version isn't performing well, you can rollback:
- Open Version History
- Find the version you want to restore
- Click Rollback to This Version
- Confirm the rollback
Rollback creates a new version with the old content. It doesn't delete the current version. Users on the current version continue their journey.
Example:
- v1 → Original
- v2 → Changed discount to 25%
- v3 → Rollback to v1 (same content as v1, new version number)
Template Versioning
Templates (email, SMS, push, in-app) are also versioned and pinned when you publish a canvas.
How It Works
- You edit an email template
- You publish the template (creates template version)
- When you publish the canvas, it captures the current template versions
- Users on that canvas version always see those template versions
Editing Templates
When you edit a template used in an active canvas:
| Scenario | What Happens |
|---|---|
| Edit template, don't publish | Draft changes only - active users see old version |
| Publish template | Creates new template version |
| Publish canvas | New canvas version uses new template version |
| Old canvas version | Still uses old template version |
This prevents accidental changes from affecting users mid-journey.
Orphaned Executions
When all versions are archived except the current one, some users may be on orphaned versions:
Orphaned: A user is on a version that's no longer the published version and has been archived.
What happens to orphaned users:
- They complete their journey on the archived version
- All nodes and logic remain available
- Analytics continue to be tracked for their version
- No changes can be made to their version
You can see orphaned users in the Canvas Executions tab with a warning indicator.
Force Migrate (Admin Only)
In rare cases (e.g., urgent bug fixes), admins can force-migrate users to a new version:
- Open Version History
- Click Migration Options
- Select users to migrate (or migrate all compatible)
- Confirm migration
Migration Compatibility
Not all users can be migrated. The system checks:
- Node exists: User's current node exists in new version
- Node type unchanged: Node type (delay, message, etc.) is the same
- Valid path: There's a valid path from current position
Migration Results:
- Migrated: Successfully moved to new version
- Incompatible: Can't migrate - continues on old version
Force migration should only be used for critical fixes. Users may experience confusion if their journey suddenly changes.
Analytics Per Version
Each version maintains separate analytics:
Version-Specific Metrics
Version 2 Analytics (Published: Jan 10)
├── Total Entries: 15,234
├── Active: 3,456
├── Completed: 8,123 (67%)
├── Exited: 3,655 (24%)
├── Failed: 0
├── Conversion Rate: 45.2%
├── Avg. Completion Time: 12.4 days
└── Avg. Time to Convert: 2.3 days
Version 3 Analytics (Published: Jan 15)
├── Total Entries: 2,341
├── Active: 1,892
├── Completed: 312 (13%)
├── Exited: 137 (6%)
├── Failed: 0
├── Conversion Rate: 28.1%
├── Avg. Completion Time: 2.1 days (in progress)
└── Avg. Time to Convert: 4.5 hours
Comparing Performance
Use version analytics to:
- A/B test changes: Compare conversion rates between versions
- Identify improvements: See if a change improved completion rates
- Diagnose issues: Find if a change caused drop-off
Audit Trail
All version actions are logged:
| Action | What's Recorded |
|---|---|
| Publish | Who published, when, change summary |
| Rollback | Who rolled back, to which version |
| Archive | When version was archived |
| Migrate | Who initiated, how many users affected |
View the audit trail in Settings > Audit Log or in the version history panel.
Best Practices
1. Write Clear Change Summaries
Good: "Added reminder email at day 7, increased discount from 15% to 20%"
Bad: "Updated canvas"
2. Review Before Publishing
- Compare with current version
- Check affected templates
- Review analytics of current version
3. Test Significant Changes
For major changes:
- Create a test canvas
- Validate the flow
- Then apply to production
4. Monitor After Publishing
After publishing a new version:
- Check entry rate is normal
- Monitor early completion metrics
- Watch for increased exits
5. Use Rollback Sparingly
Rollback when:
- Critical bug discovered
- Significant drop in performance
- Wrong content published
Don't rollback for:
- Minor typos (just publish a fix)
- Normal performance variations
Version Limits
| Limit | Value |
|---|---|
| Versions per canvas | Unlimited |
| Archived version retention | Until all executions complete |
| Audit log retention | 1 year |
Segment Filtering Options
When creating segments or targeting users, you can filter based on canvas version:
Filter by Canvas Version
In segment builder or canvas analytics:
Canvas Version filters:
├── On specific version (e.g., v2)
├── On latest version
├── On archived version (orphaned users)
├── Entered before version X
└── Entered after version X
Use Cases
Target users on old version:
Segment: "Users on Canvas v1"
Filter: canvas_version = 1 AND canvas_id = "onboarding-flow"
Use: Notify about upcoming changes or offer to restart
Target orphaned users:
Segment: "Orphaned Canvas Users"
Filter: version_status = "orphaned"
Use: Send notification about their journey status