Help & Documentation

Learn how to use StructureGram

Restoring Diagram Versions

Restoring a version loads a saved snapshot back into your working copy, allowing you to return to previous configurations or compare different layouts.

How to Restore a Version

  1. Open your diagram (Ownership View or Family Tree)
  2. Click the Versions button in the toolbar
  3. Find the version you want to restore in the list
  4. Click on the version name
  5. Follow the restore prompt (see below)
  6. The version is loaded into your working copy

Understanding Restore Behavior

Restoring a version:

  • Replaces your working copy with the version's state
  • Persists the change (saves the restored state as the new working copy)
  • Changes the diagram scope if the version had different entities
  • Updates all settings including snapshot dates, hidden entities, etc.
  • Resets dirty state (working copy is clean after restore)

After restoring, you're editing the restored configuration. Any new changes will be relative to that restored state.

The Dirty State Check

Before restoring, StructureGram checks if you have unsaved changes (dirty state):

Clean Working Copy (No Unsaved Changes)

If your working copy is clean (all changes saved):

  • Restore happens immediately
  • No confirmation prompt
  • The version loads instantly

Dirty Working Copy (Unsaved Changes)

If you have unsaved changes, you'll see three options:

  1. Save Version & Switch

    • Creates a version from your current canvas
    • Then loads the selected version
    • Use when: You want to keep your current work before switching
    • Result: You don't lose anything

  2. Discard & Switch

    • Abandons your unsaved changes
    • Loads the selected version
    • Use when: You don't care about current changes
    • Result: Current changes are lost

  3. Cancel

    • Closes the dialog
    • Nothing happens
    • Use when: You need to review your changes first

Recommendation: Unless you're certain you don't need your current changes, always choose "Save Version & Switch" to be safe.

What Gets Restored?

Restoring loads the complete saved state:

Visual Elements

  • All node positions and sizes
  • Link routing and vertices
  • Link label positions
  • Viewport zoom and pan
  • Legend position and visibility

Presentation Settings

  • Hidden entities (visibility)
  • Custom colors
  • Layout algorithm
  • Routing settings

Scope Configuration

  • Entity list (which entities are in the diagram)
  • Filter group reference
  • Snapshot date/range settings
  • Scope template reference

Important: If the version has a different entity list than your current diagram, the diagram will rebuild with the version's entities.

Scope Changes During Restore

One of the most powerful aspects of version restore is scope restoration:

Example: Restoring Historical Entity Lists

Current state: Diagram with Companies A, B, C, D, E, F (6 entities)

You restore: Version "Q1 2024" which had only A, B, C (3 entities)

Result: Diagram now shows only A, B, C

The entity list is restored to match the version. This allows you to view historical configurations exactly as they were.

Scope Change Confirmation

When restoring a version with a different entity count, you'll see:

Restoring will change scope from 6 to 3 entities

This helps you understand the impact before proceeding.

After Restoring

Once a version is restored:

  1. The canvas updates to show the restored configuration
  2. Your working copy is now the restored state
  3. The dirty state is reset (working copy is clean)
  4. You can immediately continue editing from this restored state
  5. The original version remains unchanged (still immutable)

Common Restore Scenarios

Return to a Previous Layout

Scenario: You rearranged everything and want to go back

  1. Find the version with the good layout
  2. Restore it
  3. Continue from there or just view it

Compare Two Configurations

Scenario: You want to compare two approaches

  1. View current diagram
  2. Restore old version to see that approach
  3. Take notes or screenshot
  4. Restore back to recent version if needed

Recover from Mistakes

Scenario: You made changes you regret

  1. Find the last good version
  2. Restore it (use "Discard & Switch" if you don't want the bad changes)
  3. Continue from the good state

Switch Between Presentation Modes

Scenario: You have versions for different audiences

  1. Before detailed meeting: Restore "Detailed view" version
  2. Before executive presentation: Restore "Executive summary" version
  3. Each restore gives you the appropriate configuration

Concurrent Editing Protection

StructureGram protects against concurrent edits:

  • Each working copy write (including restore) uses optimistic concurrency
  • If someone else saved changes while you were working, you'll get a conflict warning
  • The system uses ETag headers to detect out-of-date writes

Handling Conflicts (409 Error)

If you see: "Conflict: Diagram was updated by another user"

  1. Your restore was blocked to prevent data loss
  2. Another team member (or another tab) saved changes
  3. Resolution options:
    • Reload the diagram to see current state
    • Review the changes
    • Retry your restore if still appropriate
    • Save your state as a version first if needed

This prevents silently overwriting someone else's work.

Limitations and Considerations

Entities Must Still Exist

If a version references entities that have been deleted from the database:

  • Those entities will be silently omitted
  • The diagram may look different than the original save
  • Relationships to deleted entities won't appear

Shared vs. Version-Specific Scope

The current implementation:

  • Versions capture scope references (entity filter IDs)
  • Recent updates have improved scope immutability
  • Future versions will have fully frozen entity lists

No Diff/Compare UI

StructureGram doesn't show visual diffs between versions. To compare:

  1. Restore version A and review/screenshot
  2. Restore version B and compare
  3. Manually note differences

Restore vs. Promote

Restore: Replaces your current working copy Promote: Creates a new separate diagram

Use restore when:

  • ✅ You want to continue working from this version
  • ✅ You want to replace your current work
  • ✅ You want to "undo" to a previous state

Use promote when:

  • ✅ You want to keep both as separate diagrams
  • ✅ You want to create variants
  • ✅ You want permanent preservation beyond 15-version limit

Troubleshooting

"Restore doesn't show the version I expected"

  • The version may have been saved with different scope settings
  • Check the entity count in version metadata
  • Entities referenced in the version may have been deleted

"I restored and lost my current work"

  • You chose "Discard & Switch" instead of "Save Version & Switch"
  • Always save before discarding unless you're certain
  • Check if you can restore a recent version that has your work

"Restore is slow"

  • Restoring rebuilds the entire diagram from the database
  • Large scopes (many entities) take longer
  • Scope changes require fetching new data
  • This is normal for complex diagrams

"Restore failed with error"

  • May be a conflict with another user's changes
  • Reload the diagram to see current state
  • Check network connection
  • Try again after reviewing current state

Next Steps