---
title: "Scenario version history: why it exists and how it works"
description: "Reference-style overview of scenario snapshots, stored data, constants, and permissions in Scenario Builder."
---

# 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

| Component | Stored? |
|-----------|---------|
| All sections and their names | ✅ |
| All nodes and parameters | ✅ |
| All edges and handles | ✅ |
| Translations | ✅ |
| Bot variables | ✅ |
| Bot constants | ⚠️ Current values only; constants are not versioned separately |
| Save comment | ✅ |
| Author | ✅ |
| Timestamp | ✅ |

---

## 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.