Back to Documentation

File Versioning System

Introduction

Sutram's File Versioning System provides a collaborative workflow for managing document revisions in your projects. Inspired by traditional engineering document control practices, it allows teams to track changes, maintain revision history, and ensure only one person edits a file at a time.

When to Use Versioning

Use versioning for files that:

  • Require formal revision tracking (contracts, specifications, drawings)
  • Are edited by multiple team members
  • Need approval workflows before publication
  • Require an audit trail of changes

Files that typically don't need versioning:

  • Reference materials that don't change
  • Exported reports or snapshots
  • Media files (images, videos)

Key Concepts

File Types

Every file in Sutram is either a Reference file or an Editable file:

Type Description Versioning
Reference Standard files without version control. Anyone with edit permissions can replace the file at any time. Disabled
Editable Files with version control enabled. Requires check-out before editing and supports formal versioning. Enabled

By default, all uploaded files are Reference files. You can enable versioning on any file.

Lifecycle Status

Editable files have a lifecycle status that indicates their current state:

Status Description
Draft Work in progress. Can be edited via check-out/check-in. Not yet formally released.
Published Formally released version. Creates a permanent snapshot in version history.

Check-out/Check-in

The check-out/check-in system ensures only one person can edit a file at a time:

  • Check-out: Reserves the file for your exclusive editing. Others can view but not modify.
  • Check-in: Returns the file with your changes. Requires uploading a new version of the file.

This prevents conflicting edits and ensures a clear record of who made changes.

Versions

When you publish a file, Sutram creates a permanent snapshot called a Version. Versions are numbered sequentially (v1, v2, v3...) and cannot be modified or deleted. This provides:

  • Complete revision history
  • Ability to download any previous version
  • Clear audit trail of published releases

Getting Started

Enabling Versioning on a File

To enable versioning on an existing file:

  1. Navigate to your project's Content tab
  2. Find the file you want to enable versioning on
  3. Click the ... (more options) menu
  4. Select "Enable versioning"

The file will become an Editable file in Draft status.

Note: Only project Owners and Members can enable versioning.

Disabling Versioning

To disable versioning and convert back to a Reference file:

  1. Ensure the file is not checked out
  2. Click the ... menu on the file
  3. Select "Disable versioning"

Warning: Disabling versioning removes the ability to use check-out/check-in, but does not delete version history.

Check-out/Check-in Workflow

Step 1: Check Out a File

Before editing an editable file, you must check it out:

  1. Click the ... menu on the file
  2. Select "Check out for editing"
  3. The file is now reserved for your exclusive editing

Once checked out:

  • The file shows a "Checked out by [Your Name]" badge
  • Other users can view but cannot check out the file
  • You can download the current version to edit locally

Step 2: Edit the File Locally

  1. Download the current file from Sutram
  2. Make your changes using appropriate software (Word, AutoCAD, etc.)
  3. Save the modified file on your computer

Step 3: Check In with Your Changes

When you're ready to save your changes:

  1. Click the ... menu on the file
  2. Select "Check in"
  3. A dialog appears asking you to upload your modified file
  4. Drag and drop or click to select your updated file
  5. Wait for the upload to complete

Important: The replacement file must have the same extension as the original (e.g., .docx files must be replaced with .docx files).

Canceling a Check-out

If you decide not to make changes:

  1. Click the ... menu on the checked-out file
  2. Select "Cancel check-out"

This releases the file without any changes. The file returns to its previous state.

Undoing a Check-in

Made a mistake? If a backup is available:

  1. Click the ... menu on the file
  2. Select "Undo check-in"
  3. The previous version is restored

Note: Undo is only available if a backup exists (typically immediately after check-in). Once you check out and check in again, the previous backup is overwritten.

Force Releasing a Lock (Owners Only)

If a team member has a file checked out but is unavailable:

  1. As the Project Owner, click the ... menu
  2. Select "Force release lock"

This immediately releases the lock. Any unsaved changes by the original user will be lost.

Use with caution: Only use this when necessary, as it may cause work to be lost.

Version Management

Publishing a Version

When a draft is ready for formal release:

  1. Ensure the file is not checked out
  2. Click the ... menu
  3. Select "Publish version"

This creates a permanent snapshot:

  • Version number increments (v1 → v2 → v3...)
  • The snapshot is stored in version history
  • The file status changes to Published

Note: Only Project Owners can publish versions.

Creating a New Version from Published

To continue editing a published file:

  1. Click the ... menu on a Published file
  2. Select "Create new version"

This:

  • Creates a new Draft from the published version
  • Increments the version number
  • Allows you to check out and make changes

Viewing Version History

To see all published versions:

  1. Click on the file to open it
  2. Click "Version History" in the viewer
  3. A timeline shows all published versions with:
    • Version number
    • Publication date
    • Who published it

Downloading Previous Versions

From the Version History modal:

  1. Find the version you need
  2. Click the download icon next to that version
  3. The historical file downloads to your computer

This is useful for:

  • Comparing changes between versions
  • Reverting to a previous design
  • Audit and compliance needs

Permissions and Roles

Different project roles have different versioning capabilities:

Action Owner Admin Member Viewer
View files & versions Yes Yes Yes Yes
Download versions Yes Yes Yes Yes
Enable/disable versioning Yes Yes Yes No
Check out files Yes Yes Yes No
Check in files Yes Yes Yes No
Cancel own check-out Yes Yes Yes No
Undo check-in Yes Yes Yes No
Publish versions Yes No No No
Create new version Yes No No No
Force release lock Yes No No No

Key Points:

  • Only Owners can publish versions and create new versions
  • Only Owners can force release locks from other users
  • Viewers can only view and download, not edit

Visual Indicators

Status Badges

Editable files display badges showing their current state:

Badge Meaning
Draft (amber) File is a work in progress, not yet published
Published (indigo) File has been formally published as a version
Checked out by [Name] (warning) File is locked for editing by the indicated user

Identifying Locked Files

When a file is checked out:

  • A lock icon appears in the file list
  • The badge shows who has it checked out
  • The check-out option is hidden (file is unavailable)

Your Own Check-outs

When you have a file checked out:

  • The "Check in" option appears in the menu
  • The "Cancel check-out" option is available
  • Other users see that you have it locked

Best Practices

When to Enable Versioning

Enable versioning for:

  • Engineering drawings and specifications
  • Contracts and legal documents
  • Project plans and schedules
  • Any document requiring formal sign-off

Avoid versioning for:

  • Frequently updated working files
  • Reference images or media
  • Exported reports (create new files instead)

Publishing Workflow

Recommended workflow for formal documents:

  1. Create/Upload: Add the initial file to the project
  2. Enable Versioning: Convert to editable file
  3. Work in Draft: Make edits via check-out/check-in
  4. Review: Share draft with team for feedback
  5. Publish: When approved, publish as formal version
  6. Iterate: Create new version for future changes

Team Coordination Tips

  • Communicate: Let your team know when you check out files
  • Don't hoard: Check in files promptly when done
  • Regular publishing: Publish stable versions regularly, not just at milestones
  • Use comments: Add context in project chat when publishing major changes

Frequently Asked Questions

Q: Can I edit a file without checking it out?

A: For Reference files, yes. For Editable files, no - you must check out first. This ensures only one person edits at a time.

Q: What happens if I forget to check in a file?

A: The file remains locked to you until you check in or cancel. If you become unavailable, the Project Owner can force release the lock.

Q: Can I delete a published version?

A: No. Published versions are permanent for audit purposes. You can create new versions, but history is preserved.

Q: What's the difference between versions and file history?

A: Versions are formal, numbered snapshots created by publishing. Each version is permanent and downloadable. Check-ins without publishing update the working copy but don't create numbered versions.

Q: Can multiple people check out the same file?

A: No. Only one person can have a file checked out at a time. This is by design to prevent conflicting edits.

Q: Do I lose my changes if someone force releases my lock?

A: Yes, any changes not checked in will be lost. Always check in regularly. Force release should only be used when necessary.

Q: Can I enable versioning on CAD files?

A: Yes! Versioning works with any file type - CAD drawings, Office documents, PDFs, and more.

Troubleshooting

"File is already checked out"

Problem: You cannot check out a file because someone else has it.

Solution:

  1. Check the badge to see who has it checked out
  2. Contact them to coordinate
  3. If urgent and they're unavailable, ask the Project Owner to force release

"You don't have this file checked out"

Problem: You're trying to check in but don't have the file checked out.

Solution: Check out the file first, then make your changes and check in.

"File must have extension: .xyz"

Problem: You're trying to check in a file with a different extension.

Solution: Ensure your replacement file has the same extension as the original. For example, a .docx file must be replaced with another .docx file.

"Only the project owner can publish files"

Problem: You don't have permission to publish.

Solution: Ask the Project Owner to publish the version, or request they upgrade your role.

Check-in upload fails

Problem: The upload during check-in doesn't complete.

Solution:

  1. Check your internet connection
  2. Ensure the file isn't too large (check project limits)
  3. Try again with a smaller file or better connection
  4. If persistent, contact support

Version history not showing

Problem: You can't see version history for a file.

Solution: Version history only appears for files that have been published at least once. If the file is still in Draft and has never been published, there's no version history yet.

Document Version: 1.0 Last Updated: November 2025 Author: Sutram Development Team

Back to Documentation