Scenario versioning: why it exists and how it works

Why version history matters

A bot scenario is a living document. Teams change it often: new branches, updated messages, keyboard logic. Over time it becomes hard to answer simple questions:

• Who removed the “Back to menu” button last week?
• What did the scenario look like before the campaign launch?
• Can we go back to a version that worked reliably?

Versioning addresses this. Each published save is a snapshot you can return to.

What a version is

A version is an immutable snapshot of the whole scenario: all sections, nodes, edges, and translations. A new snapshot is created when you publish the scenario ( Publish button and save dialog).

Compared to primary scenario data, each snapshot is compact (diff-oriented storage of the graph structure).

What is stored in a version

Version lifecycle

Scenario edits
     ↓
Publish (toolbar) with comment dialog
     ↓
Engine writes a new log record
     │
     ├── description (comment, if any)
     ├── constructor_user_email (author)
     ├── createdAt (time)
     └── json_layout (full graph for the new editor)
     ↓
Version appears in Version history

Important: a new history entry appears after publish through the save dialog, not on every click while editing.

How versions relate to the “current” scenario

There is only one live version — the one loaded while you work in Scenario Builder. All other snapshots are archived and do not affect live bot execution.

When you restore an older snapshot:

1. The system loads that snapshot’s graph.
2. Publishes it as the new current state.
3. Writes a new archive entry (so you can undo the “undo”).

Who can see versions

Viewing and restoring are controlled by the same permission as saving the scenario (scenario.sections.scenario.canSave). If you can publish the scenario, you can open history and restore.

Team practices

Always add a comment when publishing

An empty comment loses context. Even “Updated welcome texts” helps.

Good comments:

• “Added section for complaint handling”
• “Removed Back button from node 55”
• “Fixed condition: order status check now correct”

Poor comments:

• “Changes”
• “Fix”
• (empty)

Create checkpoints before major refactors

Publish the current state with “Checkpoint before FAQ redesign”. If something goes wrong, you know exactly where to roll back.

Preview before restore

Use preview mode to confirm the snapshot is correct. Restoring is safe for the archive (the previous state remains), but unnecessary restores add noise.

Technical notes (administrators)

• History records are stored in the instance database (MongoDB collection kw_save_bots_logs).
• For a record to appear in Version history in the new editor, it must include the full graph in the new format. If the administrator has not enabled the corresponding storage for the instance, older records may only contain the legacy format and will not show in this list.
• The UI loads a limited batch of entries per request; more load as you scroll.